docs: merge builtin-constants into builtins

[rhendric]

Motivation

As recommended in https://github.com/NixOS/nix/pull/10984/files#r1661385772.

Part of #10970.

Priorities and Process

Add 👍 to pull requests you find important.

The Nix maintainer team uses a GitHub project board to schedule and track reviews.

[Ericson2314]

Thank you! Looks great :)

[fricklerhandwerk]

This is on purpose, since most of them probably shouldn't be used unqualified and rather than making a manual list, this just provides the important ones. A complete list should be generated automatically and probably tucked away in a details tag.

[rhendric]

We can filter out anything that's deprecated or not yet ready for use, but I think it's important to have a complete description of the standard global scope in the language reference. Automated or manual is fine with me, but either way we should do the work of enumerating the set of builtins that ‘should’ be used unqualified, and this is not yet that set. (Is that set defined anywhere in code that I could reference? It's not obvious to me whether, say, map is in it.)

[Ericson2314]

The current implementation special cases the __ in a number of hacky ways. It would be nice to replace that with a boolean in the metadata structs, which we can leverage in the implementation (what goes in just builtins vs also at the top level) and also the documentation.

[rhendric]

I think that might be an orthogonal concern? The __ identifiers are only in the global scope, not on builtins. A boolean for that condition wouldn't express whether an identifier that is on builtins should be (documented as) available in the global scope also.

[Ericson2314]

My understanding is that if there is that __foo at the top level corresponds to builtins.foo, and bar at the top level corresponds to builtins.bar; in other words, that the top-level name is authoritative. But maybe there are more degrees of freedom!

[rhendric]

No, I think you're right about that. But my impression—@fricklerhandwerk correct me if I'm wrong—is that he would not want us to list all twenty-ish not-__ documented top-level identifiers because it's better practice to reference some of them from builtins. As a guess, isNull strikes me as a likely candidate for this; none of the other is* functions are available globally, so probably we should leave it in for backwards compatibility but not mention its availability outside of builtins in the language reference, sort of like the old let { ... } syntax.

But I don't know which other names should be in or out. builtins, false, null, true are obviously in. map, as I mentioned, is something I would lean toward including but I don't know how you all feel about it. break, removeAttrs, and toString are similar. Others I don't know what to think about; I would have erred on the side of including all of them (except for entirely undocumented functions like derivationStrict), but I'm happy to do whatever you all think is best.

[Ericson2314]

@rhendric Yeah so concretely I'm thinking something like this:

1. Replace internal __ hacks with a bool
2. Replace bool with a 3-way enum to disambiguate those we like at the top level vs don't like at the top level (or whatever other info we want)
3. Use the richer information when generating the docs

Step 1 is a nice thing we can get started on right away.