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

     1  # `%(Brace Quote)`
     2  
     3  > Initiates or terminates a string (variables expanded)
     4  
     5  ## Description
     6  
     7  Brace quote is used to initiate and terminate strict strings where variables
     8  can be expanded.
     9  
    10  While brace quotes are untraditional compared to your typical string quotations
    11  in POSIX shells, brace quotes have one advantage in that the open and close
    12  grapheme differ (ie `(` is a different character to `)`). This brings benefits
    13  when nesting quotes as it saves the developer from having to carefully escape
    14  the nested quotation marks just the right number of times.
    15  
    16  Commands cannot be quoted using brace quotes because `%(` is recognized as its
    17  own function.
    18  
    19  
    20  
    21  ## Examples
    22  
    23  #### As a parameter:
    24  
    25  ```
    26  name = %(Bob)
    27  ```
    28  
    29  #### As a function:
    30  
    31  ```
    32  » %(hello world)
    33  hello world
    34  ```
    35  
    36  #### Nested quotes:
    37  
    38  ```
    39  » murex -c %(out %(Hello "${murex -c %(out %(Bob))}"))
    40  Hello "Bob"
    41  ```
    42  
    43  In this example we are calling Murex to execute code as a command line
    44  parameter (the `-c` flag). That code outputs `Hello "..."` but inside the
    45  double quotes is a name that is generated from a sub-shell. That sub-shell
    46  itself runs another murex instance which also executes another command line
    47  parameter, this time outputting the name **Bob**.
    48  
    49  The example is contrived but it does demonstrate how you can heavily nest
    50  quotes and even mix and match that with other quotation marks if desired.
    51  
    52  This is something that is extremely difficult to write in traditional shells
    53  because it would require lots of escaping, and even escaping the escape
    54  characters (and so on) the further deep you get in your nest.
    55  
    56  ## Detail
    57  
    58  ### Multi-Line Quotes
    59  
    60  Quotes can also work over multiple lines
    61  
    62  ```
    63  » out %(foo
    64  » bar)
    65  foo
    66  bar
    67  ```
    68  
    69  ### Legacy Support
    70  
    71  Version 3.x of Murex introduced support for the `%` token, before that brace
    72  quotes worked without it. However to retain backwards compatibility, the older
    73  syntax is still supported...albeit officially classed as "deprecated" and may
    74  be removed from a future release.
    75  
    76  Below is a little detail about how the legacy syntax worked:
    77  
    78  #### Deprecated Syntax
    79  
    80  The open brace character is only recognized as a brace quote token if it is the
    81  start of a parameter.
    82  
    83  ```
    84  » set example=(World!)
    85  » out (Hello $example)
    86  Hello (World!)
    87  ```
    88  
    89  ## See Also
    90  
    91  * [Array (`@`) Token](../parser/array.md):
    92    Expand values as an array
    93  * [Code Block Parsing](../user-guide/code-block.md):
    94    Overview of how code blocks are parsed
    95  * [Tilde (`~`) Token](../parser/tilde.md):
    96    Home directory path variable
    97  * [`"Double Quote"`](../parser/double-quote.md):
    98    Initiates or terminates a string (variables expanded)
    99  * [`'Single Quote'`](../parser/single-quote.md):
   100    Initiates or terminates a string (variables not expanded)
   101  * [`(brace quote)`](../parser/brace-quote-func.md):
   102    Write a string to the STDOUT without new line (deprecated)
   103  * [`out`](../commands/out.md):
   104    Print a string to the STDOUT with a trailing new line character
   105  * [`set`](../commands/set.md):
   106    Define a local variable and set it's value
   107  * [`string` (stringing)](../types/str.md):
   108    string (primitive)
   109  * [`{ Curly Brace }`](../parser/curly-brace.md):
   110    Initiates or terminates a code block
   111  
   112  <hr/>
   113  
   114  This document was generated from [gen/parser/quotes_doc.yaml](https://github.com/lmorg/murex/blob/master/gen/parser/quotes_doc.yaml).