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

     1  - DocumentID: formap
     2    Title: >+
     3      `formap`
     4    CategoryID: commands
     5    Summary: >-
     6      Iterate through a map or other collection of data
     7    Description: |-
     8      `formap` is a generic tool for iterating through a map, table or other
     9      sequences of data similarly like a `foreach`. In fact `formap` can even be
    10      used on array too.
    11  
    12      Unlike `foreach`, `formap`'s default output is `str`, so each new line will be
    13      treated as a list item. This behaviour will differ if any additional flags are
    14      used with `foreach`, such as `--jmap`.
    15    Usage: |-
    16      `formap` writes a list:
    17  
    18      ```
    19      <stdin> -> foreach variable { code-block } -> <stdout>
    20      ```
    21  
    22      `formap` writes to a buffered JSON map:
    23  
    24      ```
    25      <stdin> -> formap --jmap key value { code-block (map key) } { code-block (map value) } -> <stdout>
    26      ```
    27    Examples: |-
    28      First of all lets assume the following dataset:
    29  
    30      ```
    31      set json people={
    32          "Tom": {
    33              "Age": 32,
    34              "Gender": "Male"
    35          },
    36          "Dick": {
    37              "Age": 43,
    38              "Gender": "Male"
    39          },
    40          "Sally": {
    41              "Age": 54,
    42              "Gender": "Female"
    43          }
    44      }
    45      ```
    46  
    47      We can create human output from this:
    48  
    49      ```
    50      » $people -> formap key value { out "$key is $value[Age] years old" }
    51      Sally is 54 years old
    52      Tom is 32 years old
    53      Dick is 43 years old
    54      ```
    55  
    56      > Please note that maps are intentionally unsorted so you cannot guarantee the
    57      > order of the output produced even if the input has been superficially set in
    58      > a specific order.
    59  
    60      With `--jmap` we can turn that structure into a new structure:
    61  
    62      ```
    63      » $people -> formap --jmap key value { $key } { $value[Age] }
    64      {
    65          "Dick": "43",
    66          "Sally": "54",
    67          "Tom": "32"
    68      } 
    69      ```
    70    Flags:
    71      --jmap: >-
    72        Write a `json` map to STDOUT instead of an array
    73    Detail: |-
    74      `formap` can also work against arrays and tables as well. However `foreach` is
    75      a much better tool for ordered lists and tables can look a little funky when
    76      when there are more than 2 columns. In those instances you're better off using
    77      `[` (index) to specify columns and then `tabulate` for any data transformation.
    78  
    79      {{ include "gen/includes/meta-values.inc.md" }}
    80  
    81      * `i`: iteration number
    82    Synonyms:
    83    Related:
    84      - foreach
    85      - for
    86      - while
    87      - json
    88      - set
    89      - item-index
    90      - tabulate
    91      - break