max/nix-super
1
0
Fork 0
mirror of https://github.com/privatevoid-net/nix-super.git synced 2024-11-22 05:56:15 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

language: Link examples to detail explanations.

Browse source 
Also, warn of the scoping caveats of `with`.
This commit is contained in:
Niklas Hambüchen 2024-04-29 03:57:28 +02:00
parent 2f678331d5
commit 460d8fbaea
2 changed files with 79 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
doc/manual/src/language/constructs.md
View file

@ -402,7 +402,35 @@ establishes the same scope as
let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...
```
Variables coming from outer `with` expressions *are* shadowed:
```nix
with { a = "outer"; };
with { a = "inner"; };
a
```
Does evaluate to `"inner"`.
## Comments
Comments can be single-line, started with a `#` character, or
inline/multi-line, enclosed within `/* ... */`.
`#` comments last until the end of the line.
`/*` comments run until the next occurrence of `*/`; this cannot be escaped.
## Scoping rules
Nix has constructs with
* dynamic scope
* [`with`](#with-expressions)
* static scope
* [`let`](#let-expressions)
* [`inherit`](#inheriting-attributes)
* function arguments
Static scope takes precedence over dynamic scope.
See [`with`](#with-expressions) for a detailed example.

84
doc/manual/src/language/index.md
View file

@ -53,7 +53,7 @@ This is an incomplete overview of language features, by example.
<td>
*Basic values*
*Basic values ([primitives](@docroot@/language/values.md#primitives))*
</td>
@ -71,7 +71,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A string
A [string](@docroot@/language/values.md#type-string)
</td>
</tr>
@ -94,6 +94,18 @@ This is an incomplete overview of language features, by example.
</td>
</tr>
<tr>
<td>
`# Explanation`
</td>
<td>
A [comment](@docroot@/language/constructs.md#comments).
</td>
</tr>
<tr>
<td>
@ -106,7 +118,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
String interpolation (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
[String interpolation](@docroot@/language/string-interpolation.md) (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
</td>
</tr>
@ -118,7 +130,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Booleans
[Booleans](@docroot@/language/values.md#type-boolean)
</td>
</tr>
@ -130,7 +142,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Null value
[Null](@docroot@/language/values.md#type-null) value
</td>
</tr>
@ -142,7 +154,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
An integer
An [integer](@docroot@/language/values.md#type-number)
</td>
</tr>
@ -154,7 +166,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A floating point number
A [floating point number](@docroot@/language/values.md#type-number)
</td>
</tr>
@ -166,7 +178,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
An absolute path
An absolute [path](@docroot@/language/values.md#type-path)
</td>
</tr>
@ -178,7 +190,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A path relative to the file containing this Nix expression
A [path](@docroot@/language/values.md#type-path) relative to the file containing this Nix expression
</td>
</tr>
@ -190,7 +202,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A home path. Evaluates to the `"<user's home directory>/.config"`.
A home [path](@docroot@/language/values.md#type-path). Evaluates to the `"<user's home directory>/.config"`.
</td>
</tr>
@ -202,7 +214,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Search path for Nix files. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
A [lookup path](@docroot@/language/constructs/lookup-path.md) for Nix files. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
</td>
</tr>
@ -226,7 +238,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A set with attributes named `x` and `y`
An [attribute set](@docroot@/language/values.md#attribute-set) with attributes named `x` and `y`
</td>
</tr>
@ -250,7 +262,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }`
A [recursive set](@docroot@/language/constructs.md#recursive-sets), equivalent to `{ x = "foo"; y = "foobar"; }`.
</td>
</tr>
@ -266,7 +278,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Lists with three elements.
[Lists](@docroot@/language/values.md#list) with three elements.
</td>
</tr>
@ -350,7 +362,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Attribute selection (evaluates to `1`)
[Attribute selection](@docroot@/language/values.md#attribute-set) (evaluates to `1`)
</td>
</tr>
@ -362,7 +374,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Attribute selection with default (evaluates to `3`)
[Attribute selection](@docroot@/language/values.md#attribute-set) with default (evaluates to `3`)
</td>
</tr>
@ -398,7 +410,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Conditional expression
[Conditional expression](@docroot@/language/constructs.md#conditionals).
</td>
</tr>
@ -410,7 +422,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Assertion check (evaluates to `"yes!"`).
[Assertion](@docroot@/language/constructs.md#assertions) check (evaluates to `"yes!"`).
</td>
</tr>
@ -422,7 +434,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Variable definition
Variable definition. See [`let`-expressions](@docroot@/language/constructs.md#let-expressions).
</td>
</tr>
@ -434,7 +446,9 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Add all attributes from the given set to the scope (evaluates to `1`)
Add all attributes from the given set to the scope (evaluates to `1`).
See [`with`-expressions](@docroot@/language/constructs.md#with-expressions) for details and shadowing caveats.
</td>
</tr>
@ -447,7 +461,8 @@ This is an incomplete overview of language features, by example.
<td>
Adds the variables to the current scope (attribute set or `let` binding).
Desugars to `pkgs = pkgs; src = src;`
Desugars to `pkgs = pkgs; src = src;`.
See [Inheriting attributes](@docroot@/language/constructs.md#inheriting-attributes).
</td>
</tr>
@ -460,14 +475,15 @@ This is an incomplete overview of language features, by example.
<td>
Adds the attributes, from the attribute set in parentheses, to the current scope (attribute set or `let` binding).
Desugars to `lib = pkgs.lib; stdenv = pkgs.stdenv;`
Desugars to `lib = pkgs.lib; stdenv = pkgs.stdenv;`.
See [Inheriting attributes](@docroot@/language/constructs.md#inheriting-attributes).
</td>
</tr>
<tr>
<td>
*Functions (lambdas)*
*[Functions](@docroot@/language/constructs.md#functions) (lambdas)*
</td>
<td>
@ -484,7 +500,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A function that expects an integer and returns it increased by 1
A [function](@docroot@/language/constructs.md#functions) that expects an integer and returns it increased by 1.
</td>
</tr>
@ -496,7 +512,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Curried function, equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
Curried [function](@docroot@/language/constructs.md#functions), equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
</td>
</tr>
@ -508,7 +524,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A function call (evaluates to 101)
A [function](@docroot@/language/constructs.md#functions) call (evaluates to 101)
</td>
</tr>
@ -520,7 +536,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A function bound to a variable and subsequently called by name (evaluates to 103)
A [function](@docroot@/language/constructs.md#functions) bound to a variable and subsequently called by name (evaluates to 103)
</td>
</tr>
@ -532,7 +548,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A function that expects a set with required attributes `x` and `y` and concatenates them
A [function](@docroot@/language/constructs.md#functions) that expects a set with required attributes `x` and `y` and concatenates them
</td>
</tr>
@ -544,7 +560,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
A [function](@docroot@/language/constructs.md#functions) that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
</td>
</tr>
@ -556,7 +572,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A function that expects a set with required attributes `x` and `y` and ignores any other attributes
A [function](@docroot@/language/constructs.md#functions) that expects a set with required attributes `x` and `y` and ignores any other attributes
</td>
</tr>
@ -570,7 +586,7 @@ This is an incomplete overview of language features, by example.
</td>
<td>
A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
A [function](@docroot@/language/constructs.md#functions) that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
</td>
</tr>
@ -594,7 +610,8 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Load and return Nix expression in given file
Load and return Nix expression in given file.
See [import](@docroot@/language/builtins.md#builtins-import).
</td>
</tr>
@ -606,7 +623,8 @@ This is an incomplete overview of language features, by example.
</td>
<td>
Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`)
Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`).
See [`map`](@docroot@/language/builtins.md#builtins-map).
</td>
</tr>