@@ -25,6 +25,46 @@ There are only four reserved symbols used for structuring the expression: `,:()`
2525 passed to the [ call] ( ./ref/call.md ) command. For example, ` (,:dup,) ` will push a list with a single
2626 string value of ` ":dup" ` on to the stack.
2727
28+ ### Escaping Reserved Symbols
29+
30+ When you need to include the reserved symbols ` ,:() ` as literal characters within your data, you can
31+ escape them using Unicode escape sequences. This is useful when working with tag values or string
32+ literals that contain these special characters.
33+
34+ Unicode escape sequences use the format ` \uXXXX ` where ` XXXX ` is the four-digit hexadecimal Unicode
35+ code point. For example:
36+
37+ - ` , ` (comma) can be escaped as ` \u002C `
38+ - ` : ` (colon) can be escaped as ` \u003A `
39+ - ` ( ` (left parenthesis) can be escaped as ` \u0028 `
40+ - ` ) ` (right parenthesis) can be escaped as ` \u0029 `
41+
42+ #### Example
43+
44+ Consider a scenario where you want to match a tag value that contains a colon:
45+
46+ ```
47+ name,:foo,:eq # Invalid - colon in :foo is interpreted as a command
48+ name,\u003Afoo,:eq # Valid - colon is escaped and treated as literal text
49+ ```
50+
51+ In the first case, ` :foo ` would be interpreted as a command, which would cause an error. In the
52+ second case, ` \u003Afoo ` represents the literal string ` :foo ` .
53+
54+ #### Preserving Whitespace
55+
56+ Unicode escaping can also be used to preserve whitespace at the beginning and end of tokens,
57+ which is normally trimmed during parsing. This is useful when exact spacing is important for your
58+ data:
59+
60+ ```
61+ tag,\u0020value\u0020,:eq # Preserves leading and trailing spaces around "value"
62+ ```
63+
64+ Without escaping, leading and trailing whitespace would be automatically removed from tokens
65+ during parsing.
66+
67+
2868## Data Model
2969
3070The stack language is primarily used for representing expressions over tagged time series
0 commit comments