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

- DocumentID: unsafe
  Title: >+
    `unsafe`
  CategoryID: commands
  Summary: >-
    Execute a block of code, always returning a zero exit number
  Description: |-
    `unsafe` is similar to normal execution except that the exit number for the
    last function in the `unsafe` block is ignored. `unsafe` always returns `0`.

    This is useful in any situations where you might want errors ignored.
  Usage: |-
    ```
    unsafe { code-block } -> <stdout>

    <stdin> -> unsafe { -> code-block } -> <stdout>
    ```
  Examples: |-
    ```
    try {
        unsafe { err "foobar" }
        out "This message still displays because the error is inside an `unsafe` block"
    }
    ```
  Flags:
  Detail:
  Synonyms:
  Related:
    - try
    - trypipe
    - tryerr
    - trypipeerr
    - catch
    - runmode
    - fid-list
    - if
    - switch
    - schedulers


- DocumentID: try
  Title: >+
    `try`
  CategoryID: commands
  Summary: >-
    Handles non-zero exits inside a block of code
  Description: |-
    `try` forces a different execution behavior where a failed process at the end
    of a pipeline will cause the block to terminate regardless of any functions that
    might follow.

    It's usage is similar to try blocks in other languages (eg Java) but a closer
    functional example would be `set -e` in Bash.

    To maintain concurrency within the pipeline, `try` will only check the last
    function in any given pipeline (ie series of functions joined via `|`, `->`, or
    similar operators). If you need the entire pipeline checked then use `trypipe`.
  Usage: |-
    ```
    try { code-block } -> <stdout>

    <stdin> -> try { -> code-block } -> <stdout>
    ```
  Examples: |-
    ```
    try {
        out "Hello, World!" -> grep: "non-existent string"
        out "This command will be ignored"
    }
    ```
  Flags:
  Detail: |-
    A failure is determined by:

    * Any process that returns a non-zero exit number

    You can see which run mode your functions are executing under via the `fid-list`
    command.
  Synonyms:
  Related:
    - unsafe
    - trypipe
    - tryerr
    - trypipeerr
    - catch
    - runmode
    - fid-list
    - if
    - switch
    - schedulers



- DocumentID: trypipe
  Title: >+
    `trypipe`
  CategoryID: commands
  Summary: >-
    Checks for non-zero exits of each function in a pipeline
  Description: |-
    `trypipe` checks the state of each function and exits the block if any of them
    fail. Where `trypipe` differs from regular `try` blocks is `trypipe` will check
    every process along the pipeline as well as the terminating function (which
    `try` only validates against). The downside to this is that piped functions can
    no longer run in parallel.
  Usage: |-
    ```
    trypipe { code-block } -> <stdout>

    <stdin> -> trypipe { -> code-block } -> <stdout>
    ```
  Examples: |-
    ```
    trypipe {
        out "Hello, World!" -> grep: "non-existent string" -> cat
        out "This command will be ignored"
    }
    ```

    Formated pager (`less`) where the pager isn't called if the formatter (`pretty`) fails (eg input isn't valid JSON):

    ```
    func pless {
        -> trypipe { -> pretty -> less }
    }
    ```
  Flags:
  Detail: |-
    A failure is determined by:

    * Any process that returns a non-zero exit number

    You can see which run mode your functions are executing under via the `fid-list`
    command.
  Synonyms:
  Related:
    - unsafe
    - try
    - tryerr
    - trypipeerr
    - catch
    - runmode
    - fid-list
    - if
    - switch
    - schedulers



- DocumentID: catch
  Title: >+
    `catch`
  CategoryID: commands
  Summary: >-
    Handles the exception code raised by `try` or `trypipe`
  Description: |-
    `catch` is designed to be used in conjunction with `try` and `trypipe` as it
    handles the exceptions raised by the aforementioned.
  Usage: |-
    ```
    [ try | trypipe ] { code-block } -> <stdout>

    catch { code-block } -> <stdout>

    !catch { code-block } -> <stdout>
    ```
  Examples: |-
    ```
    try {
        out "Hello, World!" -> grep: "non-existent string"
        out "This command will be ignored"
    }

    catch {
        out "An error was caught"
    }

    !catch {
        out "No errors were raised"
    }
    ```
  Flags:
  Detail: |-
    `catch` can be used with a bang prefix to check for a lack of errors.

    `catch` forwards on the STDIN and exit number of the calling function.
  Synonyms:
    - catch
    - "!catch"
  Related:
    - unsafe
    - try
    - trypipe
    - tryerr
    - trypipeerr
    - runmode
    - if
    - switch
    - schedulers



- DocumentID: runmode
  Title: >+
    `runmode`
  CategoryID: commands
  Summary: >-
    Alter the scheduler's behaviour at higher scoping level
  Description: |-
    Due to dynamic nature in which blocks are compiled on demand, traditional `try`
    and `trypipe` blocks cannot affect the runtime behaviour of schedulers already
    invoked (eg for function blocks and modules which `try` et al would sit inside).
    To solve this we need an additional command that is executed by the compiler
    prior to the block being executed which can define the runmode of the scheduler.
    This is the purpose of `runmode`.

    The caveat of being a compiler command rather than a builtin is that `runmode`
    needs be the first command in a block.
  Usage: |-
    ```
    runmode try|trypipe function|module
    ```
  Examples: |-
    ```
    function hello {
        # Short conversation, exit on error
        
        runmode try function

        read name "What is your name? "
        out "Hello $name, pleased to meet you"
        
        read mood "How are you feeling? "
        out "I'm feeling $mood too"
    }
    ```
  Flags:
  Detail: |-
    `runmode`'s parameters are ordered:

    ### 1st parameter

    #### unsafe

    Always return a zero exit number.

    #### try

    Checks only the last command in the pipeline for errors. However still allows
    commands in a pipeline to run in parallel.

    #### trypipe

    Checks every command in the pipeline before executing the next. However this
    blocks pipelines from running every command in parallel.

    #### tryerr

    Checks last command in the pipeline for errors (still allowing commands to run
    in parallel) plus also checks if STDERR contains excessive output.

    #### trypipeerr

    Checks every command in the pipeline before executing the next (blocking
    commands from running in parallel) plus also checks if STDERR contains
    excessive output.

    ### 2nd parameter

    #### function

    Sets the runmode for all blocks within the function when `runmode` is placed at
    the start of the function. This includes privates, autocompletes, events, etc.

    #### module

    Sets the runmode for all blocks within that module when placed at the start of
    the module. This include any functions, privates, autocompletes, events, etc
    that are inside that module. They do not need a separate `runmode ... function`
    if `runmode ... module` is set.
  Synonyms:
  Related:
    - unsafe
    - try
    - trypipe
    - tryerr
    - trypipeerr
    - catch
    - read
    - out
    - schedulers
    - pipeline
    - fid-list
    - function
    - private
    - autocomplete
    - event