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

manual: use subheadings for primitive types

Browse source 
this gives us HTML anchors for each of them
This commit is contained in:
Valentin Gagarin 2022-07-28 17:09:53 +02:00
parent 86fcd4f692
commit 3063e5b94c
1 changed files with 149 additions and 139 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

252
doc/manual/src/expressions/language-values.md
View file

@ -4,151 +4,161 @@
Nix has the following basic data types: Nix has the following basic data types:
- *Strings* can be written in three ways. ### Strings
The most common way is to enclose the string between double quotes, *Strings* can be written in three ways.
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.
You can include the result of an expression into a string by The most common way is to enclose the string between double quotes,
enclosing it in `${...}`, a feature known as *antiquotation*. The e.g., `"foo bar"`. Strings can span multiple lines. The special
enclosed expression must evaluate to something that can be coerced characters `"` and `\` and the character sequence `${` must be
into a string (meaning that it must be a string, a path, or a escaped by prefixing them with a backslash (`\`). Newlines, carriage
derivation). For instance, rather than writing returns and tabs can be written as `\n`, `\r` and `\t`,
respectively.
```nix You can include the result of an expression into a string by
"--with-freetype2-library=" + freetype + "/lib" enclosing it in `${...}`, a feature known as *antiquotation*. The
``` enclosed expression must evaluate to something that can be coerced
into a string (meaning that it must be a string, a path, or a
derivation). For instance, rather than writing
(where `freetype` is a derivation), you can instead write the more ```nix
natural "--with-freetype2-library=" + freetype + "/lib"
```
```nix (where `freetype` is a derivation), you can instead write the more
"--with-freetype2-library=${freetype}/lib" natural
```
The latter is automatically translated to the former. A more ```nix
complicated example (from the Nix expression for "--with-freetype2-library=${freetype}/lib"
[Qt](http://www.trolltech.com/products/qt)): ```
```nix The latter is automatically translated to the former. A more
configureFlags = " complicated example (from the Nix expression for
-system-zlib -system-libpng -system-libjpeg [Qt](http://www.trolltech.com/products/qt)):
${if openglSupport then "-dlopen-opengl
-L${mesa}/lib -I${mesa}/include
-L${libXmu}/lib -I${libXmu}/include" else ""}
${if threadSupport then "-thread" else "-no-thread"}
";
```
Note that Nix expressions and strings can be arbitrarily nested; in ```nix
this case the outer string contains various antiquotations that configureFlags = "
themselves contain strings (e.g., `"-thread"`), some of which in -system-zlib -system-libpng -system-libjpeg
turn contain expressions (e.g., `${mesa}`). ${if openglSupport then "-dlopen-opengl
-L${mesa}/lib -I${mesa}/include
-L${libXmu}/lib -I${libXmu}/include" else ""}
${if threadSupport then "-thread" else "-no-thread"}
";
```
The second way to write string literals is as an *indented string*, Note that Nix expressions and strings can be arbitrarily nested; in
which is enclosed between pairs of *double single-quotes*, like so: this case the outer string contains various antiquotations that
themselves contain strings (e.g., `"-thread"`), some of which in
turn contain expressions (e.g., `${mesa}`).
```nix The second way to write string literals is as an *indented string*,
which is enclosed between pairs of *double single-quotes*, like so:
```nix
''
This is the first line.
This is the second line.
This is the third line.
''
```
This kind of string literal intelligently strips indentation from
the start of each line. To be precise, it strips from each line a
number of spaces equal to the minimal indentation of the string as a
whole (disregarding the indentation of empty lines). For instance,
the first and second line are indented two spaces, while the third
line is indented four spaces. Thus, two spaces are stripped from
each line, so the resulting string is
```nix
"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
ignored if there is no non-whitespace text on the initial line.
Antiquotation (`${expr}`) is supported in indented strings.
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
characters can be written as `''\n`, `''\r`, `''\t`, and `''\`
escapes any other character.
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
strings representing languages such as shell scripts and
configuration files because `''` is much less common than `"`.
Example:
```nix
stdenv.mkDerivation {
...
postInstall =
'' ''
This is the first line. mkdir $out/bin $out/etc
This is the second line. cp foo $out/bin
This is the third line. echo "Hello World" > $out/etc/foo.conf
'' ${if enableBar then "cp bar $out/bin" else ""}
``` '';
...
}
```
This kind of string literal intelligently strips indentation from Finally, as a convenience, *URIs* as defined in appendix B of
the start of each line. To be precise, it strips from each line a [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as
number of spaces equal to the minimal indentation of the string as a is*, without quotes. For instance, the string
whole (disregarding the indentation of empty lines). For instance, `"http://example.org/foo.tar.bz2"` can also be written as
the first and second line are indented two spaces, while the third `http://example.org/foo.tar.bz2`.
line is indented four spaces. Thus, two spaces are stripped from
each line, so the resulting string is
```nix ### Numbers
"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 Numbers, which can be *integers* (like `123`) or *floating point*
ignored if there is no non-whitespace text on the initial line. (like `123.43` or `.27e13`).
Antiquotation (`${expr}`) is supported in indented strings. Numbers are type-compatible: pure integer operations will always
return integers, whereas any operation involving at least one
floating point number will have a floating point number as a result.
Since `${` and `''` have special meaning in indented strings, you ### Paths
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
characters can be written as `''\n`, `''\r`, `''\t`, and `''\`
escapes any other character.
Indented strings are primarily useful in that they allow multi-line *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
string literals to follow the indentation of the enclosing Nix least one slash to be recognised as such. For instance, `builder.sh`
expression, and that less escaping is typically necessary for is not a path: it's parsed as an expression that selects the
strings representing languages such as shell scripts and attribute `sh` from the variable `builder`. If the file name is
configuration files because `''` is much less common than `"`. relative, i.e., if it does not begin with a slash, it is made
Example: absolute at parse time relative to the directory of the Nix
expression that contained it. For instance, if a Nix expression in
`/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
is `/foo/xyzzy/fnord.nix`.
```nix If the first component of a path is a `~`, it is interpreted as if
stdenv.mkDerivation { the rest of the path were relative to the user's home directory.
... e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
postInstall = whose home directory is `/home/edolstra`.
''
mkdir $out/bin $out/etc
cp foo $out/bin
echo "Hello World" > $out/etc/foo.conf
${if enableBar then "cp bar $out/bin" else ""}
'';
...
}
```
Finally, as a convenience, *URIs* as defined in appendix B of Paths can also be specified between angle brackets, e.g.
[RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as `<nixpkgs>`. This means that the directories listed in the
is*, without quotes. For instance, the string environment variable `NIX_PATH` will be searched for the given file
`"http://example.org/foo.tar.bz2"` can also be written as or directory name.
`http://example.org/foo.tar.bz2`.
- Numbers, which can be *integers* (like `123`) or *floating point* Antiquotation is supported in any paths except those in angle brackets.
(like `123.43` or `.27e13`). `./${foo}-${bar}.nix` is a more convenient way of writing
`./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
least one slash must appear *before* any antiquotations for this to be
recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
operation. `./a.${foo}/b.${bar}` is a path.
Numbers are type-compatible: pure integer operations will always ### Booleans
return integers, whereas any operation involving at least one
floating point number will have a floating point number as a result.
- *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at *Booleans* with values `true` and `false`.
least one slash to be recognised as such. For instance, `builder.sh`
is not a path: it's parsed as an expression that selects the
attribute `sh` from the variable `builder`. If the file name is
relative, i.e., if it does not begin with a slash, it is made
absolute at parse time relative to the directory of the Nix
expression that contained it. For instance, if a Nix expression in
`/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
is `/foo/xyzzy/fnord.nix`.
If the first component of a path is a `~`, it is interpreted as if ### Null
the rest of the path were relative to the user's home directory.
e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
whose home directory is `/home/edolstra`.
Paths can also be specified between angle brackets, e.g. The null value, denoted as `null`.
`<nixpkgs>`. This means that the directories listed in the
environment variable `NIX_PATH` will be searched for the given file
or directory name.
Antiquotation is supported in any paths except those in angle brackets.
`./${foo}-${bar}.nix` is a more convenient way of writing
`./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At
least one slash must appear *before* any antiquotations for this to be
recognized as a path. `a.${foo}/b.${bar}` is a syntactically valid division
operation. `./a.${foo}/b.${bar}` is a path.
- *Booleans* with values `true` and `false`.
- The null value, denoted as `null`.
## Lists ## Lists