github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/docs/user-guide/code-block.md (about)

     1  # Code Block Parsing
     2  
     3  > Overview of how code blocks are parsed
     4  
     5  The murex parser creates ASTs ahead of interpreting each block of code. However
     6  the AST is only generated for a block at a time. Take this sample code:
     7  
     8  ```
     9  function example {
    10      # An example function
    11      if { $ENVVAR } then {
    12          out 'foobar'
    13      }
    14      out 'Finished!'
    15  }
    16  ```
    17  
    18  When that code is run `function` is executed with the parameters `example` and
    19  `{ ... }` but the contents of `{ ... }` isn't converted into ASTs until someone
    20  calls `example` elsewhere in the shell.
    21  
    22  When `example` (the Murex function defined above) is executed the parser will
    23  then generate AST of the commands inside said function but not any blocks that
    24  are associated with those functions. eg the AST would look something like this:
    25  
    26  ```
    27  [
    28      {
    29          "Command": "if",
    30          "Parameters": [
    31              "{ $ENVVAR }",
    32              "then",
    33              "{\n        out 'foobar'\n    }"
    34          ]
    35      },
    36      {
    37          "Command": "out",
    38          "Parameters": [
    39              "Finished!"
    40          ]
    41      }
    42  ]
    43  ```
    44  
    45  > Please note this is a mock JSON structure rather than a representation of the
    46  > actual AST that would be created. Parameters are stored differently to allow
    47  > infixing of variables; and there also needs to be data shared about how
    48  > pipelining (eg STDOUT et al) is chained. What is being captured above is only
    49  > the command name and parameters.
    50  
    51  So when `if` executes, the conditional (the first parameter) is then parsed and
    52  turned into ASTs and executed. Then the last parameter (the **then** block) is
    53  parsed and turned into ASTs, if the first conditional is true.
    54  
    55  This sequence of parsing is defined within the `if` builtin rather than
    56  Murex's parser. That means any code blocks are parsed only when a builtin
    57  specifically requests that they are executed.
    58  
    59  With murex, there's no distinction between text and code. It's up to commands
    60  to determine if they want to execute a parameter as code or not (eg a curly
    61  brace block might be JSON).
    62  
    63  ## See Also
    64  
    65  * [ANSI Constants](../user-guide/ansi.md):
    66    Infixed constants that return ANSI escape sequences
    67  * [Pipeline](../user-guide/pipeline.md):
    68    Overview of what a "pipeline" is
    69  * [Schedulers](../user-guide/schedulers.md):
    70    Overview of the different schedulers (or 'run modes') in Murex
    71  * [`%(Brace Quote)`](../parser/brace-quote.md):
    72    Initiates or terminates a string (variables expanded)
    73  * [`%[]` Create Array](../parser/create-array.md):
    74    Quickly generate arrays
    75  * [`%{}` Create Map](../parser/create-object.md):
    76    Quickly generate objects and maps
    77  * [`{ Curly Brace }`](../parser/curly-brace.md):
    78    Initiates or terminates a code block
    79  
    80  <hr/>
    81  
    82  This document was generated from [gen/parser/codeblock_doc.yaml](https://github.com/lmorg/murex/blob/master/gen/parser/codeblock_doc.yaml).