murex rocks

Welcome

About

Install

Change Log

Blog

Technical Docs

Language Tour

Interactive Shell

Rosetta Stone

User Guide

Open Source

Discuss

Contribute

Source Code

Search Site

User Guide

This section contains miscellaneous documents on using and configuring the shell and Murex’s numerous features.

Table of Contents

Language Tour

The Language Tour is a great introduction into the Murex language.

User Guides

• ANSI Constants: Infixed constants that return ANSI escape sequences
• Bang Prefix: Bang prefixing to reverse default actions
• Code Block Parsing: Overview of how code blocks are parsed
• FileRef: How to track what code was loaded and from where
• Hint Text: A status bar for your shell
• Integrations: Default integrations shipped with Murex
• Interactive Shell: What’s different about Murex’s interactive shell?
• Job Control: How to manage jobs with Murex
• Modules And Packages: Modules and packages: An Introduction
• Named Pipes: A detailed breakdown of named pipes in Murex
• Operators And Tokens: All supported operators and tokens
• Pipeline: Overview of what a “pipeline” is
• Profile Files: A breakdown of the different files loaded on start up
• Reserved Variables: Special variables reserved by Murex
• Rosetta Stone: A tabulated list of Bashism’s and their equivalent Murex syntax
• Schedulers: Overview of the different schedulers (or ‘run modes’) in Murex
• Strict Types In Expressions: Expressions can auto-convert types or strictly honour data types
• Terminal Hotkeys: A list of all the terminal hotkeys and their uses
• Variable And Config Scoping: How scoping works within Murex
• Working With Arrays: Examples using arrays within Murex

Operators And Tokens

• ( expression ): Inline expressions
• C-style functions: Inlined commands for expressions and statements
• Filter By Range: [ ..Range ]: Outputs a ranged subset of data from stdin
• Get Item Property: [ Index ]: Outputs an element from an array, map or table
• Get Nested Element: [[ Element ]]: Outputs an element from a nested structure
• Read / Write To A Named Pipe: <pipe>: Reads from a Murex named pipe
• Read From Stdin: <stdin>: Read the stdin belonging to the parent code block
• Write File (Append): >>: Writes stdin to disk - appending contents if file already exists
• Write File (Truncate): >: Writes stdin to disk - overwriting contents if file already exists
• "Double Quote": Initiates or terminates a string (variables expanded)
• $Scalar Sigil (eg variables): Expand values as a scalar
• %(Brace Quote): Initiates or terminates a string (variables expanded)
• %[] Array Builder: Quickly generate arrays
• %{} Object Builder: Quickly generate objects (dictionaries / maps)
• && And Logical Operator: Continues next operation if previous operation passes
• 'Single Quote': Initiates or terminates a string (variables not expanded)
• (brace quote): Write a string to the stdout without new line (deprecated)
• *= Multiply By Operator: Multiplies a variable by the right hand value (expression)
• * Multiplication Operator: Multiplies one numeric value with another (expression)
• += Add With Operator: Adds the right hand value to a variable (expression)
• + Addition Operator: Adds two numeric values together (expression)
• -= Subtract By Operator: Subtracts a variable by the right hand value (expression)
• -> Arrow Pipe: Pipes stdout from the left hand command to stdin of the right hand command
• - Subtraction Operator: Subtracts one numeric value from another (expression)
• /= Divide By Operator: Divides a variable by the right hand value (expression)
• / Division Operator: Divides one numeric value from another (expression)
• <~ Assign Or Merge: Merges the right hand value to a variable on the left hand side (expression)
• => Generic Pipe: Pipes a reformatted stdout stream from the left hand command to stdin of the right hand command
• ?: Elvis Operator: Returns the right operand if the left operand is falsy (expression)
• ?? Null Coalescing Operator: Returns the right operand if the left operand is empty / undefined (expression)
• @Array Sigil: Expand values as an array
• [{ Lambda }]: Iterate through structured data
• { Curly Brace }: Initiates or terminates a code block
• | POSIX Pipe: Pipes stdout from the left hand command to stdin of the right hand command
• || Or Logical Operator: Continues next operation only if previous operation fails
• ~ Home Sigil: Home directory path variable

Builtin Commands

Standard Builtins

• ASCII And ANSI Escape Sequences: key-code: Returns character sequences for any key pressed (ie sent from the terminal)
• Add Heading: addheading: Adds headings to a table
• Add Prefix: prefix: Prefix a string to every item in a list
• Add Suffix: suffix: Prefix a string to every item in a list
• Alias “shortcut”: alias: Create an alias for a command
• Alter Data Structure: alter, ~>: Change a value within a structured data-type and pass that change along the pipeline without altering the original source input
• Array Append: append: Add data to the end of an array
• Array Merge To String: mjoin: Joins a list or array into a single string
• Array Prepend: prepend: Add data to the start of an array
• Array Reverse: mtac: Reverse the order of an array
• Array Sort: msort: Sorts an array - data type agnostic
• Background Process: bg: Run processes in the background
• CPU Architecture: cpuarch: Output the hosts CPU architecture
• CPU Count: cpucount: Output the number of CPU cores available on your host
• Caught Error Block: catch: Handles the exception code raised by try or trypipe
• Change Directory: cd: Change (working) directory
• Change Text Case: list.case: Changes the character case of a string or all elements in an array
• Check Builtin Exists: bexists: Check which builtins exist
• Command Line History: history: Outputs murex’s command history
• Count: count: Count items in a map, list or array
• Create 2d Array: 2darray: Create a 2D JSON array from multiple input sources
• Create JSON Array: ja: A sophisticated yet simply way to build a JSON array
• Create Map: map: Creates a map from two data sources
• Create Named Pipe: pipe: Manage Murex named pipes
• Create New Array: ta: A sophisticated yet simple way to build an array of a user defined data-type
• Create Streamable Array: a: A sophisticated yet simple way to stream an array or list (mkarray)
• Create Temporary File: tmp: Create a temporary file and write to it
• Date And Time Conversion: datetime: A date and/or time conversion tool (like printf but for date and time values)
• Debug Mode: debug: Debugging information
• Define Environmental Variable: export: Define an environmental variable and set it’s value
• Define Function Arguments: args: Command line flag parser for Murex shell scripting
• Define Global: global: Define a global variable and set it’s value
• Define Handlers For “open” (openagent): Creates a handler function for open
• Define Method Relationships (method): Define a methods supported data-types
• Define Type: cast: Alters the data-type of the previous function without altering its output
• Define Variable: set: Define a variable (typically local) and set it’s value
• Disable Error Handling In Block: unsafe: Execute a block of code, always returning a zero exit number
• Display Command Type: type: Command type (function, builtin, alias, etc)
• Display Running Functions: fid-list: Lists all running functions within the current Murex session
• Download File: getfile: Makes a standard HTTP request and return the contents as Murex-aware data type for passing along Murex pipelines.
• Error String, strerr: err: Print a line to the stderr
• Escape Command Line String: esccli: Escapes an array so output is valid shell code
• Escape HTML: eschtml: Encode or decodes text for HTML
• Escape URL: escurl: Encode or decodes text for the URL
• Execute External Command: exec: Runs an executable
• Execute Function or Builtin: fexec: Execute a command or function, bypassing the usual order of precedence.
• Exit Code: exitnum: Output the exit number of the previous process
• Exit Function: return: Exits current function scope
• Exit Murex: exit: Exit murex
• Exit Scope: break: Terminate execution of a block within your processes scope
• Expressions: expr: Expressions: mathematical, string comparisons, logical operators
• False: false: Returns a false value
• Filesystem Objects: f: Lists or filters file system objects (eg files)
• Filesystem Regex Match: rx: Regexp pattern matching for file system objects (eg .*\\.txt)
• For Each In Map: formap: Iterate through a map or other collection of data
• For Each In array: foreach: Iterate through an array
• For Loop: for: A more familiar iteration loop to existing developers
• Foreground Process: fg: Sends a background process into the foreground
• Function / Module Defaults: runmode: Alter the scheduler’s behaviour at higher scoping level
• Generate Random Sequence: rand: Random field generator
• Get Data Type: get-type: Returns the data-type of a variable or pipe
• Get Pipe Status: pt: Pipe telemetry. Writes data-types and bytes written
• Globbing: g: Glob pattern matching for file system objects (eg *.txt)
• HTTP(S) Get Request: get: Makes a standard HTTP request and returns the result as a JSON object
• HTTP(S) Post Request: post: HTTP POST request with a JSON-parsable return
• If Conditional: if: Conditional statement to execute different blocks of code depending on the result of the condition
• Include / Evaluate Murex Code: source: Import Murex code from another file or code block
• Is Value Null: is-null: Checks if a variable is null or undefined
• Kill All In Session: fid-killall: Terminate all running Murex functions in current session
• Kill Function: fid-kill: Terminate a running Murex function
• Left Sub-String: left: Left substring every item in a list
• List object keys: struct-keys: Outputs all the keys in a structure as a file path
• Location / Type Of Command: which: Locate command origin
• Lock Files: lockfile: Create and manage lock files
• Logic And Statements: and: Returns true or false depending on whether multiple conditions are met
• Logic Or Statements: or: Returns true or false depending on whether one code-block out of multiple ones supplied is successful or unsuccessful.
• Loop While: while: Loop until condition false
• Man-Page Summary: man-summary: Outputs a man page summary of a command
• Murex Event Subsystem: event: Event driven programming for shell scripts
• Murex Package Manager: murex-package: Murex’s package manager
• Murex Version: version: Get Murex version
• Murex’s Offline Documentation: murex-docs: Displays the man pages for Murex builtins
• Next Iteration: continue: Terminate process of a block within a caller function
• Not: !: Reads the stdin and exit number from previous process and not’s it’s condition
• Null: null: null function. Similar to /dev/null
• Open File: open: Open a file with a preferred handler
• Operating System: os: Output the auto-detected OS name
• Output String, stdout: out: Print a string to the stdout with a trailing new line character
• Output With Type Annotation: tout: Print a string to the stdout and set it’s data-type
• Parse Man-Page For Flags: man-get-flags: Parses man page files for command line flags
• Parse Murex Source: murex-parser: Runs the Murex parser against a block of code
• Pipe Fail: trypipe: Checks for non-zero exits of each function in a pipeline
• Prettify Objects: pretty: Prettifies data documents to make it human readable
• Private Function: private: Define a private function block
• Processes Execution Time: time: Returns the execution run time of a command or block
• Public Function: function: Define a function block
• Quote String: escape: Escape or unescape input
• Re-Scan $PATH For Executables: Forces Murex to rescan $PATH looking for executables
• Read User Input: read: read a line of input from the user and store as a variable
• Reformat Data Type: format: Reformat one data-type into another data-type
• Regex Patterns: regexp: Regexp tools for arrays / lists of strings
• Render Image In Terminal: open-image: Renders bitmap image data on your terminal
• Right Sub-String: right: Right substring every item in a list
• Round Number: round: Round a number by a user defined precision
• Send Signal IPC: signal: Sends a signal RPC
• Send pipes to multiple processes: fanout (EXPERIMENTAL): Copies stdin and sends it to multiple pipelines, collating their output
• Set Command Summary Hint: summary: Defines a summary help text for a command
• Shell Configuration And Settings: config: Query or define Murex runtime settings
• Shell Runtime: runtime: Returns runtime information on the internal state of Murex
• Shell Script Tests: test: Murex’s test framework - define tests, run tests and debug shell scripts
• Stderr Checking In Pipes: trypipeerr: Checks state of each function in a pipeline and exits block on error
• Stderr Checking In TTY: tryerr: Handles errors inside a block of code
• String Match: match: Match an exact value in an array
• String Split: jsplit: Splits stdin into a JSON array based on a regex parameter
• Switch Conditional: switch: Blocks of cascading conditionals
• Tab Autocompletion: autocomplete: Set definitions for tab-completion in the command line
• Transformation Tools: tabulate: Table transformation tools
• True: true: Returns a true value
• Try Block: try: Handles non-zero exits inside a block of code

Optional Builtins

These builtins are optional. select is included as part of the default build but can be disabled without breaking functionality. The other optional builtins are only included by default on Windows.

• Inline SQL: select: Inlining SQL into shell pipelines
• !bz2: Decompress a bz2 file
• base64: Encode or decode a base64 string
• gz: Compress or decompress a gzip file
• qr: Creates a QR code from stdin
• sleep: Suspends the shell for a number of seconds

Data Types

• * (generic): generic (primitive)
• bool: Boolean (primitive)
• commonlog: Apache httpd “common” log format
• csv: CSV files (and other character delimited tables)
• float (floating point number): Floating point number (primitive)
• hcl: HashiCorp Configuration Language (HCL)
• int: Whole number (primitive)
• json: JavaScript Object Notation (JSON)
• jsonc: Concatenated JSON
• jsonl: JSON Lines
• num (number): Floating point number (primitive)
• path: Structured object for working with file and directory paths
• paths: Structured array for working with $PATH style data
• str (string): string (primitive)
• toml: Tom’s Obvious, Minimal Language (TOML)
• xml: Extensible Markup Language (XML) (experimental)
• yaml: YAML Ain’t Markup Language (YAML)
• mxjson: Murex-flavoured JSON (deprecated)

Events

• onCommandCompletion: Trigger an event upon a command’s completion
• onFileSystemChange: Add a filesystem watch
• onKeyPress: Custom definable key bindings and macros
• onPreview: Full screen previews for files and command documentation
• onPrompt: Events triggered by changes in state of the interactive shell
• onSecondsElapsed: Events triggered by time intervals
• onSignalReceived: Trap OS signals

Variables

• Numeric (str): Variables who’s name is a positive integer, eg 0, 1, 2, 3 and above
• $., Meta Values (json): State information for iteration blocks
• ARGV (json): Array of the command name and parameters within a given scope
• COLUMNS (int): Character width of terminal
• EVENT_RETURN (json): Return values for events
• HOME (path): Return the home directory for the current session user
• HOSTNAME (str): Hostname of the current machine
• LINES (int): Character height of terminal
• LOGNAME (str): Username for the current session (historic)
• MUREX_ARGV (json): Array of the command name and parameters passed to the current shell
• MUREX_CONFIG_DIR (str): Defines the path to Murex’s config
• MUREX_EXE (path): Absolute path to running shell
• MUREX_HISTORY (str): Defines the path to the .murex_history log
• MUREX_MODULES (str): Defines the path to the modules directory
• MUREX_PRELOAD (str): Defines the path to the .murex_preload script
• MUREX_PROFILE (str): Defines the path to the .murex_profile script
• OLDPWD (path): Return the home directory for the current session user
• PARAMS (json): Array of the parameters within a given scope
• PWDHIST (json): History of each change to the sessions working directory
• PWD (path): Current working directory
• RANDOM (int): Return a random 32-bit integer (historical)
• SELF (json): Meta information about the running scope.
• SHELL (str): Path of current shell
• TMPDIR (path): Return the temporary directory
• USER (str): Username for the current session

Integrations

• ChatGPT: How to enable ChatGPT hints
• Cheat.sh: Cheatsheets provided by cheat.sh
• Kitty Integrations: Get more out of Kitty terminal emulator
• Makefiles / make: make integrations
• Man Pages (POSIX): Linux/UNIX man page integrations
• Spellcheck: How to enable inline spellchecking
• Terminology Integrations: Get more out of Terminology terminal emulator
• direnv Integrations: Directory specific environmental variables
• yarn Integrations: Working with yarn and package.json
• iTerm2 Integrations: Get more out of iTerm2 terminal emulator

API Reference

These API docs are provided for any developers wishing to write their own builtins.

• Marshal() (type): Converts structured memory into a structured file format (eg for stdio)
• ReadArray() (type): Read from a data type one array element at a time
• ReadArrayWithType() (type): Read from a data type one array element at a time and return the elements contents and data type
• ReadIndex() (type): Data type handler for the index, [, builtin
• ReadMap() (type): Treat data type as a key/value structure and read its contents
• ReadNotIndex() (type): Data type handler for the bang-prefixed index, ![, builtin
• Unmarshal() (type): Converts a structured file format into structured memory
• WriteArray() (type): Write a data type, one array element at a time
• lang.ArrayTemplate() (template API): Unmarshals a data type into a Go struct and returns the results as an array
• lang.ArrayWithTypeTemplate() (template API): Unmarshals a data type into a Go struct and returns the results as an array with data type included
• lang.IndexTemplateObject() (template API): Returns element(s) from a data structure
• lang.IndexTemplateTable() (template API): Returns element(s) from a table
• lang.MarshalData() (system API): Converts structured memory into a Murex data-type (eg for stdio)
• lang.UnmarshalData() (system API): Converts a Murex data-type into structured memory