From 0f314f3c2594e80322c675b70a61dcfda11bf423 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Mon, 24 Aug 2020 14:49:30 +0200 Subject: Generate builtins section of the manual --- .gitignore | 2 + doc/manual/generate-builtins.jq | 6 +++ doc/manual/local.mk | 11 ++++- doc/manual/src/expressions/builtins-prefix.md | 68 +++++++++++++++++++++++++++ doc/manual/src/expressions/builtins.md | 68 --------------------------- src/nix/main.cc | 20 +++++++- 6 files changed, 104 insertions(+), 71 deletions(-) create mode 100644 doc/manual/generate-builtins.jq create mode 100644 doc/manual/src/expressions/builtins-prefix.md delete mode 100644 doc/manual/src/expressions/builtins.md diff --git a/.gitignore b/.gitignore index 44dbaa5d7..0ea27c8c8 100644 --- a/.gitignore +++ b/.gitignore @@ -27,8 +27,10 @@ perl/Makefile.config /doc/manual/*.8 /doc/manual/nix.json /doc/manual/conf-file.json +/doc/manual/builtins.json /doc/manual/src/command-ref/nix.md /doc/manual/src/command-ref/conf-file.md +/doc/manual/src/expressions/builtins.md # /scripts/ /scripts/nix-profile.sh diff --git a/doc/manual/generate-builtins.jq b/doc/manual/generate-builtins.jq new file mode 100644 index 000000000..c38799479 --- /dev/null +++ b/doc/manual/generate-builtins.jq @@ -0,0 +1,6 @@ +. | to_entries | sort_by(.key) | map( + " - `builtins." + .key + "` " + + (.value.args | map("*" + . + "*") | join(" ")) + + " \n\n" + + (.value.doc | split("\n") | map(" " + . + "\n") | join("")) + "\n\n" +) | join("") diff --git a/doc/manual/local.mk b/doc/manual/local.mk index dcc02d538..297a73414 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -32,15 +32,22 @@ $(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/generate-options.jq jq -r -f doc/manual/generate-options.jq $< >> $@ $(d)/nix.json: $(bindir)/nix - $(trace-gen) $(bindir)/nix dump-args > $@ + $(trace-gen) $(bindir)/nix __dump-args > $@ $(d)/conf-file.json: $(bindir)/nix $(trace-gen) env -i NIX_CONF_DIR=/dummy HOME=/dummy $(bindir)/nix show-config --json --experimental-features nix-command > $@ +$(d)/src/expressions/builtins.md: $(d)/builtins.json $(d)/generate-builtins.jq $(d)/src/expressions/builtins-prefix.md + cat doc/manual/src/expressions/builtins-prefix.md > $@ + jq -r -f doc/manual/generate-builtins.jq $< >> $@ + +$(d)/builtins.json: $(bindir)/nix + $(trace-gen) $(bindir)/nix __dump-builtins > $@ + # Generate the HTML manual. install: $(docdir)/manual/index.html -$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/custom.css +$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/custom.css $(d)/src/command-ref/nix.md $(d)/src/command-ref/conf-file.md $(d)/src/expressions/builtins.md $(trace-gen) mdbook build doc/manual -d $(docdir)/manual @cp doc/manual/highlight.pack.js $(docdir)/manual/highlight.js diff --git a/doc/manual/src/expressions/builtins-prefix.md b/doc/manual/src/expressions/builtins-prefix.md new file mode 100644 index 000000000..ae3bb150c --- /dev/null +++ b/doc/manual/src/expressions/builtins-prefix.md @@ -0,0 +1,68 @@ +# Built-in Functions + +This section lists the functions built into the Nix expression +evaluator. (The built-in function `derivation` is discussed above.) +Some built-ins, such as `derivation`, are always in scope of every Nix +expression; you can just access them right away. But to prevent +polluting the namespace too much, most built-ins are not in +scope. Instead, you can access them through the `builtins` built-in +value, which is a set that contains all built-in functions and values. +For instance, `derivation` is also available as `builtins.derivation`. + + - `derivation` *attrs*; `builtins.derivation` *attrs* + + `derivation` is described in [its own section](derivations.md). + + - `import` *path*; `builtins.import` *path* + + Load, parse and return the Nix expression in the file *path*. 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. + + > **Note** + > + > Unlike some languages, `import` is a regular function in Nix. + > Paths using the angle bracket syntax (e.g., `import` *\*) + > are [normal path values](language-values.md). + + 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 + + ```nix + rec { + x = 123; + y = import ./foo.nix; + } + ``` + + then the following `foo.nix` will give an error: + + ```nix + x + 456 + ``` + + 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: + + ```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.) diff --git a/doc/manual/src/expressions/builtins.md b/doc/manual/src/expressions/builtins.md deleted file mode 100644 index ae3bb150c..000000000 --- a/doc/manual/src/expressions/builtins.md +++ /dev/null @@ -1,68 +0,0 @@ -# Built-in Functions - -This section lists the functions built into the Nix expression -evaluator. (The built-in function `derivation` is discussed above.) -Some built-ins, such as `derivation`, are always in scope of every Nix -expression; you can just access them right away. But to prevent -polluting the namespace too much, most built-ins are not in -scope. Instead, you can access them through the `builtins` built-in -value, which is a set that contains all built-in functions and values. -For instance, `derivation` is also available as `builtins.derivation`. - - - `derivation` *attrs*; `builtins.derivation` *attrs* - - `derivation` is described in [its own section](derivations.md). - - - `import` *path*; `builtins.import` *path* - - Load, parse and return the Nix expression in the file *path*. 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. - - > **Note** - > - > Unlike some languages, `import` is a regular function in Nix. - > Paths using the angle bracket syntax (e.g., `import` *\*) - > are [normal path values](language-values.md). - - 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 - - ```nix - rec { - x = 123; - y = import ./foo.nix; - } - ``` - - then the following `foo.nix` will give an error: - - ```nix - x + 456 - ``` - - 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: - - ```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.) diff --git a/src/nix/main.cc b/src/nix/main.cc index 0c4fd46fd..210327927 100644 --- a/src/nix/main.cc +++ b/src/nix/main.cc @@ -179,11 +179,29 @@ void mainWrapped(int argc, char * * argv) NixArgs args; - if (argc == 2 && std::string(argv[1]) == "dump-args") { + if (argc == 2 && std::string(argv[1]) == "__dump-args") { std::cout << args.toJSON().dump() << "\n"; return; } + if (argc == 2 && std::string(argv[1]) == "__dump-builtins") { + EvalState state({}, openStore("ssh://foo.invalid/")); + auto res = nlohmann::json::object(); + auto builtins = state.baseEnv.values[0]->attrs; + for (auto & builtin : *builtins) { + auto b = nlohmann::json::object(); + if (builtin.value->type != tPrimOp) continue; + auto primOp = builtin.value->primOp; + if (!primOp->doc) continue; + b["arity"] = primOp->arity; + b["args"] = primOp->args; + b["doc"] = trim(stripIndentation(primOp->doc)); + res[(std::string) builtin.name] = std::move(b); + } + std::cout << res.dump() << "\n"; + return; + } + Finally printCompletions([&]() { if (completions) { -- cgit v1.2.3