github.com/lmorg/murex@v0.0.0-20240217211045-e081c89cd4ef/gen/parser/variables_doc.yaml (about)

     1  - DocumentID: scalar
     2    Title: >-
     3      `$Variable`
     4    CategoryID: parser
     5    Summary: >-
     6      Expand values as a scalar
     7    Description: |-
     8      The scalar token is used to tell Murex to expand variables and subshells as a
     9      string (ie one single parameter) irrespective of the data that is stored in the
    10      string. One handy common use case is file names where traditional POSIX shells
    11      would treat spaces as a new file, whereas Murex treats spaces as a printable
    12      character unless explicitly told to do otherwise.
    13  
    14      The string token must be followed with one of the following characters: 
    15      alpha, numeric, underscore (`_`) or a full stop / period (`.`).
    16   
    17    Examples: |-
    18      {{ include "gen/includes/parser-var-tokens.inc.md" }}
    19  
    20    Detail: |-
    21      Strings and subshells can be expanded inside double quotes, brace quotes as
    22      well as used as barewords. But they cannot be expanded inside single quotes.
    23      
    24      ```
    25      » set example="World!"
    26  
    27      » out Hello $example
    28      Hello World!
    29  
    30      » out 'Hello $example'
    31      Hello $example
    32  
    33      » out "Hello $example"
    34      Hello World!
    35  
    36      » out %(Hello $example)
    37      Hello World!
    38      ```
    39  
    40      However you cannot expand arrays (`@`) inside any form of quotation since
    41      it wouldn't be clear how that value should be expanded relative to the
    42      other values inside the quote. This is why array and object builders (`%[]`
    43      and `%{}` respectively) support array variables but string builders (`%()`)
    44      do not.
    45    Related:
    46    - tilde
    47    - array
    48    - single-quote
    49    - double-quote
    50    - brace-quote
    51    - out
    52    - set
    53    - let
    54    - ja
    55    - brace-quote-func
    56    - reserved-vars
    57  
    58  
    59  
    60  - DocumentID: array
    61    Title: >-
    62      Array (`@`) Token
    63    CategoryID: parser
    64    Summary: >-
    65      Expand values as an array
    66    Description: |-
    67      The array token is used to tell Murex to expand the string as multiple
    68      parameters (an array) rather than as a single parameter string.
    69    Examples: |-
    70      {{ include "gen/includes/parser-var-tokens.inc.md" }}
    71    Detail: |-
    72      Since arrays are expanded over multiple parameters, you cannot expand an array
    73      inside quoted strings like you can with a string variable:
    74  
    75      ```
    76      » out "foo ${ ja [1..5] } bar"
    77      foo ["1","2","3","4","5"] bar
    78      
    79      » out "foo @{ ja [1..5] } bar"
    80      foo  1 2 3 4 5  bar
    81  
    82      » %(${ ja [1..5] })
    83      ["1","2","3","4","5"]   
    84  
    85      » %(@{ ja: [1..5] })
    86      @{ ja [1..5] } 
    87      ```
    88    Related:
    89    - tilde
    90    - string
    91    - single-quote
    92    - double-quote
    93    - brace-quote
    94    - out
    95    - set
    96    - ja
    97    - brace-quote-func
    98    - reserved-vars
    99  
   100  
   101  - DocumentID: tilde
   102    Title: >-
   103      Tilde (`~`) Token
   104    CategoryID: parser
   105    Summary: >-
   106      Home directory path variable
   107    Description: |-
   108      The tilde token is used as a lazy reference to the users home directory.
   109    Examples: |-
   110      ```
   111      » out ~
   112      /home/bob
   113  
   114      » out ~joe
   115      /home/joe
   116      ```
   117    Detail: |-
   118      Tilde can be expanded inside double quotes, brace quotes as well as used naked.
   119      But it cannot be expanded inside single quotes.
   120      
   121      ```
   122      » out ~
   123      /home/bob
   124  
   125      » out '~'
   126      ~
   127  
   128      » out "~"
   129      /home/bob
   130  
   131      » out %(~)
   132      /home/bob
   133      ```
   134    Related:
   135    - string
   136    - array
   137    - single-quote
   138    - double-quote
   139    - brace-quote
   140    - out
   141    - set
   142    - ja
   143    - brace-quote-func
   144    - reserved-vars