diff options
Diffstat (limited to 'doc/manual/src')
| -rw-r--r-- | doc/manual/src/expressions/language-values.md | 310 |
1 files changed, 155 insertions, 155 deletions
diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md index 4aa354ba6..a53b2cb22 100644 --- a/doc/manual/src/expressions/language-values.md +++ b/doc/manual/src/expressions/language-values.md @@ -2,161 +2,161 @@ ## Primitives -### String - -*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. - -You can include the result of an expression into a string by -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 - -```nix -"--with-freetype2-library=" + freetype + "/lib" -``` - -(where `freetype` is a derivation), you can instead write the more -natural - -```nix -"--with-freetype2-library=${freetype}/lib" -``` - -The latter is automatically translated to the former. A more -complicated example (from the Nix expression for -[Qt](http://www.trolltech.com/products/qt)): - -```nix -configureFlags = " - -system-zlib -system-libpng -system-libjpeg - ${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 -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}`). - -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 = - '' - 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 -[RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as -is*, without quotes. For instance, the string -`"http://example.org/foo.tar.bz2"` can also be written as -`http://example.org/foo.tar.bz2`. - -### Number - -Numbers, which can be *integers* (like `123`) or *floating point* -(like `123.43` or `.27e13`). - -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. - -### Path - -*Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at -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 -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. -`<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. - -### Boolean - -*Booleans* with values `true` and `false`. - -### Null - -The null value, denoted as `null`. +- <a id="#type-string" href="#type-string">String</a> + + *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. + + You can include the result of an expression into a string by + 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 + + ```nix + "--with-freetype2-library=" + freetype + "/lib" + ``` + + (where `freetype` is a derivation), you can instead write the more + natural + + ```nix + "--with-freetype2-library=${freetype}/lib" + ``` + + The latter is automatically translated to the former. A more + complicated example (from the Nix expression for + [Qt](http://www.trolltech.com/products/qt)): + + ```nix + configureFlags = " + -system-zlib -system-libpng -system-libjpeg + ${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 + 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}`). + + 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 = + '' + 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 + [RFC 2396](http://www.ietf.org/rfc/rfc2396.txt) can be written *as + is*, without quotes. For instance, the string + `"http://example.org/foo.tar.bz2"` can also be written as + `http://example.org/foo.tar.bz2`. + +- <a id="#type-number" href="#type-number">Number</a> + + Numbers, which can be *integers* (like `123`) or *floating point* + (like `123.43` or `.27e13`). + + 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. + +- <a id="#type-path" href="#type-path">Path</a> + + *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at + 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 + 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. + `<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. + +- <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 |