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

     1  # `[[ Element ]]`
     2  
     3  > Outputs an element from a nested structure
     4  
     5  ## Description
     6  
     7  Outputs an element from an array, map or table. Unlike **index** (`[`),
     8  **element** takes a path parameter which means it can work inside nested
     9  structures without pipelining multiple commands together. However this
    10  comes with the drawback that you can only return one element.
    11  
    12  **Element** (`[[`) also doesn't support the bang prefix (unlike) **index**.
    13  
    14  Please note that indexes in Murex are counted from zero.
    15  
    16  ## Usage
    17  
    18  ```
    19  <stdin> -> [[ element ]] -> <stdout>
    20  
    21  $variable[[ element ]] -> <stdout>
    22  ```
    23  
    24  ## Examples
    25  
    26  Return the 2nd element in an array
    27  
    28  ```
    29  » ja [0..9] -> [[ /1 ]]
    30  [
    31      "1",
    32  ]
    33  ```
    34  
    35  Return the data-type and description of **config shell syntax-highlighting**
    36  
    37  ```
    38  » config -> [[ /shell/syntax-highlighting/Data-Type ]]
    39  bool
    40  ```
    41  
    42  ## Detail
    43  
    44  ### Element counts from zero
    45  
    46  Indexes in Murex behave like any other computer array in that all arrays
    47  start from zero (`0`).
    48  
    49  ### Alternative path separators
    50  
    51  **Element** uses the first character in the path as the separator. So the
    52  following are all valid parameters:
    53  
    54  ```
    55  » config -> [[ ,shell,syntax-highlighting,Data-Type ]]
    56  bool
    57  
    58  » config -> [[ >shell>syntax-highlighting>Data-Type ]]
    59  bool
    60  
    61  » config -> [[ \|shell\|syntax-highlighting\|Data-Type ]]
    62  bool
    63  
    64  » config -> [[ >shell>syntax-highlighting>Data-Type ]]
    65  bool
    66  ```
    67  
    68  However there are a few of caveats:
    69  
    70  1. Currently **element** does not support unicode separators. All separators
    71     must be 1 byte characters. This limitation is highlighted as a bug, albeit
    72     a low priority one. If this limitation does directly affect you then raise
    73     an issue on GitHub to get the priority bumped up.
    74  
    75  2. Any shell tokens (eg pipe `|`, `;`, `}`, etc) will need to be escaped. For
    76     readability reasons it is recommended not to use such characters even
    77     though it is technically possible to.
    78  
    79  ```
    80      # Would fail because the semi-colon is an unescaped / unquoted shell token
    81      config -> [[ ;shell-syntax-highlighting;Data-Type ]]
    82  ```
    83  
    84  3. Please also make sure you don't use a character that is also used inside
    85     key names because keys _cannot_ be escaped. For example both of the
    86     following would fail:
    87  
    88  ```
    89      # Would fail because 'syntax-highlighting' and 'Data-Type' both also contain
    90      # the separator character
    91      config -> [[ -shell-syntax-highlighting-Data-Type ]]
    92  
    93      # Would fail because you cannot escape key names (escaping happens at the
    94      # shell parser level rather than command parameter level)
    95      config -> [[ -shell-syntax\-highlighting-Data\-Type ]]
    96  ```
    97  
    98  ### Quoting parameters
    99  
   100  In Murex, everything is a function. Thus even `[[` is a function name and
   101  the closing `]]` is actually a last parameter. This means the recommended way
   102  to quote **element** parameters is to quote specific key names or the entire
   103  path:
   104  
   105  ```
   106  » config -> [[ /shell/"syntax-highlighting"/Data-Type ]]
   107  bool
   108  
   109  » config -> [[ "|shell|syntax-highlighting|Data-Type" ]]
   110  bool
   111  ```
   112  
   113  ## Synonyms
   114  
   115  * `[[`
   116  * `element`
   117  
   118  
   119  ## See Also
   120  
   121  * [`[ ..Range ]`](../parser/range.md):
   122    Outputs a ranged subset of data from STDIN
   123  * [`[ Index ]`](../parser/item-index.md):
   124    Outputs an element from an array, map or table
   125  * [`a` (mkarray)](../commands/a.md):
   126    A sophisticated yet simple way to build an array or list
   127  * [`config`](../commands/config.md):
   128    Query or define Murex runtime settings
   129  * [`count`](../commands/count.md):
   130    Count items in a map, list or array
   131  * [`ja` (mkarray)](../commands/ja.md):
   132    A sophisticated yet simply way to build a JSON array
   133  * [`mtac`](../commands/mtac.md):
   134    Reverse the order of an array
   135  
   136  <hr/>
   137  
   138  This document was generated from [builtins/core/element/element_doc.yaml](https://github.com/lmorg/murex/blob/master/builtins/core/element/element_doc.yaml).