From beb231784e6bfadf59f31e56631d80d60a4b0c84 Mon Sep 17 00:00:00 2001 From: Alois Wohlschlager Date: Sat, 13 Jul 2024 16:11:07 +0200 Subject: [PATCH] doc/manual: clarify documentation related to the `$$` parser bug 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 --- doc/manual/src/language/values.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/doc/manual/src/language/values.md b/doc/manual/src/language/values.md index f02ef2597..aa5455ae2 100644 --- a/doc/manual/src/language/values.md +++ b/doc/manual/src/language/values.md @@ -7,13 +7,16 @@ *Strings* can be written in three ways. The most common way is to enclose the string between double quotes, - e.g., `"foo bar"`. Strings can span multiple lines. The special - characters `"` and `\` and the character sequence `${` must be - escaped by prefixing them with a backslash (`\`). Newlines, carriage - returns and tabs can be written as `\n`, `\r` and `\t`, - respectively. + e.g., `"foo bar"`. Strings can span multiple lines. The backslash + (`\`) can be used to escape characters: newlines, carriage returns + and tabs may be written as `\n`, `\r` and `\t` respectively; any + other characters can be preceded by a backslash to remove any + 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]. + 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 @@ -43,16 +46,16 @@ Note that the whitespace and newline following the opening `''` is 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 need a way to quote them. `$` can be escaped by prefixing it with `''` (that is, two single quotes), i.e., `''$`. `''` can be escaped - by prefixing it with `'`, i.e., `'''`. `$` removes any special - meaning from the following `$`. Linefeed, carriage-return and tab + by prefixing it with `'`, i.e., `'''`. Linefeed, carriage-return and tab characters can be written as `''\n`, `''\r`, `''\t`, and `''\` 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 string literals to follow the indentation of the enclosing Nix expression, and that less escaping is typically necessary for