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

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