Skip to content

Commit 94663e7

Browse files
authored
update ASL tutorial to cover escaping (#229)
1 parent 76e652d commit 94663e7

File tree

1 file changed

+40
-0
lines changed

1 file changed

+40
-0
lines changed

docs/asl/tutorial.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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

3070
The stack language is primarily used for representing expressions over tagged time series

0 commit comments

Comments
 (0)