diff options
Diffstat (limited to 'doc/manual/src')
| -rw-r--r-- | doc/manual/src/SUMMARY.md.in | 1 | ||||
| -rw-r--r-- | doc/manual/src/glossary.md | 11 | ||||
| -rw-r--r-- | doc/manual/src/language/string-interpolation.md | 82 | ||||
| -rw-r--r-- | doc/manual/src/language/values.md | 103 | ||||
| -rw-r--r-- | doc/manual/src/release-notes/rl-next.md | 17 |
5 files changed, 134 insertions, 80 deletions
diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index 6a514fa2c..24dbb739f 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/SUMMARY.md.in @@ -29,6 +29,7 @@ - [Nix Language](language/index.md) - [Data Types](language/values.md) - [Language Constructs](language/constructs.md) + - [String interpolation](language/string-interpolation.md) - [Operators](language/operators.md) - [Derivations](language/derivations.md) - [Advanced Attributes](language/advanced-attributes.md) diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 0fcc2b07b..e63f6becc 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -60,7 +60,7 @@ cache](https://cache.nixos.org). - [store path]{#gloss-store-path}\ - The location in the file system of a store object, i.e., an + The location of a [store object] in the file system, i.e., an immediate child of the Nix store directory. Example: `/nix/store/a040m110amc4h71lds2jmr8qrkj2jhxd-git-2.38.1` @@ -178,3 +178,12 @@ - [`ε`]{#gloss-epsilon}\ The epsilon symbol. In the context of a package, this means the version is empty. More precisely, the derivation does not have a version attribute. + + - [string interpolation]{#gloss-string-interpolation}\ + Expanding expressions enclosed in `${ }` within a [string], [path], or [attribute name]. + + See [String interpolation](./language/string-interpolation.md) for details. + + [string]: ./language/values.md#type-string + [path]: ./language/values.md#type-path + [attribute name]: ./language/values.md#attribute-set 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 6fc8c0369..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,26 +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 a path appears in an antiquotation, and is thus coerced into a string, - the path is first copied into the Nix store and the resulting string is - the Nix store path. For instance `"${./foo.txt}" will cause `foo.txt` in - the current directory to be copied into the Nix store and result in the - string `"/nix/store/<HASH>-foo.txt"`. - - Note that the Nix language assumes that all input files will remain - _unchanged_ during the course of the Nix expression evaluation. - If you for example antiquote a file path during a `nix repl` session, and - then later in the same session, after having changed the file contents, - evaluate the antiquotation with the file path again, then Nix will still - return the first store path. It will _not_ reread the file contents to - produce a different Nix store 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/<hash>-foo.txt"`. + + Note that the Nix language assumes that all input files will remain _unchanged_ while evaluating a Nix expression. + For example, assume you used a file path in an interpolated string during a `nix repl` session. + Later in the same session, after having changed the file contents, evaluating the interpolated string with the file path again might not return a new store path, since Nix might not re-read the file contents. + + Paths themselves, except those in angle brackets (`< >`), support [string interpolation]. + + At least one slash (`/`) must appear *before* any interpolated expression for the result 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> @@ -235,23 +200,33 @@ will evaluate to `"Xyzzy"` because there is no `c` attribute in the set. You can use arbitrary double-quoted strings as attribute names: ```nix -{ "foo ${bar}" = 123; "nix-1.0" = 456; }."foo ${bar}" +{ "$!@#?" = 123; }."$!@#?" +``` + +```nix +let bar = "bar"; +{ "foo ${bar}" = 123; }."foo ${bar}" ``` -This will evaluate to `123` (Assuming `bar` is antiquotable). In the -case where an attribute name is just a single antiquotation, the quotes -can be dropped: +Both will evaluate to `123`. + +Attribute names support [string interpolation]: + +```nix +let bar = "foo"; in +{ foo = 123; }.${bar} +``` ```nix -{ foo = 123; }.${bar} or 456 +let bar = "foo"; in +{ ${bar} = 123; }.foo ``` -This will evaluate to `123` if `bar` evaluates to `"foo"` when coerced -to a string and `456` otherwise (again assuming `bar` is antiquotable). +Both will evaluate to `123`. In the special case where an attribute name inside of a set declaration -evaluates to `null` (which is normally an error, as `null` is not -antiquotable), that attribute is simply not added to the set: +evaluates to `null` (which is normally an error, as `null` cannot be coerced to +a string), that attribute is simply not added to the set: ```nix { ${if foo then "bar" else null} = true; } diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md index 906b048f1..8119b7c31 100644 --- a/doc/manual/src/release-notes/rl-next.md +++ b/doc/manual/src/release-notes/rl-next.md @@ -15,19 +15,6 @@ # NIX_PATH=nixpkgs=flake:nixpkgs nix-build '<nixpkgs>' -A hello ``` -* Allow explicitly selecting outputs in a store derivation installable, just like we can do with other sorts of installables. - For example, - ```shell-session - $ nix-build /nix/store/gzaflydcr6sb3567hap9q6srzx8ggdgg-glibc-2.33-78.drv^dev` - ``` - now works just as - ```shell-session - $ nix-build glibc^dev` - ``` - does already. +* Instead of "antiquotation", the more common term [string interpolation](../language/string-interpolation.md) is now used consistently. + Historical release notes were not changed. -* On Linux, `nix develop` now sets the - [*personality*](https://man7.org/linux/man-pages/man2/personality.2.html) - for the development shell in the same way as the actual build of the - derivation. This makes shells for `i686-linux` derivations work - correctly on `x86_64-linux`. |