+
+ |
+ Example
+ |
+
+ Description
+ |
+
+
+ |
+
+
+ *Basic values*
+
+
+ |
+
+
+
+
+ |
+
+
+ |
+
+ `"hello world"`
+
+ |
+
+
+ A string
+
+ |
+
+
+ |
+
+ ```
+ ''
+ multi
+ line
+ string
+ ''
+ ```
+
+ |
+
+
+ A multi-line string. Strips common prefixed whitespace. Evaluates to `"multi\n line\n string"`.
+
+ |
+
+
+ |
+
+ `"hello ${ { a = "world" }.a }"`
+
+ `"1 2 ${toString 3}"`
+
+ `"${pkgs.bash}/bin/sh"`
+
+ |
+
+
+ String interpolation (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/-bash-/bin/sh"`)
+
+ |
+
+
+ |
+
+ `true`, `false`
+
+ |
+
+
+ Booleans
+
+ |
+
+
+ |
+
+ `null`
+
+ |
+
+
+ Null value
+
+ |
+
+
+ |
+
+ `123`
+
+ |
+
+
+ An integer
+
+ |
+
+
+ |
+
+ `3.141`
+
+ |
+
+
+ A floating point number
+
+ |
+
+
+ |
+
+ `/etc`
+
+ |
+
+
+ An absolute path
+
+ |
+
+
+ |
+
+ `./foo.png`
+
+ |
+
+
+ A path relative to the file containing this Nix expression
+
+ |
+
+
+ |
+
+ `~/.config`
+
+ |
+
+
+ A home path. Evaluates to the `"/.config"`.
+
+ |
+
+
+ |
+
+
+
+ |
+
+
+ Search path. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
+
+ |
+
+
+ |
+
+ *Compound values*
+
+ |
+
+
+
+
+ |
+
+
+ |
+
+ `{ x = 1; y = 2; }`
+
+ |
+
+
+ A set with attributes named `x` and `y`
+
+ |
+
+
+ |
+
+ `{ foo.bar = 1; }`
+
+ |
+
+
+ A nested set, equivalent to `{ foo = { bar = 1; }; }`
+
+ |
+
+
+ |
+
+ `rec { x = "foo"; y = x + "bar"; }`
+
+ |
+
+
+ A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }`
+
+ |
+
+
+ |
+
+ `[ "foo" "bar" "baz" ]`
+
+ `[ 1 2 3 ]`
+
+ `[ (f 1) { a = 1; b = 2; } [ "c" ] ]`
+
+ |
+
+
+ Lists with three elements.
+
+ |
+
+
+ |
+
+ *Operators*
+
+ |
+
+
+
+
+ |
+
+
+ |
+
+ `"foo" + "bar"`
+
+ |
+
+
+ String concatenation
+
+ |
+
+
+ |
+
+ `1 + 2`
+
+ |
+
+
+ Integer addition
+
+ |
+
+
+ |
+
+ `"foo" == "f" + "oo"`
+
+ |
+
+
+ Equality test (evaluates to `true`)
+
+ |
+
+
+ |
+
+ `"foo" != "bar"`
+
+ |
+
+
+ Inequality test (evaluates to `true`)
+
+ |
+
+
+ |
+
+ `!true`
+
+ |
+
+
+ Boolean negation
+
+ |
+
+
+ |
+
+ `{ x = 1; y = 2; }.x`
+
+ |
+
+
+ Attribute selection (evaluates to `1`)
+
+ |
+
+
+ |
+
+ `{ x = 1; y = 2; }.z or 3`
+
+ |
+
+
+ Attribute selection with default (evaluates to `3`)
+
+ |
+
+
+ |
+
+ `{ x = 1; y = 2; } // { z = 3; }`
+
+ |
+
+
+ Merge two sets (attributes in the right-hand set taking precedence)
+
+ |
+
+
+ |
+
+ *Control structures*
+
+ |
+
+
+
+
+ |
+
+
+ |
+
+ `if 1 + 1 == 2 then "yes!" else "no!"`
+
+ |
+
+
+ Conditional expression
+
+ |
+
+
+ |
+
+ `assert 1 + 1 == 2; "yes!"`
+
+ |
+
+
+ Assertion check (evaluates to `"yes!"`).
+
+ |
+
+
+ |
+
+ `let x = "foo"; y = "bar"; in x + y`
+
+ |
+
+
+ Variable definition
+
+ |
+
+
+ |
+
+ `with builtins; head [ 1 2 3 ]`
+
+ |
+
+
+ Add all attributes from the given set to the scope (evaluates to `1`)
+
+ |
+
+
+ |
+
+ *Functions (lambdas)*
+
+ |
+
+
+
+
+ |
+
+
+ |
+
+ `x: x + 1`
+
+ |
+
+
+ A function that expects an integer and returns it increased by 1
+
+ |
+
+
+ |
+
+ `x: y: x + y`
+
+ |
+
+
+ Curried function, equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
+
+ |
+
+
+ |
+
+ `(x: x + 1) 100`
+
+ |
+
+
+ A function call (evaluates to 101)
+
+ |
+
+
+ |
+
+ `let inc = x: x + 1; in inc (inc (inc 100))`
+
+ |
+
+
+ A function bound to a variable and subsequently called by name (evaluates to 103)
+
+ |
+
+
+ |
+
+ `{ x, y }: x + y`
+
+ |
+
+
+ A function that expects a set with required attributes `x` and `y` and concatenates them
+
+ |
+
+
+ |
+
+ `{ x, y ? "bar" }: x + y`
+
+ |
+
+
+ A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
+
+ |
+
+
+ |
+
+ `{ x, y, ... }: x + y`
+
+ |
+
+
+ A function that expects a set with required attributes `x` and `y` and ignores any other attributes
+
+ |
+
+
+ |
+
+ `{ x, y } @ args: x + y`
+
+ `args @ { x, y }: x + y`
+
+ |
+
+
+ A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
+
+ |
+
+
+ |
+
+ *Built-in functions*
+
+ |
+
+
+
+
+ |
+
+
+ |
+
+ `import ./foo.nix`
+
+ |
+
+
+ Load and return Nix expression in given file
+
+ |
+
+
+ |
+
+ `map (x: x + x) [ 1 2 3 ]`
+
+ |
+
+
+ Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`)
+
+ |
+
+
diff --git a/doc/manual/src/language/string-interpolation.md b/doc/manual/src/language/string-interpolation.md
new file mode 100644
index 000000000..ddc6b8230
--- /dev/null
+++ b/doc/manual/src/language/string-interpolation.md
@@ -0,0 +1,82 @@
+# String interpolation
+
+String interpolation is a language feature where a [string], [path], or [attribute name] can contain expressions enclosed in `${ }` (dollar-sign with curly brackets).
+
+Such a string is an *interpolated string*, and an expression inside is an *interpolated expression*.
+
+Interpolated expressions must evaluate to one of the following:
+
+- a [string]
+- a [path]
+- a [derivation]
+
+[string]: ./values.md#type-string
+[path]: ./values.md#type-path
+[attribute name]: ./values.md#attribute-set
+[derivation]: ../glossary.md#gloss-derivation
+
+## Examples
+
+### String
+
+Rather than writing
+
+```nix
+"--with-freetype2-library=" + freetype + "/lib"
+```
+
+(where `freetype` is a [derivation]), you can instead write
+
+```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 interpolated expressions that themselves contain strings (e.g., `"-thread"`), some of which in turn contain interpolated expressions (e.g., `${mesa}`).
+
+### Path
+
+Rather than writing
+
+```nix
+./. + "/" + foo + "-" + bar + ".nix"
+```
+
+or
+
+```nix
+./. + "/${foo}-${bar}.nix"
+```
+
+you can instead write
+
+```nix
+./${foo}-${bar}.nix
+```
+
+### Attribute name
+
+Attribute names can be created dynamically with string interpolation:
+
+```nix
+let name = "foo"; in
+{
+ ${name} = "bar";
+}
+```
+
+ { foo = "bar"; }
diff --git a/doc/manual/src/language/values.md b/doc/manual/src/language/values.md
index f09400d02..08baa8f95 100644
--- a/doc/manual/src/language/values.md
+++ b/doc/manual/src/language/values.md
@@ -13,41 +13,9 @@
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
+ You can include the results of other expressions into a string by enclosing them in `${ }`, a feature known as [string interpolation].
- ```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}`).
+ [string interpolation]: ./string-interpolation.md
The second way to write string literals is as an *indented string*,
which is enclosed between pairs of *double single-quotes*, like so:
@@ -75,7 +43,7 @@
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.
+ 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
@@ -143,12 +111,23 @@
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.
+ When an [interpolated string][string interpolation] evaluates to a path, the path is first copied into the Nix store and the resulting string is the [store path] of the newly created [store object].
+
+ [store path]: ../glossary.md#gloss-store-path
+ [store object]: ../glossary.md#gloss-store-object
+
+ For instance, evaluating `"${./foo.txt}"` will cause `foo.txt` in the current directory to be copied into the Nix store and result in the string `"/nix/store/