NixOS/nix
NixOS/nix
1
0
Fork 0
mirror of https://github.com/NixOS/nix synced 2024-09-19 10:50:24 -04:00
Code Activity

add many more examples on escaping in strings (#10974)

Browse source
This commit is contained in:
Valentin Gagarin 2024-06-27 10:58:59 +02:00 committed by GitHub
parent 3b388f6629
commit b44909ac22
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 114 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -6,19 +6,60 @@
*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"`.
e.g., `"foo bar"`. Strings can span multiple lines. The special Strings can span multiple lines.
characters `"` and `\` and the character sequence `${` must be The results of other expressions can be included into a string by enclosing them in `${ }`, a feature known as [string interpolation].
escaped by prefixing them with a backslash (`\`). Newlines, carriage
returns and tabs can be written as `\n`, `\r` and `\t`,
respectively.
You can include the results of other expressions into a string by enclosing them in `${ }`, a feature known as [string interpolation].
[string interpolation]: ./string-interpolation.md [string interpolation]: ./string-interpolation.md
The second way to write string literals is as an *indented string*, The following must be escaped to represent them within a string, by prefixing with a backslash (`\`):
which is enclosed between pairs of *double single-quotes*, like so:
- Double quote (`"`)
> **Example**
>
> ```nix
> "\""
> ```
>
> "\""
- Backslash (`\`)
> **Example**
>
> ```nix
> "\\"
> ```
>
> "\\"
- Dollar sign followed by an opening curly bracket (`${`) – "dollar-curly"
> **Example**
>
> ```nix
> "\${"
> ```
>
> "\${"
The newline, carriage return, and tab characters can be written as `\n`, `\r` and `\t`, respectively.
A "double-dollar-curly" (`$${`) can be written literally.
> **Example**
>
> ```nix
> "$${"
> ```
>
> "$\${"
String values are output on the terminal with Nix-specific escaping.
Strings written to files will contain the characters encoded by the escaping.
The second way to write string literals is as an *indented string*, which is enclosed between pairs of *double single-quotes* (`''`), like so:
```nix ```nix
'' ''
@ -40,18 +81,71 @@
"This is the first line.\nThis is the second line.\n This is the third line.\n" "This is the first line.\nThis is the second line.\n This is the third line.\n"
``` ```
Note that the whitespace and newline following the opening `''` is > **Note**
ignored if there is no non-whitespace text on the initial line. >
> Whitespace and newline following the opening `''` is ignored if there is no non-whitespace text on the initial line.
> **Warning**
>
> Prefixed tab characters are not stripped.
>
> > **Example**
> >
> > The following indented string is prefixed with tabs:
> >
> > ''
> > all:
> > @echo hello
> > ''
> >
> > "\tall:\n\t\t@echo hello\n"
Indented strings support [string interpolation]. Indented strings support [string interpolation].
Since `${` and `''` have special meaning in indented strings, you The following must be escaped to represent them in an indented string:
need a way to quote them. `$` can be escaped by prefixing it with
`''` (that is, two single quotes), i.e., `''$`. `''` can be escaped - `$` is escaped by prefixing it with two single quotes (`''`)
by prefixing it with `'`, i.e., `'''`. `$` removes any special
meaning from the following `$`. Linefeed, carriage-return and tab > **Example**
characters can be written as `''\n`, `''\r`, `''\t`, and `''\` >
escapes any other character. > ```nix
> ''
> ''$
> ''
> ```
>
> "$\n"
- `''` is escaped by prefixing it with one single quote (`'`)
> **Example**
>
> ```nix
> ''
> '''
> ''
> ```
>
> "''\n"
These special characters are escaped as follows:
- Linefeed (`\n`): `''\n`
- Carriage return (`\r`): `''\r`
- Tab (`\t`): `''\t`
`''\` escapes any other character.
A "double-dollar-curly" (`$${`) can be written literally.
> **Example**
>
> ```nix
> ''
> $${
> ''
> ```
>
> "$\${\n"
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
@ -167,7 +261,7 @@ function and the fifth being a set.
Note that lists are only lazy in values, and they are strict in length. Note that lists are only lazy in values, and they are strict in length.
Elements in a list can be accessed using [`builtins.elemAt`](./builtins.md#builtins-elemAt). Elements in a list can be accessed using [`builtins.elemAt`](./builtins.md#builtins-elemAt).
## Attribute Set ## Attribute Set