From d8e452a91b4440a049c03dec118c439fa773e323 Mon Sep 17 00:00:00 2001 From: stuebinm Date: Tue, 28 May 2024 15:58:13 +0200 Subject: [PATCH] document context-dependent keywords Documents some of the weirdness of __curPos and the or keyword. This does not fit well into any existing section for either of them, though the use of or as a quasi-operator is mentioned in the section on operators. Addresses https://git.lix.systems/lix-project/lix/issues/353 Change-Id: I7c906c8368843dca6944e8b22573b6d201cd9a76 --- doc/manual/src/language/builtin-constants.md | 11 ++++ doc/manual/src/language/constructs.md | 67 ++++++++++++++++++++ 2 files changed, 78 insertions(+) diff --git a/doc/manual/src/language/builtin-constants.md b/doc/manual/src/language/builtin-constants.md index 74e87146f..970bf6c5a 100644 --- a/doc/manual/src/language/builtin-constants.md +++ b/doc/manual/src/language/builtin-constants.md @@ -7,3 +7,14 @@ These constants are built into the Nix language evaluator: {{#include @generated@/language/builtin-constants.md}} + +## Things which might be mistaken for constants + +
+
__curPos
+
+ +This is not a constant but a [context-dependent keyword](@docroot@/language/constructs.md#keywords-__curPos) + +
+
diff --git a/doc/manual/src/language/constructs.md b/doc/manual/src/language/constructs.md index 2a527770a..67fd0126d 100644 --- a/doc/manual/src/language/constructs.md +++ b/doc/manual/src/language/constructs.md @@ -380,3 +380,70 @@ let a = 1; in let a = 2; in let a = 3; in let a = 4; in ... Comments can be single-line, started with a `#` character, or inline/multi-line, enclosed within `/* ... */`. + +## Context-dependent keywords + +
+
+ __curPos +
+
+ +A quasi-constant which will be replaced with an attribute set describing +the location where `__curPos` was used, with attributes `file`, `line`, +and `column`. For example, `import ./file.nix` will result in + +```nix +{ + column = 1; + file = "/path/to/some/file.nix"; + line = 1; +} +``` + +assuming `file.nix` contains nothing but `__curPos`. + +In context without a source file (such as `nix-repl`), it will always +be replaced with `null`: + +```nix-repl +nix-repl> __curPos +null +``` + +While it may vaguely look like a builtin, this is a very different beast +that is handled directly by the parser. It thus cannot be shadowed, +bound to a different name, and is also not available under +[`builtins`](@docroot@/language/builtin-constants.md#builtins-builtins). + +```nix-repl +nix-repl> let __curPos = "no"; in __curPos +null +``` + +Despite this `__curPos`, much like `or`, may still be used as an identifier, +it is only treated specially when it appears as an unqualified name: + +```nix-repl +nix-repl> { __curPos = 1; }.__curPos +1 +``` + +
+ +
+ or +
+
+ +`or` is used in [Attribute selection](@docroot@/language/operators.html#attribute-selection), +where it is a keyword. + +However, it is not a keyword in some other contexts, and can be used as +a binding name in attribute sets, let-bindings, non-initial function +application position, and as a label in attribute paths. + +Its use as anything other than a keyword is discouraged. + +
+