github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/builtins/core/structs/foreach_doc.yaml (about)

     1  - DocumentID: foreach
     2    Title: >+
     3      `foreach`
     4    CategoryID: commands
     5    Summary: >-
     6      Iterate through an array
     7    Description: |-
     8      `foreach` reads an array or map from STDIN and iterates through it, running
     9      a code block for each iteration with the value of the iterated element passed
    10      to it.
    11  
    12      By default `foreach`'s output data type is inherited from its input data type.
    13      For example is STDIN is `yaml` then so will STDOUT. The only exception to this
    14      is if STDIN is `json` in which case STDOUT will be jsonlines (`jsonl`), or when
    15      additional flags are used such as `--jmap`.
    16    Usage: |-
    17      `{ code-block }` reads from a variable and writes to an array / unbuffered STDOUT:
    18  
    19      ```
    20      <stdin> -> foreach variable { code-block } -> <stdout>
    21      ```
    22  
    23      `{ code-block }` reads from STDIN and writes to an array / unbuffered STDOUT:
    24  
    25      ```
    26      <stdin> -> foreach { -> code-block } -> <stdout>
    27      ```
    28  
    29      `foreach` writes to a buffered JSON map:
    30  
    31      ```
    32      <stdin> -> foreach --jmap variable {
    33          code-block (map key)
    34      } {
    35          code-block (map value)
    36      } -> <stdout>
    37      ```
    38    Examples: |-
    39      There are two basic ways you can write a `foreach` loop depending on how you
    40      want the iterated element passed to the code block.
    41  
    42      The first option is to specify a temporary variable which can be read by the
    43      code block:
    44  
    45      ```
    46      » a [1..3] -> foreach i { out $i }
    47      1
    48      2
    49      3
    50      ```
    51  
    52      > Please note that the variable is specified **without** the dollar prefix,
    53      > then used in the code block **with** the dollar prefix.
    54  
    55      The second option is for the code block's STDIN to read the element:
    56  
    57      ```
    58      » a [1..3] -> foreach { -> cat }
    59      1
    60      2
    61      3
    62      ```
    63  
    64      > STDIN can only be read as the first command. If you cannot process the
    65      > element on the first command then it is recommended you use the first
    66      > option (passing a variable) instead.
    67  
    68      ### Writing JSON maps
    69  
    70      ```
    71      » ja [Monday..Friday] -> foreach --jmap day { out $day -> left 3 } { $day }
    72      {
    73          "Fri": "Friday",
    74          "Mon": "Monday",
    75          "Thu": "Thursday",
    76          "Tue": "Tuesday",
    77          "Wed": "Wednesday"
    78      } 
    79      ```
    80  
    81      ### Using steps to jump iterations by more than 1 (one)
    82  
    83      You can step through an array, list or table in jumps of user definable
    84      quantities. The value passed in STDIN and $VAR will be an array of all
    85      the records within that step range. For example:
    86  
    87      ```
    88      » %[1..10] -> foreach --step 3 value { out "Iteration $.i: $value" }
    89      Iteration 1: [
    90          1,
    91          2,
    92          3
    93      ]
    94      Iteration 2: [
    95          4,
    96          5,
    97          6
    98      ]
    99      Iteration 3: [
   100          7,
   101          8,
   102          9
   103      ]
   104      Iteration 4: [
   105          10
   106      ]
   107      ```
   108    Flags:
   109      --jmap: >-
   110        Write a `json` map to STDOUT instead of an array
   111      --step: >-
   112        `<int>` Iterates in steps. Value passed to block is an array of items in the step range. Not (yet) supported with `--jmap`
   113  
   114    Detail: |-
   115      {{ include "gen/includes/meta-values.inc.md" }}
   116  
   117      * `i`: iteration number
   118  
   119      ### Preserving the data type (when no flags used)
   120  
   121      `foreach` will preserve the data type read from STDIN in all instances where
   122      data is being passed along the pipeline and push that data type out at the
   123      other end:
   124  
   125      * The temporary variable will be created with the same data-type as
   126        `foreach`'s STDIN, or the data type of the array element (eg if it is a
   127        string or number)
   128      * The code block's STDIN will have the same data-type as `foreach`'s STDIN
   129      * `foreeach`'s STDOUT will also be the same data-type as it's STDIN (or `jsonl`
   130        (jsonlines) where STDIN was `json` because `jsonl` better supports streaming)
   131  
   132      This last point means you may need to `cast` your data if you're writing
   133      data in a different format. For example the following is creating a YAML list
   134      however the data-type is defined as `json`:
   135  
   136      ```
   137      » ja [1..3] -> foreach i { out "- $i" }
   138      - 1
   139      - 2
   140      - 3
   141  
   142      » ja [1..3] -> foreach i { out "- $i" } -> debug -> [[ /Data-Type/Murex ]]
   143      json
   144      ```
   145  
   146      Thus any marshalling or other data-type-aware API's would fail because they
   147      are expecting `json` and receiving an incompatible data format.
   148  
   149      This can be resolved via `cast`:
   150  
   151      ```
   152      » ja [1..3] -> foreach i { out "- $i" } -> cast yaml
   153      - 1
   154      - 2
   155      - 3
   156  
   157      » ja [1..3] -> foreach i { out "- $i" } -> cast yaml -> debug -> [[ /Data-Type/Murex ]]
   158      yaml
   159      ```
   160  
   161      The output is the same but now it's defined as `yaml` so any further pipelined
   162      processes will now automatically use YAML marshallers when reading that data.
   163  
   164      {{ include "gen/includes/for-loop-json-tips.inc.md" }}
   165    Synonyms:
   166    Related:
   167      - formap
   168      - for
   169      - while
   170      - if
   171      - format
   172      - cast
   173      - a
   174      - ja
   175      - json
   176      - jsonl
   177      - yaml
   178      - out
   179      - left
   180      - debug
   181      - element
   182      - ReadArrayWithType
   183      - break