Skip to content

Commit

Permalink
Merge pull request #9116 from fricklerhandwerk/doc-import
Browse files Browse the repository at this point in the history 
reword and reformat description of `builtins.import`
  • Loading branch information
@Ericson2314
Ericson2314 committed Oct 9, 2023
2 parents 6b6bd90 + 6305801 commit 67eddc0
Show file tree
Hide file tree
Showing 3 changed files with 194 additions and 73 deletions.
152 changes: 134 additions & 18 deletions doc/manual/src/language/string-interpolation.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,12 @@
# 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).
String interpolation is a language feature where a [string], [path], or [attribute name][attribute set] 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]
Such a construct is called *interpolated string*, and the expression inside is an [interpolated expression](#interpolated-expression).

[string]: ./values.md#type-string
[path]: ./values.md#type-path
[attribute name]: ./values.md#attribute-set
[derivation]: ../glossary.md#gloss-derivation
[attribute set]: ./values.md#attribute-set

## Examples

Expand Down Expand Up @@ -70,13 +63,136 @@ you can instead write

### Attribute name

Attribute names can be created dynamically with string interpolation:
<!--
FIXME: these examples are redundant with the main page on attribute sets.
figure out what to do about that
-->

```nix
let name = "foo"; in
{
${name} = "bar";
}
```
Attribute names can be interpolated strings.

> **Example**
>
> ```nix
> let name = "foo"; in
> { ${name} = 123; }
> ```
>
> { foo = 123; }
{ foo = "bar"; }
Attributes can be selected with interpolated strings.

> **Example**
>
> ```nix
> let name = "foo"; in
> { foo = 123; }.${name}
> ```
>
> 123
# Interpolated expression

An interpolated expression must evaluate to one of the following:

- a [string]
- a [path]
- an [attribute set] that has a `__toString` attribute or an `outPath` attribute

- `__toString` must be a function that takes the attribute set itself and returns a string
- `outPath` must be a string

This includes [derivations](./derivations.md) or [flake inputs](@docroot@/command-ref/new-cli/nix3-flake.md#flake-inputs) (experimental).

A string interpolates to itself.

A path in an interpolated expression is first copied into the Nix store, and the resulting string is the [store path] of the newly created [store object](../glossary.md#gloss-store-object).

[store path]: ../glossary.md#gloss-store-path

> **Example**
>
> ```console
> $ mkdir foo
> ```
>
> Reference the empty directory in an interpolated expression:
>
> ```nix
> "${./foo}"
> ```
>
> "/nix/store/2hhl2nz5v0khbn06ys82nrk99aa1xxdw-foo"
A derivation interpolates to the [store path] of its first [output](./derivations.md#attr-outputs).
> **Example**
>
> ```nix
> let
> pkgs = import <nixpkgs> {};
> in
> "${pkgs.hello}"
> ```
>
> "/nix/store/4xpfqf29z4m8vbhrqcz064wfmb46w5r7-hello-2.12.1"
An attribute set interpolates to the return value of the function in the `__toString` applied to the attribute set itself.
> **Example**
>
> ```nix
> let
> a = {
> value = 1;
> __toString = self: toString (self.value + 1);
> };
> in
> "${a}"
> ```
>
> "2"
An attribute set also interpolates to the value of its `outPath` attribute.
> **Example**
>
> ```nix
> let
> a = { outPath = "foo"; };
> in
> "${a}"
> ```
>
> "foo"
If both `__toString` and `outPath` are present in an attribute set, `__toString` takes precedence.
> **Example**
>
> ```nix
> let
> a = { __toString = _: "yes"; outPath = throw "no"; };
> in
> "${a}"
> ```
>
> "yes"
If neither is present, an error is thrown.
> **Example**
>
> ```nix
> let
> a = {};
> in
> "${a}"
> ```
>
> error: cannot coerce a set to a string
>
> at «string»:4:2:
>
> 3| in
> 4| "${a}"
> | ^
12 changes: 5 additions & 7 deletions doc/manual/src/language/values.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,18 +112,16 @@
environment variable `NIX_PATH` will be searched for the given file
or directory name.

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.
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.

[store path]: ../glossary.md#gloss-store-path

Paths themselves, except those in angle brackets (`< >`), support [string interpolation].
Paths, except those in angle brackets (`< >`), support [string interpolation] and can be used in [interpolated expressions].
[interpolated expressions]: ./string-interpolation.md#interpolated-expressions

At least one slash (`/`) must appear *before* any interpolated expression for the result to be recognized as a path.

Expand Down
103 changes: 55 additions & 48 deletions src/libexpr/primops.cc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -258,64 +258,71 @@ static RegisterPrimOp primop_import({
.args = {"path"},
// TODO turn "normal path values" into link below
.doc = R"(
Load, parse and return the Nix expression in the file *path*.
The value *path* can be a path, a string, or an attribute set with an
`__toString` attribute or a `outPath` attribute (as derivations or flake
inputs typically have).
If *path* is a directory, the file `default.nix` in that directory
is loaded.
Evaluation aborts if the file doesn’t exist or contains
an incorrect Nix expression. `import` implements Nix’s module
system: you can put any Nix expression (such as a set or a
function) in a separate file, and use it from Nix expressions in
other files.
Load, parse, and return the Nix expression in the file *path*.
> **Note**
>
> Unlike some languages, `import` is a regular function in Nix.
> Paths using the angle bracket syntax (e.g., `import` *\<foo\>*)
> are normal [path values](@docroot@/language/values.md#type-path).
A Nix expression loaded by `import` must not contain any *free
variables* (identifiers that are not defined in the Nix expression
itself and are not built-in). Therefore, it cannot refer to
variables that are in scope at the call site. For instance, if you
have a calling expression
```nix
rec {
x = 123;
y = import ./foo.nix;
}
```
The *path* argument must meet the same criteria as an [interpolated expression](@docroot@/language/string-interpolation.md#interpolated-expression).
then the following `foo.nix` will give an error:
If *path* is a directory, the file `default.nix` in that directory is used if it exists.
```nix
x + 456
```
since `x` is not in scope in `foo.nix`. If you want `x` to be
available in `foo.nix`, you should pass it as a function argument:
```nix
rec {
x = 123;
y = import ./foo.nix x;
}
```
> **Example**
>
> ```console
> $ echo 123 > default.nix
> ```
>
> Import `default.nix` from the current directory.
>
> ```nix
> import ./.
> ```
>
> 123
and
Evaluation aborts if the file doesn’t exist or contains an invalid Nix expression.
```nix
x: x + 456
```
A Nix expression loaded by `import` must not contain any *free variables*, that is, identifiers that are not defined in the Nix expression itself and are not built-in.
Therefore, it cannot refer to variables that are in scope at the call site.
(The function argument doesn’t have to be called `x` in `foo.nix`;
any name would work.)
> **Example**
>
> If you have a calling expression
>
> ```nix
> rec {
> x = 123;
> y = import ./foo.nix;
> }
> ```
>
> then the following `foo.nix` will give an error:
>
> ```nix
> # foo.nix
> x + 456
> ```
>
> since `x` is not in scope in `foo.nix`.
> If you want `x` to be available in `foo.nix`, pass it as a function argument:
>
> ```nix
> rec {
> x = 123;
> y = import ./foo.nix x;
> }
> ```
>
> and
>
> ```nix
> # foo.nix
> x: x + 456
> ```
>
> The function argument doesn’t have to be called `x` in `foo.nix`; any name would work.
)",
.fun = [](EvalState & state, const PosIdx pos, Value * * args, Value & v)
{
Expand Down

0 comments on commit 67eddc0

Please sign in to comment.