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

     1  - DocumentID: alter
     2    Title: >+
     3      `alter`
     4    CategoryID: commands
     5    Summary: >-
     6      Change a value within a structured data-type and pass that change along the
     7      pipeline without altering the original source input
     8    Description: |-
     9      `alter` a value within a structured data-type.
    10  
    11      The path separater is defined by the first character in the path. For example
    12      `/path/to/key`, `,path,to,key`, `|path|to|key` and `#path#to#key` are all valid
    13      however you should remember to quote or escape any special characters (tokens)
    14      used by the shell (such as pipe, `|`, and hash, `#`).
    15  
    16      The *value* must always be supplied as JSON however 
    17    Usage: |-
    18      ```
    19      <stdin> -> alter [ -m | --merge | -s | --sum ] /path value -> <stdout>
    20      ```
    21    Examples: |-
    22      ```
    23      » config -> [ shell ] -> [ prompt ] -> alter /Value moo
    24      {
    25          "Data-Type": "block",
    26          "Default": "{ out 'murex » ' }",
    27          "Description": "Interactive shell prompt.",
    28          "Value": "moo"
    29      }
    30      ```
    31  
    32      `alter` also accepts JSON as a parameter for adding structured data:
    33  
    34      ```
    35      config -> [ shell ] -> [ prompt ] -> alter /Example { "Foo": "Bar" }
    36      {
    37          "Data-Type": "block",
    38          "Default": "{ out 'murex » ' }",
    39          "Description": "Interactive shell prompt.",
    40          "Example": {
    41              "Foo": "Bar"
    42          },
    43          "Value": "{ out 'murex » ' }"
    44      }
    45      ```
    46  
    47      However it is also data type aware so if they key you're updating holds a string
    48      (for example) then the JSON data a will be stored as a string:
    49  
    50      ```
    51      » config -> [ shell ] -> [ prompt ] -> alter /Value { "Foo": "Bar" }
    52      {
    53          "Data-Type": "block",
    54          "Default": "{ out 'murex » ' }",
    55          "Description": "Interactive shell prompt.",
    56          "Value": "{ \"Foo\": \"Bar\" }"
    57      }
    58      ```
    59  
    60      Numbers will also follow the same transparent conversion treatment:
    61  
    62      ```
    63      » tout json { "one": 1, "two": 2 } -> alter /two "3"
    64      {
    65          "one": 1,
    66          "two": 3
    67      }
    68      ```
    69  
    70      > Please note: `alter` is not changing the value held inside `config` but
    71      > instead took the STDOUT from `config`, altered a value and then passed that
    72      > new complete structure through it's STDOUT.
    73      >
    74      > If you require modifying a structure inside Murex config (such as http
    75      > headers) then you can use `config alter`. Read the config docs for reference.
    76    
    77      ### -m / --merge
    78  
    79      Thus far all the examples have be changing existing keys. However you can also
    80      alter a structure by appending to an array or a merging two maps together. You
    81      do this with the `--merge` (or `-m`) flag.
    82  
    83      ```
    84      » out a\nb\nc -> alter --merge / ([ "d", "e", "f" ])
    85      a
    86      b
    87      c
    88      d
    89      e
    90      f
    91      ```
    92  
    93      ### -s / --sum
    94  
    95      This behaves similarly to `--merge` where structures are blended together.
    96      However where a map exists with two keys the same and the values are numeric,
    97      those values are added together.
    98  
    99      ```
   100      » tout json { "a": 1, "b": 2 } -> alter --sum / { "b": 3, "c": 4 }
   101      {
   102          "a": 1,
   103          "b": 5,
   104          "c": 4
   105      }
   106      ```
   107    Detail: |-
   108      ### Path
   109  
   110      The path parameter can take any character as node separators. The separator is
   111      assigned via the first character in the path. For example
   112  
   113      ```
   114      config -> alter .shell.prompt.Value moo
   115      config -> alter >shell>prompt>Value moo
   116      ```
   117  
   118      Just make sure you quote or escape any characters used as shell tokens. eg
   119  
   120      ```
   121      config -> alter '#shell#prompt#Value' moo
   122      config -> alter ' shell prompt Value' moo
   123      ```
   124  
   125      ### Supported data-types
   126  
   127      The *value* field must always be supplied as JSON however the *STDIN* struct
   128      can be any data-type supported by murex.
   129      
   130      You can check what data-types are available via the `runtime` command:
   131  
   132      ```
   133      runtime --marshallers
   134      ```
   135  
   136      Marshallers are enabled at compile time from the `builtins/data-types` directory.
   137    Flags:
   138      "--merge": Merge data structures rather than overwrite
   139      "-m"     : Alias for `--merge`
   140      "--sum"  : Sum values in a map, merge items in an array
   141      "-s"     : Alias for `--sum`
   142    Synonyms:
   143    Related:
   144    - item-index
   145    - element
   146    - format
   147    - append
   148    - prepend
   149    - runtime
   150    - cast
   151    - config