- DocumentID: try
  Title: >+
    `try`
  CategoryID: commands
  Summary: >-
    Handles errors 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
    * Any process that returns more output via STDERR than it does via STDOUT

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



- DocumentID: trypipe
  Title: >+
    `trypipe`
  CategoryID: commands 
  Summary: >-
    Checks state of each function in a pipeline and exits block on error
  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
    * Any process that returns more output via STDERR than it does via STDOUT

    You can see which run mode your functions are executing under via the `fid-list`
    command.
  Synonyms:
  Related:
  - try
  - catch
  - runmode
  - fid-list
  - if
  - switch
  - user-guide/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:
  - trypipe
  - try
  - runmode
  - if
  - switch
  - user-guide/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

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

    ### 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. The do not need a separate `runmode ... function`
    if `runmode ... module` is set.
  Synonyms:
  Related:
  - try
  - trypipe
  - catch
  - read
  - out
  - user-guide/schedulers
  - user-guide/pipeline
  - fid-list
  - function
  - private
  - autocomplete
  - event