picnoir/Nix
1
0
Fork 0
Code Issues Pull requests 1 Releases Wiki Activity

reword and reformat description of builtins.import

Browse source
This commit is contained in:
Valentin Gagarin 2023-10-07 02:53:41 +02:00
parent a7ba8c3f4a
commit 6305801626
1 changed files with 55 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

101
src/libexpr/primops.cc
View file

@ -258,62 +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 *path* argument must meet the same criteria as an [interpolated expression](@docroot@/language/string-interpolation.md#interpolated-expression).
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
The *path* argument must meet the same criteria as an [interpolated expression](@docroot@/language/string-interpolation.md#interpolated-expression).
```nix
rec {
x = 123;
y = import ./foo.nix;
}
```
If *path* is a directory, the file `default.nix` in that directory is used if it exists.
then the following `foo.nix` will give an error:
> **Example**
>
> ```console
> $ echo 123 > default.nix
> ```
>
> Import `default.nix` from the current directory.
>
> ```nix
> import ./.
> ```
>
> 123
```nix
x + 456
```
Evaluation aborts if the file doesn’t exist or contains an invalid Nix expression.
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:
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.
```nix
rec {
x = 123;
y = import ./foo.nix x;
}
```
and
```nix
x: x + 456
```
(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)
{