murex Shell Docs

Command Reference: function

Define a function block

Description

function defines a block of code as a function

Usage

Define a function:

function: name { code-block }

Define a function with variable names defined (default value and description are optional parameters):

function: name (
    variable1: data-type [default-value] "description",
    variable2: data-type [default-value] "description"
) {
    code-block
}

Undefine a function:

!function: command

Examples

» function hw { out "Hello, World!" }
» hw
Hello, World!

» !function hw
» hw
exec: "hw": executable file not found in $PATH

Detail

Allowed characters

Function names can only include any characters apart from dollar ($). This is to prevent functions from overwriting variables (see the order of preference below).

Undefining a function

Like all other definable states in murex, you can delete a function with the bang prefix (see the example above).

Using parameterized variable names

By default, if you wanted to query the parameters passed to a murex function you would have to use either:

Starting from murex 2.7.x it's been possible to declare parameters from within the function declaration:

function: name (
    variable1: data-type [default-value] "description",
    variable2: data-type [default-value] "description"
) {
    code-block
}

Syntax

First off, the syntax doesn't have to follow exactly as above:

This field is optional.

This field is optional.

Variables

Any variable name you declare in your function declaration will be exposed in your function body as a local variable. For example:

function: hello (name: str) {
    out: "Hello $name, pleased to meet you."
}

If the function isn't called with the complete list of parameters and it is running in the foreground (ie not part of autocomplete, event, bg, etc) then you will be prompted for it's value. That could look something like this:

» function: hello (name: str) {
»     out: "Hello $name, pleased to meet you."
» }

» hello
Please enter a value for 'name': Bob
Hello Bob, pleased to meet you.

(in this example you typed Bob when prompted)

Data-Types

This is the murex data type of the variable. From version 2.8.x this field is optional and will default to str when omitted.

The advantage of setting this field is that values are type checked and the function will fail early if an incorrect value is presented. For example:

» function: age (age: int) { out: "$age is a great age." }

» age
Please enter a value for 'age': ten
Error in `age` ( 2,1): cannot convert parameter 1 'ten' to data type 'int'

» age ten
Error in `age` ( 2,1): cannot convert parameter 1 'ten' to data type 'int'

However it will try to automatically convert values if it can:

» age 1.2
1 is a great age.

Default values

Default values are only relevant when functions are run interactively. It allows the user to press enter without inputting a value:

» function: hello (name: str [John]) { out: "Hello $name, pleased to meet you." }

» hello
Please enter a value for 'name' [John]: 
Hello John, pleased to meet you.

Here no value was entered so $name defaulted to John.

Default values will not auto-populate when the function is run in the background. For example:

» bg {hello}
Error in `hello` ( 2,2): cannot prompt for parameters when a function is run in the background: too few parameters

Description

Descriptions are only relevant when functions are run interactively. It allows you to define a more useful prompt should that function be called without sufficient parameters. For example:

» function hello (name: str "What is your name?") { out "Hello $name" }

» hello
What is your name?: Sally
Hello Sally

Order of precedence

There is an order of precedence for which commands are looked up:

  1. test and pipe functions because they alter the behavior of the compiler
  2. Aliases - defined via alias. All aliases are global
  3. murex functions - defined via function. All functions are global
  4. private functions - defined via private. Private's cannot be global and are scoped only to the module or source that defined them. For example, You cannot call a private function from the interactive command line
  5. variables (dollar prefixed) - declared via set or let
  6. auto-globbing prefix: @g
  7. murex builtins
  8. external executable files

Synonyms

See Also

This site's content is rebuilt automatically from murex's source code after each merge to the master branch. Downloadable murex binaries are also built with the website.

Last built on Thu May 26 22:49:43 UTC 2022 against commit 59e27bb59e27bb1013043fc4a940cf9a2767c63f31dad2c.

Current version is 2.8.2100 which has been verified against 15889 tests cases.