Skip to content

Commit

Permalink
Merge pull request #10620 from nh2/patch-2
Browse files Browse the repository at this point in the history 
manual: language: Explain that `with` does not shadow
  • Loading branch information
@Ericson2314
Ericson2314 authored May 8, 2024
2 parents 0930058 + a5252c9 commit d8d2030
Show file tree
Hide file tree
Showing 2 changed files with 80 additions and 33 deletions.
29 changes: 29 additions & 0 deletions doc/manual/src/language/constructs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -402,7 +402,36 @@ 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 is [statically scoped](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scope), but with multiple scopes and shadowing rules.

* primary scope --- explicitly-bound variables
* [`let`](#let-expressions)
* [`inherit`](#inheriting-attributes)
* function arguments

* secondary scope --- implicitly-bound variables
* [`with`](#with-expressions)

Primary scope takes precedence over secondary scope.
See [`with`](#with-expressions) for a detailed example.
84 changes: 51 additions & 33 deletions doc/manual/src/language/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>

Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand All @@ -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>
Expand Down

0 comments on commit d8d2030

Please sign in to comment.