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

Merge pull request #6846 from fricklerhandwerk/values

Browse source 
manual: use subheadings for primitive types
This commit is contained in:
Théophane Hufschmitt 2022-08-03 14:50:41 +02:00 committed by GitHub
parent 780a479386 c55bea4204
commit 7d1ccd9105
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 155 additions and 147 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/manual/src/SUMMARY.md.in
View file

@ -34,7 +34,7 @@
- [Building and Testing](expressions/simple-building-testing.md) - [Building and Testing](expressions/simple-building-testing.md)
- [Generic Builder Syntax](expressions/generic-builder.md) - [Generic Builder Syntax](expressions/generic-builder.md)
- [Nix Expression Language](expressions/expression-language.md) - [Nix Expression Language](expressions/expression-language.md)
- [Values](expressions/language-values.md) - [Data Types](expressions/language-values.md)
- [Language Constructs](expressions/language-constructs.md) - [Language Constructs](expressions/language-constructs.md)
- [Operators](expressions/language-operators.md) - [Operators](expressions/language-operators.md)
- [Derivations](expressions/derivations.md) - [Derivations](expressions/derivations.md)

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

@ -1,156 +1,164 @@
# Values # Data Types
## Simple Values ## Primitives
Nix has the following basic data types: - <a id="type-string" href="#type-string">String</a>
- *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 special
characters `"` and `\` and the character sequence `${` must be characters `"` and `\` and the character sequence `${` must be
escaped by prefixing them with a backslash (`\`). Newlines, carriage escaped by prefixing them with a backslash (`\`). Newlines, carriage
returns and tabs can be written as `\n`, `\r` and `\t`, returns and tabs can be written as `\n`, `\r` and `\t`,
respectively. respectively.
You can include the result of an expression into a string by You can include the result of an expression into a string by
enclosing it in `${...}`, a feature known as *antiquotation*. The enclosing it in `${...}`, a feature known as *antiquotation*. The
enclosed expression must evaluate to something that can be coerced enclosed expression must evaluate to something that can be coerced
into a string (meaning that it must be a string, a path, or a into a string (meaning that it must be a string, a path, or a
derivation). For instance, rather than writing derivation). For instance, rather than writing
```nix ```nix
"--with-freetype2-library=" + freetype + "/lib" "--with-freetype2-library=" + freetype + "/lib"
``` ```
(where `freetype` is a derivation), you can instead write the more (where `freetype` is a derivation), you can instead write the more
natural natural
```nix ```nix
"--with-freetype2-library=${freetype}/lib" "--with-freetype2-library=${freetype}/lib"
``` ```
The latter is automatically translated to the former. A more The latter is automatically translated to the former. A more
complicated example (from the Nix expression for complicated example (from the Nix expression for
[Qt](http://www.trolltech.com/products/qt)): [Qt](http://www.trolltech.com/products/qt)):
```nix ```nix
configureFlags = " configureFlags = "
-system-zlib -system-libpng -system-libjpeg -system-zlib -system-libpng -system-libjpeg
${if openglSupport then "-dlopen-opengl ${if openglSupport then "-dlopen-opengl
-L${mesa}/lib -I${mesa}/include -L${mesa}/lib -I${mesa}/include
-L${libXmu}/lib -I${libXmu}/include" else ""} -L${libXmu}/lib -I${libXmu}/include" else ""}
${if threadSupport then "-thread" else "-no-thread"} ${if threadSupport then "-thread" else "-no-thread"}
"; ";
``` ```
Note that Nix expressions and strings can be arbitrarily nested; in Note that Nix expressions and strings can be arbitrarily nested; in
this case the outer string contains various antiquotations that this case the outer string contains various antiquotations that
themselves contain strings (e.g., `"-thread"`), some of which in themselves contain strings (e.g., `"-thread"`), some of which in
turn contain expressions (e.g., `${mesa}`). turn contain expressions (e.g., `${mesa}`).
The second way to write string literals is as an *indented string*, The second way to write string literals is as an *indented string*,
which is enclosed between pairs of *double single-quotes*, like so: which is enclosed between pairs of *double single-quotes*, like so:
```nix ```nix
'' ''
This is the first line. This is the first line.
This is the second line. This is the second line.
This is the third line. This is the third line.
'' ''
``` ```
This kind of string literal intelligently strips indentation from This kind of string literal intelligently strips indentation from
the start of each line. To be precise, it strips from each line a 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 number of spaces equal to the minimal indentation of the string as a
whole (disregarding the indentation of empty lines). For instance, whole (disregarding the indentation of empty lines). For instance,
the first and second line are indented two spaces, while the third the first and second line are indented two spaces, while the third
line is indented four spaces. Thus, two spaces are stripped from line is indented four spaces. Thus, two spaces are stripped from
each line, so the resulting string is each line, so the resulting string is
```nix ```nix
"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 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.
Antiquotation (`${expr}`) is supported in indented strings. Antiquotation (`${expr}`) is supported in indented strings.
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., `'''`. `$` removes any special
meaning from the following `$`. 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 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
strings representing languages such as shell scripts and strings representing languages such as shell scripts and
configuration files because `''` is much less common than `"`. configuration files because `''` is much less common than `"`.
Example: Example:
```nix ```nix
stdenv.mkDerivation { stdenv.mkDerivation {
... ...
postInstall = postInstall =
'' ''
mkdir $out/bin $out/etc mkdir $out/bin $out/etc
cp foo $out/bin cp foo $out/bin
echo "Hello World" > $out/etc/foo.conf echo "Hello World" > $out/etc/foo.conf
${if enableBar then "cp bar $out/bin" else ""} ${if enableBar then "cp bar $out/bin" else ""}
''; '';
... ...
} }
``` ```
Finally, as a convenience, *URIs* as defined in appendix B of Finally, as a convenience, *URIs* as defined in appendix B of
[RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as
is*, without quotes. For instance, the string is*, without quotes. For instance, the string
`"http://example.org/foo.tar.bz2"` can also be written as `"http://example.org/foo.tar.bz2"` can also be written as
`http://example.org/foo.tar.bz2`. `http://example.org/foo.tar.bz2`.
- Numbers, which can be *integers* (like `123`) or *floating point* - <a id="type-number" href="#type-number">Number</a>
(like `123.43` or `.27e13`).
Numbers are type-compatible: pure integer operations will always Numbers, which can be *integers* (like `123`) or *floating point*
return integers, whereas any operation involving at least one (like `123.43` or `.27e13`).
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 Numbers are type-compatible: pure integer operations will always
least one slash to be recognised as such. For instance, `builder.sh` return integers, whereas any operation involving at least one
is not a path: it's parsed as an expression that selects the floating point number will have a floating point number as a result.
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 - <a id="type-path" href="#type-path">Path</a>
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. *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
`<nixpkgs>`. This means that the directories listed in the least one slash to be recognised as such. For instance, `builder.sh`
environment variable `NIX_PATH` will be searched for the given file is not a path: it's parsed as an expression that selects the
or directory name. 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`.
Antiquotation is supported in any paths except those in angle brackets. If the first component of a path is a `~`, it is interpreted as if
`./${foo}-${bar}.nix` is a more convenient way of writing the rest of the path were relative to the user's home directory.
`./. + "/" + foo + "-" + bar + ".nix"` or `./. + "/${foo}-${bar}.nix"`. At e.g. `~/foo` would be equivalent to `/home/edolstra/foo` for a user
least one slash must appear *before* any antiquotations for this to be whose home directory is `/home/edolstra`.
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`. Paths can also be specified between angle brackets, e.g.
`<nixpkgs>`. This means that the directories listed in the
environment variable `NIX_PATH` will be searched for the given file
or directory name.
- The null value, denoted as `null`. 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.
## Lists - <a id="type-boolean" href="#type-boolean">Boolean</a>
*Booleans* with values `true` and `false`.
- <a id="type-null" href="#type-null">Null</a>
The null value, denoted as `null`.
## List
Lists are formed by enclosing a whitespace-separated list of values Lists are formed by enclosing a whitespace-separated list of values
between square brackets. For example, between square brackets. For example,
@ -172,9 +180,9 @@ 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.
## Attribute Sets ## Attribute Set
Attribute sets are collections of name-value-pairs (called *attributes*) enclosed in curly brackets (`{ }`). An attribute set is a collection of name-value-pairs (called *attributes*) enclosed in curly brackets (`{ }`).
Names and values are separated by an equal sign (`=`). Names and values are separated by an equal sign (`=`).
Each value is an arbitrary expression terminated by a semicolon (`;`). Each value is an arbitrary expression terminated by a semicolon (`;`).