Builtin Commands

This section is a glossary of Murex builtin commands.

Because Murex is loosely modelled on the functional paradigm, it means all language constructs are exposed via functions and those are typically builtins because they can share the Murex runtime virtual machine. However any executable command can also be called from within Murex; be that either via the exec builtin or natively like you would from any Linux, UNIX, or even Windows command prompt.

Other Reference Material

Language Guides

1. Language Tour, which is an introduction into the Murex language.

2. Rosetta Stone, which is a reference table comparing Bash syntax to Murex's.

Murex's Source Code

The source for each of these builtins can be found on Github.

Shell Commands For Querying Builtins

From the shell itself: run builtins to list the builtin command.

If you require a manual on any of those commands, you can run murex-docs to return the same markdown-formatted document as those listed below. eg

murex-docs trypipe

Pages

Input / Output Streams

Commands for managing the flow of data between different processes and/or the terminal screen.

• Create Named Pipe (pipe): Manage Murex named pipes
• Error String (err): Print a line to the stderr
• Get Pipe Status (pt): Pipe telemetry. Writes data-types and bytes written
• Output String (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
• 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
• Read User Input (read): read a line of input from the user and store as a variable
• Read With Type (tread) (removed 7.x): read a line of input from the user and store as a user defined typed variable (deprecated)
• Render Image In Terminal (open-image): Renders bitmap image data on your terminal
• (brace quote): Write a string to the stdout without new line (deprecated)

Filesystem Operations

Commands for working with files and/or the filesystem.

• Create Temporary File (tmp): Create a temporary file and write to it
• Globbing (g): Glob pattern matching for file system objects (eg *.txt)
• List Filesystem Objects (f): Lists or filters file system objects (eg files)
• Lock Files (lockfile): Create and manage lock files
• Open File (open): Open a file with a preferred handler
• Regex Matches (rx): Regexp pattern matching for file system objects (eg .*\\.txt)
• Render Image In Terminal (open-image): Renders bitmap image data on your terminal
• Truncate File (>): Writes stdin to disk - overwriting contents if file already exists

Defined by POSIX

Commands defined by POSIX.

• Alias Pointer (alias): Create an alias for a command
• Change Directory (cd): Change (working) directory
• Display Command Type (type): Command type (function, builtin, alias, etc)
• Expressions (expr): Expressions: mathematical, string comparisons, logical operators
• False (false): Returns a false value
• Location Of Command (which): Locate command origin
• Output String (out): Print a string to the stdout with a trailing new line character
• Processes Execution Time (time): Returns the execution run time of a command or block
• Read User Input (read): read a line of input from the user and store as a variable
• True (true): Returns a true value

List / Array Editing

Commands that operate against a list or array.

• Add Prefix (prefix): Prefix a string to every item in a list
• Add Suffix (suffix): Prefix a string to every item in a list
• Append To List (append): Add data to the end of an array
• Change Text Case (list.case): Changes the character case of a string or all elements in an array
• Count (count): Count items in a map, list or array
• Create JSON Array (ja): A sophisticated yet simply way to build a JSON array
• Create New Array (ta): A sophisticated yet simple way to build an array of a user defined data-type
• Filter By Range [ ..Range ]: Outputs a ranged subset of data from stdin
• For Each In List (foreach): Iterate through an array
• Get Item ([ Index ]): Outputs an element from an array, map or table
• Join Array To String (mjoin): Joins a list or array into a single string
• Left Sub-String (left): Left substring every item in a list
• Match String (match): Match an exact value in an array
• Prepend To List (prepend): Add data to the start of an array
• Reformat Data type (format): Reformat one data-type into another data-type
• Regex Operations (regexp): Regexp tools for arrays / lists of strings
• Reverse Array (mtac): Reverse the order of an array
• Right Sub-String (right): Right substring every item in a list
• Sort Array (msort): Sorts an array - data type agnostic
• Stream New List (a): A sophisticated yet simple way to stream an array or list (mkarray)

String Manipulation

Commands for working with strings.

Several list based tools will also work with strings. Those that can, are included in this sub-section.

• Change Text Case (list.case): Changes the character case of a string or all elements in an array
• Date And Time Conversion (datetime): A date and/or time conversion tool (like printf but for date and time values)
• 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
• Generate Random Sequence (rand): Random field generator
• Left Sub-String (left): Left substring every item in a list
• Prettify JSON: Prettifies JSON to make it human readable
• Quote String (escape): Escape or unescape input
• Reformat Data type (format): Reformat one data-type into another data-type
• Regex Operations (regexp): Regexp tools for arrays / lists of strings
• Right Sub-String (right): Right substring every item in a list
• Split String (jsplit): Splits stdin into a JSON array based on a regex parameter

Numeric / Math Tools

Commands for working with numerical data.

• Expressions (expr): Expressions: mathematical, string comparisons, logical operators
• Generate Random Sequence (rand): Random field generator
• Round Number (round): Round a number by a user defined precision

Structured Data Management

Commands for working with structured data such as maps, tables, arrays and other data formats that are present in documents such as CSV, JSON, YAML, TOML, Sexpr, CSV, etc.

• 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
• Count (count): Count items in a map, list or array
• Create 2d Array (2darray): Create a 2D JSON array from multiple input sources
• Create Map (map): Creates a map from two data sources
• For Each In Map (formap): Iterate through a map or other collection of data
• Get Item ([ Index ]): Outputs an element from an array, map or table
• Get Nested Element ([[ Element ]]): Outputs an element from a nested structure
• Print Map / Structure Keys (struct-keys): Outputs all the keys in a structure as a file path
• Reformat Data type (format): Reformat one data-type into another data-type
• Transformation Tools (tabulate): Table transformation tools

Table Management

Commands specifically for working with tabulated data.

• Add Heading (addheading): Adds headings to a table
• For Each In Map (formap): Iterate through a map or other collection of data
• Inline SQL (select): Inlining SQL into shell pipelines
• Reformat Data type (format): Reformat one data-type into another data-type
• Transformation Tools (tabulate): Table transformation tools

System Inspection

Tools to inspect the host system.

• CPU Architecture (cpuarch): Output the hosts CPU architecture
• CPU Count (cpucount): Output the number of CPU cores available on your host
• Define Environmental Variable (export): Define an environmental variable and set it's value
• Operating System (os): Output the auto-detected OS name

Shell / Murex Management

Commands to manage the Murex shell session.

• Alias Pointer (alias): Create an alias for a command
• Command Line History (history): Outputs murex's command history
• Create Named Pipe (pipe): Manage Murex named pipes
• Debugging Mode (debug): Debugging information
• Define Handlers For "open" (openagent): Creates a handler function for open
• Define Method Relationships (method): Define a methods supported data-types
• Execute Shell Function or Builtin (fexec): Execute a command or function, bypassing the usual order of precedence.
• Include / Evaluate Murex Code (source): Import Murex code from another file or code block
• Murex Event Subsystem (event): Event driven programming for shell scripts
• Murex Package Management (murex-package): Murex's package manager
• Murex Version (version): Get Murex version
• Private Function (private): Define a private function block
• Public Function (function): Define a function block
• Re-Scan $PATH For Executables: Forces Murex to rescan $PATH looking for executables
• 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
• Tab Autocompletion (autocomplete): Set definitions for tab-completion in the command line

String Escaping / Character Codes

Commands to escape special characters in various different string formats.

• ASCII And ANSI Escape Sequences (key-code): Returns character sequences for any key pressed (ie sent from the terminal)
• 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
• Quote String (escape): Escape or unescape input

Process Management

Management of system processes and Murex FIDs.

• Background Process (bg): Run processes in the background
• Check Builtin Exists (bexists): Check which builtins exist
• Display Running Functions (fid-list): Lists all running functions within the current Murex session
• Execute External Command (exec): Runs an executable
• Foreground Process (fg): Sends a background process into the foreground
• Get Exit Code (exitnum): Output the exit number of the previous process
• Include / Evaluate Murex Code (source): Import Murex code from another file or code block
• Kill All In Session (fid-killall): Terminate all running Murex functions in current session
• Kill Function (fid-kill): Terminate a running Murex function
• Location Of Command (which): Locate command origin
• Processes Execution Time (time): Returns the execution run time of a command or block
• Send Signal IPC (signal): Sends a signal RPC

Language And Scripting

Various commands that enable control flow, error handling and other important characteristics that turn Murex into a functional programming language.

• 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 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
• Exit Block (break): Terminate execution of a block within your processes scope
• Exit Function (return): Exits current function scope
• Exit Murex (exit): Exit murex
• Expressions (expr): Expressions: mathematical, string comparisons, logical operators
• For Each In List (foreach): Iterate through an array
• For Each In Map (formap): Iterate through a map or other collection of data
• For Loop (for): A more familiar iteration loop to existing developers
• Get Data Type (get-type): Returns the data-type of a variable or pipe
• If Conditional (if): Conditional statement to execute different blocks of code depending on the result of the condition
• Is Value Null (is-null): Checks if a variable is null or undefined
• 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
• 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
• Private Function (private): Define a private function block
• Public Function (function): Define a function block
• Switch Conditional (switch): Blocks of cascading conditionals

Error Handling

Tools and control flow structures to handle errors.

• Caught Error Block (catch): Handles the exception code raised by try or trypipe
• Disable Error Handling In Block (unsafe): Execute a block of code, always returning a zero exit number
• Function / Module Defaults (runmode): Alter the scheduler's behaviour at higher scoping level
• Pipe Fail (trypipe): Checks for non-zero exits of each function in a pipeline
• 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
• Try Block (try): Handles non-zero exits inside a block of code

Help and Hint Tools

Tools for providing help and hints, useful when working inside the interactive shell.

• Man-Page Summary (man-summary): Outputs a man page summary of a command
• Murex's Offline Documentation (murex-docs): Displays the man pages for Murex builtins
• Parse Man-Page For Flags (man-get-flags): Parses man page files for command line flags
• Set Command Summary Hint (summary): Defines a summary help text for a command

Uncategorised

• die: Terminate murex with an exit number of 1 (deprecated)
• let: Evaluate a mathematical function and assign to variable (deprecated)
• murex-parser: Runs the Murex parser against a block of code

Optional Builtins

• 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