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

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