alois31/lix
0
0
Fork 0
forked from lix-project/lix
Code Pull requests Activity

doc/manual: clarify documentation related to the $$ parser bug

Browse source 
Due to a mistake in the grammar, a dollar character implicitly escapes a second
dollar character that immediately follows, so that it cannot start an
interpolation. Unfortunately, this behaviour has since come to be relied upon,
so it cannot be fixed. Furthermore, the documentation on regular strings did
not mention this behaviour at all, while in the case of indented strings it was
rather implicit.
Mention it explicitly in both cases, and describe how an interpolation can
follow a dollar character (namely, by escaping that). Since we have to touch
that section anyway, state that any character (other than n, r, and t; but
notably including `$` even if not succeeded by `{`) can be escaped using a
backslash in regular strings.

Change-Id: I7e5d68a9a4130eec98ce8218b485168f4b31a677
This commit is contained in:
alois31 2024-07-13 16:11:07 +02:00
parent 48fb1f2e03
commit e49c54c5f2
Signed by: alois31
GPG key ID: E0F59EA5E5216914
1 changed files with 12 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
doc/manual/src/language/values.md
View file

@ -7,13 +7,16 @@
*Strings* can be written in three ways. *Strings* can be written in three ways.
The most common way is to enclose the string between double quotes, The most common way is to enclose the string between double quotes,
e.g., `"foo bar"`. Strings can span multiple lines. The special e.g., `"foo bar"`. Strings can span multiple lines. The backslash
characters `"` and `\` and the character sequence `${` must be (`\`) can be used to escape characters: newlines, carriage returns
escaped by prefixing them with a backslash (`\`). Newlines, carriage and tabs may be written as `\n`, `\r` and `\t` respectively; any
returns and tabs can be written as `\n`, `\r` and `\t`, other characters can be preceded by a backslash to remove any
respectively. special meaning they may have, like the special characters `"` and
`\` and the character sequence `${`.
You can include the results of other expressions into a string by enclosing them in `${ }`, a feature known as [string interpolation]. You can include the results of other expressions into a string by enclosing them in `${ }`, a feature known as [string interpolation].
Due to a parser issue that has since come to be relied upon, the character sequence `$${` is interpreted literally and does not introduce an interpolation.
To express a `$` character immediately followed by an interpolation, the former must be escaped.
[string interpolation]: ./string-interpolation.md [string interpolation]: ./string-interpolation.md
@ -43,16 +46,16 @@
Note that the whitespace and newline following the opening `''` is Note that the whitespace and newline following the opening `''` is
ignored if there is no non-whitespace text on the initial line. ignored if there is no non-whitespace text on the initial line.
Indented strings support [string interpolation].
Since `${` and `''` have special meaning in indented strings, you Since `${` and `''` have special meaning in indented strings, you
need a way to quote them. `$` can be escaped by prefixing it with need a way to quote them. `$` can be escaped by prefixing it with
`''` (that is, two single quotes), i.e., `''$`. `''` can be escaped `''` (that is, two single quotes), i.e., `''$`. `''` can be escaped
by prefixing it with `'`, i.e., `'''`. `$` removes any special by prefixing it with `'`, i.e., `'''`. Linefeed, carriage-return and tab
meaning from the following `$`. Linefeed, carriage-return and tab
characters can be written as `''\n`, `''\r`, `''\t`, and `''\` characters can be written as `''\n`, `''\r`, `''\t`, and `''\`
escapes any other character. escapes any other character.
Indented strings support [string interpolation] using `${ }` the same way regular strings do.
`$${` is interpreted literally in indented strings as well, so the `$` character must be escaped if it is to be followed by an interpolation.
Indented strings are primarily useful in that they allow multi-line Indented strings are primarily useful in that they allow multi-line
string literals to follow the indentation of the enclosing Nix string literals to follow the indentation of the enclosing Nix
expression, and that less escaping is typically necessary for expression, and that less escaping is typically necessary for