foreach_doc.yaml

- DocumentID: foreach
  Title: >+
    For Each In List (`foreach`)
  CategoryID: commands
  SubCategoryIDs:
    - commands.lang
    - commands.list
  Summary: >-
    Iterate through an array
  Description: |-
    `foreach` reads an array or map from stdin and iterates through it, running
    a code block for each iteration with the value of the iterated element passed
    to it.

    By default `foreach`'s output data type is inherited from its input data type.
    For example is stdin is `yaml` then so will stdout. The only exception to this
    is if stdin is `json` in which case stdout will be jsonlines (`jsonl`), or when
    additional flags are used such as `--jmap`.
  Usage: |-
    `{ code-block }` reads from a variable and writes to an array / unbuffered stdout:

    ```
    <stdin> -> foreach variable { code-block } -> <stdout>
    ```

    `{ code-block }` reads from stdin and writes to an array / unbuffered stdout:

    ```
    <stdin> -> foreach { -> code-block } -> <stdout>
    ```

    `foreach` writes to a buffered JSON map:

    ```
    <stdin> -> foreach --jmap variable {
        code-block (map key)
    } {
        code-block (map value)
    } -> <stdout>
    ```
  Examples: |-
    There are two basic ways you can write a `foreach` loop depending on how you
    want the iterated element passed to the code block.

    The first option is to specify a temporary variable which can be read by the
    code block:

    ```
    » a [1..3] -> foreach i { out $i }
    1
    2
    3
    ```

    > Please note that the variable is specified **without** the dollar prefix,
    > then used in the code block **with** the dollar prefix.

    The second option is for the code block's stdin to read the element:

    ```
    » a [1..3] -> foreach { -> cat }
    1
    2
    3
    ```

    > stdin can only be read as the first command. If you cannot process the
    > element on the first command then it is recommended you use the first
    > option (passing a variable) instead.

    ### Writing JSON maps

    ```
    » ja [Monday..Friday] -> foreach --jmap day { out $day -> left 3 } { $day }
    {
        "Fri": "Friday",
        "Mon": "Monday",
        "Thu": "Thursday",
        "Tue": "Tuesday",
        "Wed": "Wednesday"
    } 
    ```

    ### Using steps to jump iterations by more than 1 (one)

    You can step through an array, list or table in jumps of user definable
    quantities. The value passed in stdin and $VAR will be an array of all
    the records within that step range. For example:

    ```
    » %[1..10] -> foreach --step 3 value { out "Iteration $.i: $value" }
    Iteration 1: [
        1,
        2,
        3
    ]
    Iteration 2: [
        4,
        5,
        6
    ]
    Iteration 3: [
        7,
        8,
        9
    ]
    Iteration 4: [
        10
    ]
    ```
  Flags:
    --jmap: >-
      Write a `json` map to stdout instead of an array
    --step: >-
      `<int>` Iterates in steps. Value passed to block is an array of items in the step range. Not (yet) supported with `--jmap`

  Detail: |-
    {{ include "gen/includes/meta-values.inc.md" }}

    * `i`: iteration number

    ### Preserving the data type (when no flags used)

    `foreach` will preserve the data type read from stdin in all instances where
    data is being passed along the pipeline and push that data type out at the
    other end:

    * The temporary variable will be created with the same data-type as
      `foreach`'s stdin, or the data type of the array element (eg if it is a
      string or number)
    * The code block's stdin will have the same data-type as `foreach`'s stdin
    * `foreeach`'s stdout will also be the same data-type as it's stdin (or `jsonl`
      (jsonlines) where stdin was `json` because `jsonl` better supports streaming)

    This last point means you may need to `cast` your data if you're writing
    data in a different format. For example the following is creating a YAML list
    however the data-type is defined as `json`:

    ```
    » ja [1..3] -> foreach i { out "- $i" }
    - 1
    - 2
    - 3

    » ja [1..3] -> foreach i { out "- $i" } -> debug -> [[ /Data-Type/Murex ]]
    json
    ```

    Thus any marshalling or other data-type-aware API's would fail because they
    are expecting `json` and receiving an incompatible data format.

    This can be resolved via `cast`:

    ```
    » ja [1..3] -> foreach i { out "- $i" } -> cast yaml
    - 1
    - 2
    - 3

    » ja [1..3] -> foreach i { out "- $i" } -> cast yaml -> debug -> [[ /Data-Type/Murex ]]
    yaml
    ```

    The output is the same but now it's defined as `yaml` so any further pipelined
    processes will now automatically use YAML marshallers when reading that data.

    {{ include "gen/includes/for-loop-json-tips.inc.md" }}
  Synonyms:
  Related:
    - formap
    - for
    - while
    - if
    - format
    - cast
    - a
    - ja
    - json
    - jsonl
    - yaml
    - out
    - left
    - debug
    - element
    - ReadArrayWithType
    - break