github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/docs/commands/formap.md (about)

     1  # `formap`
     2  
     3  > Iterate through a map or other collection of data
     4  
     5  ## Description
     6  
     7  `formap` is a generic tool for iterating through a map, table or other
     8  sequences of data similarly like a `foreach`. In fact `formap` can even be
     9  used on array too.
    10  
    11  Unlike `foreach`, `formap`'s default output is `str`, so each new line will be
    12  treated as a list item. This behaviour will differ if any additional flags are
    13  used with `foreach`, such as `--jmap`.
    14  
    15  ## Usage
    16  
    17  `formap` writes a list:
    18  
    19  ```
    20  <stdin> -> foreach variable { code-block } -> <stdout>
    21  ```
    22  
    23  `formap` writes to a buffered JSON map:
    24  
    25  ```
    26  <stdin> -> formap --jmap key value { code-block (map key) } { code-block (map value) } -> <stdout>
    27  ```
    28  
    29  ## Examples
    30  
    31  First of all lets assume the following dataset:
    32  
    33  ```
    34  set json people={
    35      "Tom": {
    36          "Age": 32,
    37          "Gender": "Male"
    38      },
    39      "Dick": {
    40          "Age": 43,
    41          "Gender": "Male"
    42      },
    43      "Sally": {
    44          "Age": 54,
    45          "Gender": "Female"
    46      }
    47  }
    48  ```
    49  
    50  We can create human output from this:
    51  
    52  ```
    53  » $people -> formap key value { out "$key is $value[Age] years old" }
    54  Sally is 54 years old
    55  Tom is 32 years old
    56  Dick is 43 years old
    57  ```
    58  
    59  > Please note that maps are intentionally unsorted so you cannot guarantee the
    60  > order of the output produced even if the input has been superficially set in
    61  > a specific order.
    62  
    63  With `--jmap` we can turn that structure into a new structure:
    64  
    65  ```
    66  » $people -> formap --jmap key value { $key } { $value[Age] }
    67  {
    68      "Dick": "43",
    69      "Sally": "54",
    70      "Tom": "32"
    71  } 
    72  ```
    73  
    74  ## Flags
    75  
    76  * `--jmap`
    77      Write a `json` map to STDOUT instead of an array
    78  
    79  ## Detail
    80  
    81  `formap` can also work against arrays and tables as well. However `foreach` is
    82  a much better tool for ordered lists and tables can look a little funky when
    83  when there are more than 2 columns. In those instances you're better off using
    84  `[` (index) to specify columns and then `tabulate` for any data transformation.
    85  
    86  ### Meta values
    87  
    88  Meta values are a JSON object stored as the variable `$.`. The meta variable
    89  will get overwritten by any other block which invokes meta values. So if you
    90  wish to persist meta values across blocks you will need to reassign `$.`, eg
    91  
    92  ```
    93  %[1..3] -> foreach {
    94      meta_parent = $.
    95      %[7..9] -> foreach {
    96          out "$(meta_parent.i): $.i"
    97      }
    98  }
    99  ```
   100  
   101  The following meta values are defined:
   102  
   103  * `i`: iteration number
   104  
   105  ## See Also
   106  
   107  * [`[ Index ]`](../parser/item-index.md):
   108    Outputs an element from an array, map or table
   109  * [`break`](../commands/break.md):
   110    Terminate execution of a block within your processes scope
   111  * [`for`](../commands/for.md):
   112    A more familiar iteration loop to existing developers
   113  * [`foreach`](../commands/foreach.md):
   114    Iterate through an array
   115  * [`json`](../types/json.md):
   116    JavaScript Object Notation (JSON)
   117  * [`set`](../commands/set.md):
   118    Define a local variable and set it's value
   119  * [`tabulate`](../commands/tabulate.md):
   120    Table transformation tools
   121  * [`while`](../commands/while.md):
   122    Loop until condition false
   123  
   124  <hr/>
   125  
   126  This document was generated from [builtins/core/structs/formap_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/core/structs/formap_doc.yaml).