github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/builtins/core/structs/function_doc.yaml

- DocumentID: alias
  Title: >+
    `alias`
  CategoryID: commands
  Summary: >-
    Create an alias for a command
  Description: |-
    `alias` allows you to create a shortcut or abbreviation for a longer command.

    IMPORTANT: aliases in Murex are not macros and are therefore different than
     other shells. if the shortcut requires any dynamics such as `piping`,
     `command sequencing`, `variable evaluations` or `scripting`...
     Prefer the **`function`** builtin.
  Usage: |-
    ```
    alias alias=command parameter parameter

    !alias command
    ```
  Examples: |-
    Because aliases are parsed into an array of parameters, you cannot put the
    entire alias within quotes. For example:

    ```
    # bad :(
    » alias hw="out Hello, World!"
    » hw
    exec "out\\ Hello,\\ World!": executable file not found in $PATH

    # good :)
    » alias hw=out "Hello, World!"
    » hw
    Hello, World!
    ```

    Notice how only the command `out "Hello, World!"` is quoted in `alias` the
    same way you would have done if you'd run that command "naked" in the command
    line? This is how `alias` expects it's parameters and where `alias` on Murex
    differs from `alias` in POSIX shells.

    To materialize those differences, pay attention to the examples below:

    ```
    # bad : the following statements generate errors,
    #  prefer function builtin to implent them

    » alias myalias=out "Hello, World!" | wc
    » alias myalias=out $myvariable | wc
    » alias myalias=out ${vmstat} | wc
    » alias myalias=out "hello" && out "world"
    » alias myalias=out "hello" ; out "world"
    » alias myalias="out hello; out world"
    ```

    In some ways this makes `alias` a little less flexible than it might
    otherwise be. However the design of this is to keep `alias` focused on it's
    core objective. To implement the above aliasing, you can use `function`
    instead.
  Flags:
  Detail: |-
    ### Allowed characters

    Alias names can only include alpha-numeric characters, hyphen and underscore.
    The following regex is used to validate the `alias`'s parameters:
    `^([-_a-zA-Z0-9]+)=(.*?)$`

    ### Undefining an alias

    Like all other definable states in Murex, you can delete an alias with the
    bang prefix:

    ```
    » alias hw=out "Hello, World!"
    » hw
    Hello, World!

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

    ### Order of preference

    {{ include "gen/includes/order-of-precedence.inc.md" }}
  Synonyms:
    - alias
    - "!alias"
  Related:
    - function
    - private
    - source
    - g
    - let
    - set
    - global
    - export
    - exec
    - fexec
    - method

- DocumentID: function
  Title: >+
    `function`
  CategoryID: commands
  Summary: >-
    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
    ```
  Flags:
  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 `!function` (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:

    * the Bash syntax where of `$2` style numbered reserved variables,

    * and/or the Murex convention of `$PARAM` / `$ARGS` arrays (see **reserved-vars**
      document below),
      
    * and/or the older Murex convention of the `args` builtin for any flags.

    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:

    * **Variables** shouldn't be prefixed with a dollar (`$`). This is a little like
      declaring variables via `set`, etc. However it should be followed by a colon
      (`:`) or comma (`,`). Normal rules apply with regards to allowed characters
      in variable names: limited to ASCII letters (upper and lower case), numbers,
      underscore (`_`), and hyphen (`-`). Unicode characters as variable names are
      not currently supported.

    * **data-type** is the Murex data type. This is an optional field in version
      `2.8.x` (defaults to `str`) but is required in `2.7.x`.

    * The **default value** must be inside square brackets (`[...]`). Any value is
      allowed (including Unicode) _except_ for carriage returns / new lines (`\r`,
      `\n`) and a closing square bracket (`]`) as the latter would indicate the end
      of this field. You cannot escape these characters either.

      This field is optional.

    * The **description** must sit inside double quotes (`"..."`). Any value is allowed
      (including Unicode) _except_ for carriage returns / new lines (`\r`, `\n`)
      and double quotes (`"`) as the latter would indicate the end of this field.
      You cannot escape these characters either.

      This field is optional.

    * You do not need a new line between each parameter, however you do need to
      separate them with a comma (like with JSON, there should not be a trailing
      comma at the end of the parameters). Thus the following is valid:
      `variable1: data-type, variable2: data-type`.

    #### 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

    {{ include "gen/includes/order-of-precedence.inc.md" }}
  Synonyms:
    - function
    - "!function"
  Related:
    - args
    - alias
    - private
    - source
    - g
    - let
    - set
    - global
    - export
    - exec
    - fexec
    - method
    - reserved-vars
    - version
    - break

- DocumentID: private
  Title: >+
    `private`
  CategoryID: commands
  Summary: >-
    Define a private function block
  Description: |-
    `private` defines a function who's scope is limited to that module or source
    file.

    Privates cannot be called from one module to another (unless they're wrapped
    around a global `function`) and nor can they be called from the interactive
    command line. The purpose of a `private` is to reduce repeated code inside
    a module or source file without cluttering up the global namespace.
  Usage: |-
    ```
    private name { code-block }
    ```
  Examples: |-
    ```
    # The following cannot be entered via the command line. You need to write
    # it to a file and execute it from there.

    private hw {
        out "Hello, World!"
    }

    function tom {
        hw
        out "My name is Tom."
    }

    function dick {
        hw
        out "My name is Dick."
    }

    function harry {
        hw
        out "My name is Harry."
    }
    ```
  Flags:
  Detail: |-
    ### Allowed characters

    Private 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 private

    Because private functions are fixed to the source file that declares them,
    there isn't much point in undefining them. Thus at this point in time, it
    is not possible to do so.

    ### Order of preference

    {{ include "gen/includes/order-of-precedence.inc.md" }}
  Synonyms:
  Related:
    - function
    - alias
    - source
    - g
    - let
    - set
    - global
    - export
    - exec
    - fexec
    - method
    - break

- DocumentID: method
  Title: >+
    `method`
  CategoryID: commands
  Summary: >-
    Define a methods supported data-types
  Description: |-
    `method` defines what the typical data type would be for a function's STDIN
    and STDOUT.
  Usage: |-
    ```
    method: define name { json }
    ```
  Examples: |-
    ```
    method: define name {
        "Stdin":  "@Any",
        "Stdout": "json"
    }
    ```
  Flags:
  Detail: |-
    ### Type Groups

    You can define a Murex data type or use a type group. The following type
    groups are available to use:

    ```go
    {{ include "lang/types/groups.go" }}
    ```
  Synonyms:
  Related:
    - function
    - alias
    - private
    - autocomplete
    - runtime
    - pipe-arrow
    - interactive-shell