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

     1  - DocumentID: single-quote
     2    Title: >-
     3      `'Single Quote'`
     4    CategoryID: parser
     5    Summary: >-
     6      Initiates or terminates a string (variables not expanded)
     7    Description: |-
     8      Single quote is used to initiate and terminate strict strings where variables
     9      cannot be expanded.
    10  
    11      Commands can also be quoted using single quotes (eg where a command might
    12      contain a space character in it's name)
    13    Examples: |-
    14      ```
    15      » set example='World!'
    16      
    17      » out 'Hello $example'
    18      Hello $example
    19      ```
    20    Detail: |-
    21      Quotes can also work over multiple lines
    22  
    23      ```
    24      » out 'foo
    25      » bar'
    26      foo
    27      bar
    28      ```
    29    Related:
    30    - tilde
    31    - string
    32    - array
    33    - double-quote
    34    - brace-quote
    35    - curly-brace
    36    - out
    37    - set
    38    - brace-quote-func
    39  
    40  
    41  - DocumentID: double-quote
    42    Title: >-
    43      `"Double Quote"`
    44    CategoryID: parser
    45    Summary: >-
    46      Initiates or terminates a string (variables expanded)
    47    Description: |-
    48      Double quote is used to initiate and terminate strict strings where variables
    49      can be expanded.
    50  
    51      Commands can also be quoted using double quotes (eg where a command might
    52      contain a space character in it's name) however variables cannot be used as
    53      part of a command name.
    54    Examples: |-
    55      ```
    56      » set: example="World!"
    57      
    58      » out: "Hello $example"
    59      Hello World!
    60      ```
    61    Detail: |-
    62      Quotes can also work over multiple lines
    63  
    64      ```
    65      » out "foo
    66      » bar"
    67      foo
    68      bar
    69      ```
    70    Related:
    71    - tilde
    72    - string
    73    - array
    74    - single-quote
    75    - brace-quote
    76    - curly-brace
    77    - out
    78    - set
    79    - brace-quote-func
    80  
    81  
    82  - DocumentID: brace-quote
    83    Title: >-
    84      `%(Brace Quote)`
    85    CategoryID: parser
    86    Summary: >-
    87      Initiates or terminates a string (variables expanded)
    88    Description: |-
    89      Brace quote is used to initiate and terminate strict strings where variables
    90      can be expanded.
    91  
    92      While brace quotes are untraditional compared to your typical string quotations
    93      in POSIX shells, brace quotes have one advantage in that the open and close
    94      grapheme differ (ie `(` is a different character to `)`). This brings benefits
    95      when nesting quotes as it saves the developer from having to carefully escape
    96      the nested quotation marks just the right number of times.
    97  
    98      Commands cannot be quoted using brace quotes because `%(` is recognized as its
    99      own function.
   100    Examples: |-
   101      #### As a parameter:
   102  
   103      ```
   104      name = %(Bob)
   105      ```
   106  
   107      #### As a function:
   108  
   109      ```
   110      » %(hello world)
   111      hello world
   112      ```
   113  
   114      #### Nested quotes:
   115  
   116      ```
   117      » murex -c %(out %(Hello "${murex -c %(out %(Bob))}"))
   118      Hello "Bob"
   119      ```
   120  
   121      In this example we are calling Murex to execute code as a command line
   122      parameter (the `-c` flag). That code outputs `Hello "..."` but inside the
   123      double quotes is a name that is generated from a sub-shell. That sub-shell
   124      itself runs another murex instance which also executes another command line
   125      parameter, this time outputting the name **Bob**.
   126  
   127      The example is contrived but it does demonstrate how you can heavily nest
   128      quotes and even mix and match that with other quotation marks if desired.
   129  
   130      This is something that is extremely difficult to write in traditional shells
   131      because it would require lots of escaping, and even escaping the escape
   132      characters (and so on) the further deep you get in your nest.
   133    Detail: |-
   134      ### Multi-Line Quotes
   135  
   136      Quotes can also work over multiple lines
   137  
   138      ```
   139      » out %(foo
   140      » bar)
   141      foo
   142      bar
   143      ```
   144  
   145      ### Legacy Support
   146  
   147      Version 3.x of Murex introduced support for the `%` token, before that brace
   148      quotes worked without it. However to retain backwards compatibility, the older
   149      syntax is still supported...albeit officially classed as "deprecated" and may
   150      be removed from a future release.
   151  
   152      Below is a little detail about how the legacy syntax worked:
   153  
   154      #### Deprecated Syntax
   155      
   156      The open brace character is only recognized as a brace quote token if it is the
   157      start of a parameter.
   158  
   159      ```
   160      » set example=(World!)
   161      » out (Hello $example)
   162      Hello (World!)
   163      ```
   164    Related:
   165    - tilde
   166    - string
   167    - array
   168    - single-quote
   169    - double-quote
   170    - curly-brace
   171    - code-block
   172    - out
   173    - set
   174    - brace-quote-func
   175  
   176