From 0f314f3c2594e80322c675b70a61dcfda11bf423 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 24 Aug 2020 14:49:30 +0200
Subject: [PATCH] Generate builtins section of the manual

---
 .gitignore                                    |  2 ++
 doc/manual/generate-builtins.jq               |  6 ++++++
 doc/manual/local.mk                           | 11 ++++++++--
 .../{builtins.md => builtins-prefix.md}       |  0
 src/nix/main.cc                               | 20 ++++++++++++++++++-
 5 files changed, 36 insertions(+), 3 deletions(-)
 create mode 100644 doc/manual/generate-builtins.jq
 rename doc/manual/src/expressions/{builtins.md => builtins-prefix.md} (100%)

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.md b/doc/manual/src/expressions/builtins-prefix.md
similarity index 100%
rename from doc/manual/src/expressions/builtins.md
rename to doc/manual/src/expressions/builtins-prefix.md
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) {