From 460d8fbaea6c5600b88efe1be84623c7fa32b073 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niklas=20Hamb=C3=BCchen?= Date: Mon, 29 Apr 2024 03:57:28 +0200 Subject: [PATCH 1/2] language: Link examples to detail explanations. Also, warn of the scoping caveats of `with`. --- doc/manual/src/language/constructs.md | 28 +++++++++ doc/manual/src/language/index.md | 84 ++++++++++++++++----------- 2 files changed, 79 insertions(+), 33 deletions(-) diff --git a/doc/manual/src/language/constructs.md b/doc/manual/src/language/constructs.md index a82ec5960a8..ad1fdfe5f7f 100644 --- a/doc/manual/src/language/constructs.md +++ b/doc/manual/src/language/constructs.md @@ -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. diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md index 650412f1b5d..3694480d718 100644 --- a/doc/manual/src/language/index.md +++ b/doc/manual/src/language/index.md @@ -53,7 +53,7 @@ This is an incomplete overview of language features, by example. - *Basic values* + *Basic values ([primitives](@docroot@/language/values.md#primitives))* @@ -71,7 +71,7 @@ This is an incomplete overview of language features, by example. - A string + A [string](@docroot@/language/values.md#type-string) @@ -94,6 +94,18 @@ This is an incomplete overview of language features, by example. + + + + `# Explanation` + + + + + A [comment](@docroot@/language/constructs.md#comments). + + + @@ -106,7 +118,7 @@ This is an incomplete overview of language features, by example. - String interpolation (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/-bash-/bin/sh"`) + [String interpolation](@docroot@/language/string-interpolation.md) (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/-bash-/bin/sh"`) @@ -118,7 +130,7 @@ This is an incomplete overview of language features, by example. - Booleans + [Booleans](@docroot@/language/values.md#type-boolean) @@ -130,7 +142,7 @@ This is an incomplete overview of language features, by example. - Null value + [Null](@docroot@/language/values.md#type-null) value @@ -142,7 +154,7 @@ This is an incomplete overview of language features, by example. - An integer + An [integer](@docroot@/language/values.md#type-number) @@ -154,7 +166,7 @@ This is an incomplete overview of language features, by example. - A floating point number + A [floating point number](@docroot@/language/values.md#type-number) @@ -166,7 +178,7 @@ This is an incomplete overview of language features, by example. - An absolute path + An absolute [path](@docroot@/language/values.md#type-path) @@ -178,7 +190,7 @@ This is an incomplete overview of language features, by example. - 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 @@ -190,7 +202,7 @@ This is an incomplete overview of language features, by example. - A home path. Evaluates to the `"/.config"`. + A home [path](@docroot@/language/values.md#type-path). Evaluates to the `"/.config"`. @@ -202,7 +214,7 @@ This is an incomplete overview of language features, by example. - 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). @@ -226,7 +238,7 @@ This is an incomplete overview of language features, by example. - A set with attributes named `x` and `y` + An [attribute set](@docroot@/language/values.md#attribute-set) with attributes named `x` and `y` @@ -250,7 +262,7 @@ This is an incomplete overview of language features, by example. - A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }` + A [recursive set](@docroot@/language/constructs.md#recursive-sets), equivalent to `{ x = "foo"; y = "foobar"; }`. @@ -266,7 +278,7 @@ This is an incomplete overview of language features, by example. - Lists with three elements. + [Lists](@docroot@/language/values.md#list) with three elements. @@ -350,7 +362,7 @@ This is an incomplete overview of language features, by example. - Attribute selection (evaluates to `1`) + [Attribute selection](@docroot@/language/values.md#attribute-set) (evaluates to `1`) @@ -362,7 +374,7 @@ This is an incomplete overview of language features, by example. - Attribute selection with default (evaluates to `3`) + [Attribute selection](@docroot@/language/values.md#attribute-set) with default (evaluates to `3`) @@ -398,7 +410,7 @@ This is an incomplete overview of language features, by example. - Conditional expression + [Conditional expression](@docroot@/language/constructs.md#conditionals). @@ -410,7 +422,7 @@ This is an incomplete overview of language features, by example. - Assertion check (evaluates to `"yes!"`). + [Assertion](@docroot@/language/constructs.md#assertions) check (evaluates to `"yes!"`). @@ -422,7 +434,7 @@ This is an incomplete overview of language features, by example. - Variable definition + Variable definition. See [`let`-expressions](@docroot@/language/constructs.md#let-expressions). @@ -434,7 +446,9 @@ This is an incomplete overview of language features, by example. - 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. @@ -447,7 +461,8 @@ This is an incomplete overview of language features, by example. 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). @@ -460,14 +475,15 @@ This is an incomplete overview of language features, by example. 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). - *Functions (lambdas)* + *[Functions](@docroot@/language/constructs.md#functions) (lambdas)* @@ -484,7 +500,7 @@ This is an incomplete overview of language features, by example. - 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. @@ -496,7 +512,7 @@ This is an incomplete overview of language features, by example. - 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. @@ -508,7 +524,7 @@ This is an incomplete overview of language features, by example. - A function call (evaluates to 101) + A [function](@docroot@/language/constructs.md#functions) call (evaluates to 101) @@ -520,7 +536,7 @@ This is an incomplete overview of language features, by example. - 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) @@ -532,7 +548,7 @@ This is an incomplete overview of language features, by example. - 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 @@ -544,7 +560,7 @@ This is an incomplete overview of language features, by example. - 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` @@ -556,7 +572,7 @@ This is an incomplete overview of language features, by example. - 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 @@ -570,7 +586,7 @@ This is an incomplete overview of language features, by example. - 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` @@ -594,7 +610,8 @@ This is an incomplete overview of language features, by example. - Load and return Nix expression in given file + Load and return Nix expression in given file. + See [import](@docroot@/language/builtins.md#builtins-import). @@ -606,7 +623,8 @@ This is an incomplete overview of language features, by example. - 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). From a5252c99794a81730b030a8fcc356e1f74537198 Mon Sep 17 00:00:00 2001 From: John Ericson Date: Wed, 8 May 2024 11:18:17 -0400 Subject: [PATCH 2/2] doc: Reword scoping section "dynamic scope" is not accurate, so reword. The underlying idea is good however. --- doc/manual/src/language/constructs.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/manual/src/language/constructs.md b/doc/manual/src/language/constructs.md index ad1fdfe5f7f..4d75ea82c85 100644 --- a/doc/manual/src/language/constructs.md +++ b/doc/manual/src/language/constructs.md @@ -423,14 +423,15 @@ inline/multi-line, enclosed within `/* ... */`. ## Scoping rules -Nix has constructs with +Nix is [statically scoped](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scope), but with multiple scopes and shadowing rules. -* dynamic scope - * [`with`](#with-expressions) -* static scope +* primary scope --- explicitly-bound variables * [`let`](#let-expressions) * [`inherit`](#inheriting-attributes) * function arguments -Static scope takes precedence over dynamic scope. +* secondary scope --- implicitly-bound variables + * [`with`](#with-expressions) + +Primary scope takes precedence over secondary scope. See [`with`](#with-expressions) for a detailed example.