- DocumentID: curly-brace
  Title: >-
    Curly Brace (`{`, `}`) Tokens
  CategoryID: parser
  Summary: >-
    Initiates or terminates a code block
  Description: |-
    Curly braces are used to denote the start and end of a code block. Like with
    the single quotation marks (`'`), any code inside a curly brace is not parsed.
    Also unlike any other quotation tokens, the curly brace is included as part
    of the parsed string.

    ```
    » out: {example}
    {example}
    ```

    Also like the brace quote (`(`, `)`), the curly brace character is only
    recognized as a curly brace token if it is the start of a parameter.

    Curly braces are also used for other fields besides code blocks. For example
    inlining JSON.
  Examples:
  Detail: |-
    ### Multiline Blocks

    Curly braces can work over multiple lines

    ```
    » out: {foo
    » bar}
    {foo
    bar}
    ```

    ### Code Golfing

    Curly braces can be used to terminate the parsing of the command name / start
    the parsing of the first parameter however each new parameter would still need
    to be separated by whitespace:

    ```
    # Valid
    if{true} {out: "Yipee"}

    # Invalid
    if{true}{out: "Yipee"}
    ```

    ### ANSI Constants

    Some builtins (like `out`) also support infixing using the curly brace. eg

    ```
    out: "{GREEN}PASSED{RESET}"
    ```

    This is a separate layer of parsing and happens at the parameter level for
    specific builtins which opt to support ANSI constants. See the ANSI Constant
    user guide (link below) for more information on supporting builtins and which
    constants are available.

  Related:
  - tilde
  - string
  - array
  - single-quote
  - double-quote
  - brace-quote
  - user-guide/code-block
  - commands/out
  - commands/tout
  - commands/err
  - commands/set
  - commands/brace-quote
  - user-guide/ansi



- DocumentID: code-block
  Title: >-
    Code Block Parsing
  CategoryID: user-guide
  Summary: >-
    Overview of how code blocks are parsed
  Description: |-
    The murex parser creates ASTs ahead of interpreting each block of code. However
    the AST is only generated for a block at a time. Take this sample code:

    ```
    function example {
        # An example function
        if { $ENVVAR } then {
            out: 'foobar'
        }
        out: 'Finished!'
    }
    ```

    When that code is run `function` is executed with the parameters `example` and
    `{ ... }` but the contents of `{ ... }` isn't converted into ASTs until someone
    calls `example` elsewhere in the shell.

    When `example` (the Murex function defined above) is executed the parser will
    then generate AST of the commands inside said function but not any blocks that
    are associated with those functions. eg the AST would look something like this:

    ```
    [
        {
            "Command": "if",
            "Parameters": [
                "{ $ENVVAR }",
                "then",
                "{\n        out: 'foobar'\n    }"
            ]
        },
        {
            "Command": "out",
            "Parameters": [
                "Finished!"
            ]
        }
    ]
    ```

    > Please note this is a mock JSON structure rather than a representation of the
    > actual AST that would be created. Parameters are stored differently to allow
    > infixing of variables; and there also needs to be data shared about how
    > pipelining (eg STDOUT et al) is chained. What is being captured above is only
    > the command name and parameters.

    So when `if` executes, the conditional (the first parameter) is then parsed and
    turned into ASTs and executed. Then the last parameter (the **then** block) is
    parsed and turned into ASTs, if the first conditional is true.
    
    This sequence of parsing is defined within the `if` builtin rather than
    Murex's parser. That means any code blocks are parsed only when a builtin
    specifically requests that they are executed.

    With murex, there's no distinction between text and code. It's up to commands
    to determine if they want to execute a parameter as code or not (eg a curly
    brace block might be JSON).
  Examples:
  Detail:
  Related:
  - schedulers
  - pipeline
  - parser/curly-brace
  - ansi
