libexpr: generate builtins from data

Most builtins are now generated from data too, with two exceptions:
* Undocumented builtins, since supporting them would add complexity to the
  generator, the harms of the current implementation mostly don't apply, and
  the proper fix is to document them.
* `derivation` is somewhat magic (it is a function, but defined in the code as
  a constant), so the current treatment of having it separately documented is
  kept (for now, at least).
Since it is slightly easier to do and probably a good idea anyway, the builtin
function registrations generated this way are now processed directly in code
and don't go through global variables any more.
Unfortunately, a slight breaking change is introduced because the order of the
builtins' names in the symbol table changes. Hopefully, this will turn out to
not matter in practice.

Change-Id: I7b4379a93ae380b6524e41a916a21c5c6f70555e

doc/manual/meson.build

@@ -15,15 +15,6 @@ nix_eval_for_docs_common = nix_for_docs + [
 ]
 nix_eval_for_docs = nix_eval_for_docs_common + '--raw'
 
-language_json = custom_target(
-  command: [nix, '__dump-language'],
-  output : 'language.json',
-  capture : true,
-  env : nix_env_for_docs,
-  # FIXME: put the actual lib targets in here? meson have introspection challenge 2024 though.
-  build_always_stale : true,
-)
-
 nix3_cli_json = custom_target(
   command : [ nix, '__dump-cli' ],
   capture : true,
@@ -37,8 +28,6 @@ generate_manual_deps = files(
   'generate-deps.py',
 )
 
-# Generates builtins.md and builtin-constants.md.
-subdir('src/language')
 # Generates new-cli pages  and conf-file.md.
 subdir('src/command-ref')
 # Generates rl-next-generated.md.

doc/manual/src/contributing/hacking.md

@@ -400,9 +400,9 @@ The following properties are supported:
 Releases have a precomputed `rl-MAJOR.MINOR.md`, and no `rl-next.md`.
 Set `buildUnreleasedNotes = true;` in `flake.nix` to build the release notes on the fly.
 
-## Adding experimental or deprecated features, or global settings
+## Adding experimental or deprecated features, global settings, or builtins
 
-Experimental and deprecated features, and global settings are generally referenced both in the code and in the documentation.
+Experimental and deprecated features, global settings, and builtins are generally referenced both in the code and in the documentation.
 To prevent duplication or divergence, they are defined in data files, and a script generates the necessary glue.
 The data file format is similar to the release notes: it consists of a YAML metadata header, followed by the documentation in Markdown format.
 
@@ -443,3 +443,32 @@ Global settings support the following metadata properties:
 Settings are not collected in a single place in the source tree, so an appropriate place needs to be found for the setting to live.
 Look for related setting definition files under second-level subdirectories of `src` whose name includes `settings`.
 Then add the new file there, and don't forget to register it in the appropriate `meson.build` file.
+
+### Builtin functions
+
+The following metadata properties are supported for builtin functions:
+* `name` (required): the language-facing name (as a member of the `builtins` attribute set) of the function.
+* `implementation` (optional): a C++ expression specifying the implementation of the builtin.
+  It must be a function of signature `void(EvalState &, PosIdx, Value * *, Value &)`.
+  If not specified, defaults to `prim_${name}`.
+* `renameInGlobalScope` (optional): whether the definiton should be "hidden" in the global scope by prefixing its name with two underscores.
+  If not specified, defaults to `true`.
+* `args` (required): list containing the names of the arguments, as shown in the documentation.
+  All arguments must be listed here since the function arity is derived as the length of this list.
+* `experimental_feature` (optional): the user-facing name of the experimental feature which needs to be enabled for the bultin function to be available.
+  If not specified, no experimental feature is required.
+
+New builtin function definition files must be added to `src/libexpr/builtins` and registered in the `builtin_definitions` list in `src/libexpr/meson.build`.
+
+### Builtin constants
+The following metadata properties are supported for builtin constants:
+* `name` (required): the language-facing name (as a member of the `builtins` attribute set) of the constant.
+* `type` (required): the Nix language type of the constant; the C++ type is automatically derived.
+* `constructorArgs` (optional): list of strings containing C++ expressions passed as arguments to the appropriate `Value` constructor.
+  If the value computation is more complex, `implementation` can be used instead.
+* `implementation` (required if `constructorArgs` is not specified): string containing a C++ expressing computing the value of the constant.
+* `impure` (optional): whether the constant is considered impure.
+  Impure constants are not available when pure evaluation mode is activated.
+  Defaults to `false` when not specified.
+
+New builtin constant definition files must be added to `src/libexpr/builtin-constants` and registered in the `builtin_constant_definitions` list in `src/libexpr/meson.build`.

doc/manual/src/language/builtin-constants.md

@@ -4,7 +4,7 @@ These constants are built into the Nix language evaluator:
 
 <dl>
 
-{{#include @generated@/language/builtin-constants.md}}
+{{#include @generated@/../../../src/libexpr/builtin-constants.md}}
 
 </dl>
 

doc/manual/src/language/builtins.md

@@ -15,6 +15,6 @@ For convenience, some built-ins can be accessed directly:
   <dd><p><var>derivation</var> is described in
          <a href="derivations.md">its own section</a>.</p></dd>
 
-{{#include @generated@/language/builtins.md}}
+{{#include @generated@/../../../src/libexpr/builtins.md}}
 
 </dl>

doc/manual/src/language/meson.build

@@ -1,27 +0,0 @@
-builtins_md = custom_target(
-  command : nix_eval_for_docs + [
-    '--expr',
-    'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@)).builtins',
-  ],
-  capture : true,
-  input : [
-    '../../generate-builtins.nix',
-    language_json,
-  ],
-  output : 'builtins.md',
-  env : nix_env_for_docs,
-)
-
-builtin_constants_md = custom_target(
-  command : nix_eval_for_docs + [
-    '--expr',
-    'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@)).constants',
-  ],
-  capture : true,
-  input : [
-    '../../generate-builtin-constants.nix',
-    language_json,
-  ],
-  output : 'builtin-constants.md',
-  env : nix_env_for_docs,
-)

src/code-generation/build_builtin_constants.py

@@ -0,0 +1,93 @@
+from typing import List, NamedTuple
+
+from common import cxx_literal, generate_file, load_data
+
+KNOWN_KEYS = set([
+    'name',
+    'type',
+    'constructorArgs',
+    'implementation',
+    'impure',
+    'renameInGlobalScope',
+])
+
+class BuiltinConstant(NamedTuple):
+    name: str
+    type: str
+    implementation: str
+    impure: bool
+    rename_in_global_scope: bool
+    documentation: str
+
+    def parse(datum):
+        unknown_keys = set(datum.keys()) - KNOWN_KEYS
+        if unknown_keys:
+            raise Exception('unknown keys', unknown_keys)
+        return BuiltinConstant(
+            name = datum['name'],
+            type = datum['type'],
+            implementation = ('{' + ', '.join([f'NewValueAs::{datum["type"]}', *datum['constructorArgs']]) + '}') if 'constructorArgs' in datum else datum['implementation'],
+            impure = datum.get('impure', False),
+            rename_in_global_scope = datum.get('renameInGlobalScope', True),
+            documentation = datum.content,
+        )
+
+VALUE_TYPES = {
+    'attrs': 'nAttrs',
+    'boolean': 'nBool',
+    'integer': 'nInt',
+    'list': 'nList',
+    'null': 'nNull',
+    'string': 'nString',
+}
+
+HUMAN_TYPES = {
+    'attrs': 'set',
+    'boolean': 'Boolean',
+    'integer': 'integer',
+    'list': 'list',
+    'null': 'null',
+    'string': 'string',
+}
+
+def main():
+    import argparse
+
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--header', help='Path of the header to generate')
+    ap.add_argument('--docs', help='Path of the documentation file to generate')
+    ap.add_argument('defs', help='Builtin definition files', nargs='+')
+    args = ap.parse_args()
+
+    builtin_constants = load_data(args.defs, BuiltinConstant.parse)
+
+    generate_file(args.header, builtin_constants, lambda constant:
+        # `builtins` is magic and must come first
+        '' if constant.name == 'builtins' else constant.name,
+    lambda constant:
+        f'''{'if (!evalSettings.pureEval) ' if constant.impure else ''}{{
+    addConstant({cxx_literal(('__' if constant.rename_in_global_scope else '') + constant.name)}, {constant.implementation}, {{
+        .type = {VALUE_TYPES[constant.type]},
+        .doc = {cxx_literal(constant.documentation)},
+        .impureOnly = {cxx_literal(constant.impure)},
+    }});
+}}
+''')
+    generate_file(args.docs, builtin_constants, lambda constant: constant.name, lambda constant:
+        f'''<dt id="builtins-{constant.name}">
+  <a href="#builtins-{constant.name}"><code>{constant.name}</code></a> ({HUMAN_TYPES[constant.type]})
+</dt>
+<dd>
+
+{constant.documentation}
+
+''' + ('''> **Note**
+>
+> Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
+
+''' if constant.impure else '') + '''</dd>
+
+''')
+
+if __name__ == '__main__':
+    main()

src/code-generation/build_builtins.py

@@ -0,0 +1,82 @@
+from typing import List, NamedTuple, Optional
+
+from build_experimental_features import ExperimentalFeature
+from common import cxx_literal, generate_file, load_data
+
+KNOWN_KEYS = set([
+    'name',
+    'implementation',
+    'renameInGlobalScope',
+    'args',
+    'experimentalFeature',
+])
+
+class Builtin(NamedTuple):
+    name: str
+    implementation: str
+    rename_in_global_scope: bool
+    args: List[str]
+    experimental_feature: Optional[str]
+    documentation: str
+
+    def parse(datum):
+        unknown_keys = set(datum.keys()) - KNOWN_KEYS
+        if unknown_keys:
+            raise Exception('unknown keys', unknown_keys)
+        return Builtin(
+            name = datum['name'],
+            implementation = datum['implementation'] if 'implementation' in datum else f'prim_{datum["name"]}',
+            rename_in_global_scope = datum.get('renameInGlobalScope', True),
+            args = datum['args'],
+            experimental_feature = datum.get('experimentalFeature', None),
+            documentation = datum.content,
+        )
+
+def main():
+    import argparse
+
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--header', help='Path of the header to generate')
+    ap.add_argument('--docs', help='Path of the documentation file to generate')
+    ap.add_argument('--experimental-features', help='Directory containing the experimental feature definitions')
+    ap.add_argument('defs', help='Builtin definition files', nargs='+')
+    args = ap.parse_args()
+
+    builtins = load_data(args.defs, Builtin.parse)
+
+    experimental_feature_names = set([builtin.experimental_feature for (_, builtin) in builtins])
+    experimental_feature_names.discard(None)
+    experimental_feature_files = [f'{args.experimental_features}/{name}.md' for name in experimental_feature_names]
+    experimental_features = load_data(experimental_feature_files, ExperimentalFeature.parse)
+    experimental_features = dict(map(lambda path_and_feature:
+        (path_and_feature[1].name, f'Xp::{path_and_feature[1].internal_name}'), experimental_features))
+    experimental_features[None] = 'std::nullopt'
+
+    generate_file(args.header, builtins, lambda builtin: builtin.name, lambda builtin:
+        f'''{'' if builtin.experimental_feature is None else f'if (experimentalFeatureSettings.isEnabled({experimental_features[builtin.experimental_feature]})) '}{{
+    addPrimOp({{
+        .name = {cxx_literal(('__' if builtin.rename_in_global_scope else '') + builtin.name)},
+        .args = {cxx_literal(builtin.args)},
+        .arity = {len(builtin.args)},
+        .doc = {cxx_literal(builtin.documentation)},
+        .fun = {builtin.implementation},
+        .experimentalFeature = {experimental_features[builtin.experimental_feature]},
+    }});
+}}
+''')
+    generate_file(args.docs, builtins, lambda builtin: builtin.name, lambda builtin:
+        f'''<dt id="builtins-{builtin.name}">
+  <a href="#builtins-{builtin.name}"><code>{builtin.name} {' '.join([f'<var>{arg}</var>' for arg in builtin.args])}</code></a>
+</dt>
+<dd>
+
+{builtin.documentation}
+
+''' + (f'''This function is only available if the [{builtin.experimental_feature}](@docroot@/contributing/experimental-features.md#xp-feature-{builtin.experimental_feature}) experimental feature is enabled.
+
+''' if builtin.experimental_feature is not None else '') + '''</dd>
+
+''')
+
+if __name__ == '__main__':
+    main()

src/libexpr/builtin-constants/builtins.md

@@ -0,0 +1,14 @@
+---
+name: builtins
+type: attrs
+constructorArgs: [buildBindings(128).finish()]
+renameInGlobalScope: false
+---
+Contains all the [built-in functions](@docroot@/language/builtins.md) and values.
+
+Since built-in functions were added over time, [testing for attributes](./operators.md#has-attribute) in `builtins` can be used for graceful fallback on older Nix installations:
+
+```nix
+# if hasContext is not available, we assume `s` has a context
+if builtins ? hasContext then builtins.hasContext s else true
+```

src/libexpr/builtin-constants/currentSystem.md

@@ -0,0 +1,27 @@
+---
+name: currentSystem
+type: string
+constructorArgs: [evalSettings.getCurrentSystem()]
+impure: true
+---
+The value of the
+[`eval-system`](@docroot@/command-ref/conf-file.md#conf-eval-system)
+or else
+[`system`](@docroot@/command-ref/conf-file.md#conf-system)
+configuration option.
+
+It can be used to set the `system` attribute for [`builtins.derivation`](@docroot@/language/derivations.md) such that the resulting derivation can be built on the same system that evaluates the Nix expression:
+
+```nix
+ builtins.derivation {
+   # ...
+   system = builtins.currentSystem;
+}
+```
+
+It can be overridden in order to create derivations for different system than the current one:
+
+```console
+$ nix-instantiate --system "mips64-linux" --eval --expr 'builtins.currentSystem'
+"mips64-linux"
+```

src/libexpr/builtin-constants/currentTime.md

@@ -0,0 +1,23 @@
+---
+name: currentTime
+type: integer
+constructorArgs: ['NixInt{time(0)}']
+impure: true
+---
+Return the [Unix time](https://en.wikipedia.org/wiki/Unix_time) at first evaluation.
+Repeated references to that name will re-use the initially obtained value.
+
+Example:
+
+```console
+$ nix repl
+Welcome to Nix 2.15.1 Type :? for help.
+
+nix-repl> builtins.currentTime
+1683705525
+
+nix-repl> builtins.currentTime
+1683705525
+```
+
+The [store path](@docroot@/glossary.md#gloss-store-path) of a derivation depending on `currentTime` will differ for each evaluation, unless both evaluate `builtins.currentTime` in the same second.

src/libexpr/builtin-constants/false.md

@@ -0,0 +1,19 @@
+---
+name: 'false'
+type: boolean
+constructorArgs: ['false']
+renameInGlobalScope: false
+---
+Primitive value.
+
+It can be returned by
+[comparison operators](@docroot@/language/operators.md#Comparison)
+and used in
+[conditional expressions](@docroot@/language/constructs.md#Conditionals).
+
+The name `false` is not special, and can be shadowed:
+
+```nix-repl
+nix-repl> let false = 1; in false
+1
+```

src/libexpr/builtin-constants/langVersion.md

@@ -0,0 +1,15 @@
+---
+name: langVersion
+type: integer
+constructorArgs: ['NixInt{6}']
+---
+The legacy version of the Nix language. Always is `6` on Lix,
+matching Nix 2.18.
+
+Code in the Nix language should use other means of feature detection
+like detecting the presence of builtins, rather than trying to find
+the version of the Nix implementation, as there may be other Nix
+implementations with different feature combinations.
+
+If the feature you want to write compatibility code for cannot be
+detected by any means, please file a Lix bug.

src/libexpr/builtin-constants/nixPath.md

@@ -0,0 +1,21 @@
+---
+name: nixPath
+type: list
+implementation: getNixPath(*this, searchPath)
+---
+The search path used to resolve angle bracket path lookups.
+
+Angle bracket expressions can be
+[desugared](https://en.wikipedia.org/wiki/Syntactic_sugar)
+using this and
+[`builtins.findFile`](./builtins.html#builtins-findFile):
+
+```nix
+<nixpkgs>
+```
+
+is equivalent to:
+
+```nix
+builtins.findFile builtins.nixPath "nixpkgs"
+```

src/libexpr/builtin-constants/nixVersion.md

@@ -0,0 +1,14 @@
+---
+name: nixVersion
+type: string
+constructorArgs: ['"2.18.3-lix"']
+---
+Legacy version of Nix. Always returns "2.18.3-lix" on Lix.
+
+Code in the Nix language should use other means of feature detection
+like detecting the presence of builtins, rather than trying to find
+the version of the Nix implementation, as there may be other Nix
+implementations with different feature combinations.
+
+If the feature you want to write compatibility code for cannot be
+detected by any means, please file a Lix bug.

src/libexpr/builtin-constants/null.md

@@ -0,0 +1,14 @@
+---
+name: 'null'
+type: 'null'
+constructorArgs: []
+renameInGlobalScope: false
+---
+Primitive value.
+
+The name `null` is not special, and can be shadowed:
+
+```nix-repl
+nix-repl> let null = 1; in null
+1
+```

src/libexpr/builtin-constants/storeDir.md

@@ -0,0 +1,13 @@
+---
+name: storeDir
+type: string
+constructorArgs: [store->storeDir]
+---
+Logical file system location of the [Nix store](@docroot@/glossary.md#gloss-store) currently in use.
+
+This value is determined by the `store` parameter in [Store URLs](@docroot@/command-ref/new-cli/nix3-help-stores.md):
+
+```shell-session
+$ nix-instantiate --store 'dummy://?store=/blah' --eval --expr builtins.storeDir
+"/blah"
+```

src/libexpr/builtin-constants/true.md

@@ -0,0 +1,19 @@
+---
+name: 'true'
+type: boolean
+constructorArgs: ['true']
+renameInGlobalScope: false
+---
+Primitive value.
+
+It can be returned by
+[comparison operators](@docroot@/language/operators.md#Comparison)
+and used in
+[conditional expressions](@docroot@/language/constructs.md#Conditionals).
+
+The name `true` is not special, and can be shadowed:
+
+```nix-repl
+nix-repl> let true = 1; in true
+1
+```

src/libexpr/builtins/abort.md

@@ -0,0 +1,6 @@
+---
+name: abort
+args: [s]
+renameInGlobalScope: false
+---
+Abort Nix expression evaluation and print the error message *s*.

src/libexpr/builtins/add.md

@@ -0,0 +1,5 @@
+---
+name: add
+args: [e1, e2]
+---
+Return the sum of the numbers *e1* and *e2*.

src/libexpr/builtins/addDrvOutputDependencies.md

@@ -0,0 +1,12 @@
+---
+name: addDrvOutputDependencies
+args: [s]
+---
+Create a copy of the given string where a single constant string context element is turned into a "derivation deep" string context element.
+
+The store path that is the constant string context element should point to a valid derivation, and end in `.drv`.
+
+The original string context element must not be empty or have multiple elements, and it must not have any other type of element other than a constant or derivation deep element.
+The latter is supported so this function is idempotent.
+
+This is the opposite of [`builtins.unsafeDiscardOutputDependency`](#builtins-unsafeDiscardOutputDependency).

src/libexpr/builtins/all.md

@@ -0,0 +1,6 @@
+---
+name: all
+args: [pred, list]
+---
+Return `true` if the function *pred* returns `true` for all elements
+of *list*, and `false` otherwise.

src/libexpr/builtins/any.md

@@ -0,0 +1,6 @@
+---
+name: any
+args: [pred, list]
+---
+Return `true` if the function *pred* returns `true` for at least one
+element of *list*, and `false` otherwise.

src/libexpr/builtins/attrNames.md

@@ -0,0 +1,7 @@
+---
+name: attrNames
+args: [set]
+---
+Return the names of the attributes in the set *set* in an
+alphabetically sorted list. For instance, `builtins.attrNames { y
+= 1; x = "foo"; }` evaluates to `[ "x" "y" ]`.

src/libexpr/builtins/attrValues.md

@@ -0,0 +1,6 @@
+---
+name: attrValues
+args: [set]
+---
+Return the values of the attributes in the set *set* in the order
+corresponding to the sorted attribute names.

src/libexpr/builtins/baseNameOf.md

@@ -0,0 +1,8 @@
+---
+name: baseNameOf
+args: [s]
+renameInGlobalScope: false
+---
+Return the *base name* of the string *s*, that is, everything
+following the final slash in the string. This is similar to the GNU
+`basename` command.

src/libexpr/builtins/bitAnd.md

@@ -0,0 +1,5 @@
+---
+name: bitAnd
+args: [e1, e2]
+---
+Return the bitwise AND of the integers *e1* and *e2*.

src/libexpr/builtins/bitOr.md

@@ -0,0 +1,5 @@
+---
+name: bitOr
+args: [e1, e2]
+---
+Return the bitwise OR of the integers *e1* and *e2*.

src/libexpr/builtins/bitXor.md

@@ -0,0 +1,5 @@
+---
+name: bitXor
+args: [e1, e2]
+---
+Return the bitwise XOR of the integers *e1* and *e2*.

src/libexpr/builtins/break.md

@@ -0,0 +1,7 @@
+---
+name: break
+args: [v]
+renameInGlobalScope: false
+---
+In debug mode (enabled using `--debugger`), pause Nix expression evaluation and enter the REPL.
+Otherwise, return the argument `v`.

src/libexpr/builtins/catAttrs.md

@@ -0,0 +1,13 @@
+---
+name: catAttrs
+args: [attr, list]
+---
+Collect each attribute named *attr* from a list of attribute
+sets.  Attrsets that don't contain the named attribute are
+ignored. For example,
+
+```nix
+builtins.catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
+```
+
+evaluates to `[1 2]`.

src/libexpr/builtins/ceil.md

@@ -0,0 +1,9 @@
+---
+name: ceil
+args: [double]
+---
+Converts an IEEE-754 double-precision floating-point number (*double*) to
+the next higher integer.
+
+If the datatype is neither an integer nor a "float", an evaluation error will be
+thrown.

src/libexpr/builtins/compareVersions.md

@@ -0,0 +1,9 @@
+---
+name: compareVersions
+args: [s1, s2]
+---
+Compare two strings representing versions and return `-1` if
+version *s1* is older than version *s2*, `0` if they are the same,
+and `1` if *s1* is newer than *s2*. The version comparison
+algorithm is the same as the one used by [`nix-env
+-u`](../command-ref/nix-env.md#operation---upgrade).

src/libexpr/builtins/concatLists.md

@@ -0,0 +1,5 @@
+---
+name: concatLists
+args: [lists]
+---
+Concatenate a list of lists into a single list.

src/libexpr/builtins/concatMap.md

@@ -0,0 +1,6 @@
+---
+name: concatMap
+args: [f, list]
+---
+This function is equivalent to `builtins.concatLists (map f list)`
+but is more efficient.

src/libexpr/builtins/concatStringsSep.md

@@ -0,0 +1,7 @@
+---
+name: concatStringsSep
+args: [separator, list]
+---
+Concatenate a list of strings with a separator between each
+element, e.g. `concatStringsSep "/" ["usr" "local" "bin"] ==
+"usr/local/bin"`.

src/libexpr/builtins/deepSeq.md

@@ -0,0 +1,7 @@
+---
+name: deepSeq
+args: [e1, e2]
+---
+This is like `seq e1 e2`, except that *e1* is evaluated *deeply*:
+if it’s a list or set, its elements or attributes are also
+evaluated recursively.

src/libexpr/builtins/dirOf.md

@@ -0,0 +1,8 @@
+---
+name: dirOf
+args: [s]
+renameInGlobalScope: false
+---
+Return the directory part of the string *s*, that is, everything
+before the final slash in the string. This is similar to the GNU
+`dirname` command.

src/libexpr/builtins/div.md

@@ -0,0 +1,5 @@
+---
+name: div
+args: [e1, e2]
+---
+Return the quotient of the numbers *e1* and *e2*.

src/libexpr/builtins/elem.md

@@ -0,0 +1,6 @@
+---
+name: elem
+args: [x, xs]
+---
+Return `true` if a value equal to *x* occurs in the list *xs*, and
+`false` otherwise.

src/libexpr/builtins/elemAt.md

@@ -0,0 +1,6 @@
+---
+name: elemAt
+args: [xs, n]
+---
+Return element *n* from the list *xs*. Elements are counted starting
+from 0. A fatal error occurs if the index is out of bounds.

src/libexpr/builtins/fetchClosure.md

@@ -0,0 +1,72 @@
+---
+name: fetchClosure
+args: [args]
+experimentalFeature: fetch-closure
+---
+Fetch a store path [closure](@docroot@/glossary.md#gloss-closure) from a binary cache, and return the store path as a string with context.
+
+This function can be invoked in three ways, that we will discuss in order of preference.
+
+**Fetch a content-addressed store path**
+
+Example:
+
+```nix
+builtins.fetchClosure {
+  fromStore = "https://cache.nixos.org";
+  fromPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
+}
+```
+
+This is the simplest invocation, and it does not require the user of the expression to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.
+
+If your store path is [input addressed](@docroot@/glossary.md#gloss-input-addressed-store-object) instead of content addressed, consider the other two invocations.
+
+**Fetch any store path and rewrite it to a fully content-addressed store path**
+
+Example:
+
+```nix
+builtins.fetchClosure {
+  fromStore = "https://cache.nixos.org";
+  fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
+  toPath = /nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1;
+}
+```
+
+This example fetches `/nix/store/r2jd...` from the specified binary cache,
+and rewrites it into the content-addressed store path
+`/nix/store/ldbh...`.
+
+Like the previous example, no extra configuration or privileges are required.
+
+To find out the correct value for `toPath` given a `fromPath`,
+use [`nix store make-content-addressed`](@docroot@/command-ref/new-cli/nix3-store-make-content-addressed.md):
+
+```console
+# nix store make-content-addressed --from https://cache.nixos.org /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1
+rewrote '/nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1' to '/nix/store/ldbhlwhh39wha58rm61bkiiwm6j7211j-git-2.33.1'
+```
+
+Alternatively, set `toPath = ""` and find the correct `toPath` in the error message.
+
+**Fetch an input-addressed store path as is**
+
+Example:
+
+```nix
+builtins.fetchClosure {
+  fromStore = "https://cache.nixos.org";
+  fromPath = /nix/store/r2jd6ygnmirm2g803mksqqjm4y39yi6i-git-2.33.1;
+  inputAddressed = true;
+}
+```
+
+It is possible to fetch an [input-addressed store path](@docroot@/glossary.md#gloss-input-addressed-store-object) and return it as is.
+However, this is the least preferred way of invoking `fetchClosure`, because it requires that the input-addressed paths are trusted by the Lix configuration.
+
+**`builtins.storePath`**
+
+`fetchClosure` is similar to [`builtins.storePath`](#builtins-storePath) in that it allows you to use a previously built store path in a Nix expression.
+However, `fetchClosure` is more reproducible because it specifies a binary cache from which the path can be fetched.
+Also, using content-addressed store paths does not require users to configure [`trusted-public-keys`](@docroot@/command-ref/conf-file.md#conf-trusted-public-keys) to ensure their authenticity.

src/libexpr/builtins/fetchGit.md

@@ -0,0 +1,138 @@
+---
+name: fetchGit
+args: [args]
+renameInGlobalScope: false
+---
+Fetch a path from git. *args* can be a URL, in which case the HEAD
+of the repo at that URL is fetched. Otherwise, it can be an
+attribute with the following attributes (all except `url` optional):
+
+- `url`
+
+  The URL of the repo.
+
+- `name` (default: *basename of the URL*)
+
+  The name of the directory the repo should be exported to in the store.
+
+- `rev` (default: *the tip of `ref`*)
+
+  The [Git revision] to fetch.
+  This is typically a commit hash.
+
+  [Git revision]: https://git-scm.com/docs/git-rev-parse#_specifying_revisions
+
+- `ref` (default: `HEAD`)
+
+  The [Git reference] under which to look for the requested revision.
+  This is often a branch or tag name.
+
+  [Git reference]: https://git-scm.com/book/en/v2/Git-Internals-Git-References
+
+  By default, the `ref` value is prefixed with `refs/heads/`.
+  As of 2.3.0, Nix will not prefix `refs/heads/` if `ref` starts with `refs/` or
+  if `ref` looks like a commit hash for backwards compatibility with CppNix 2.3.
+
+- `submodules` (default: `false`)
+
+  A Boolean parameter that specifies whether submodules should be checked out.
+
+- `shallow` (default: `false`)
+
+  A Boolean parameter that specifies whether fetching from a shallow remote repository is allowed.
+  This still performs a full clone of what is available on the remote.
+
+- `allRefs`
+
+  Whether to fetch all references of the repository.
+  With this argument being true, it's possible to load a `rev` from *any* `ref`
+  (by default only `rev`s from the specified `ref` are supported).
+
+Here are some examples of how to use `fetchGit`.
+
+  - To fetch a private repository over SSH:
+
+    ```nix
+    builtins.fetchGit {
+      url = "git@github.com:my-secret/repository.git";
+      ref = "master";
+      rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
+    }
+    ```
+
+  - To fetch an arbitrary reference:
+
+    ```nix
+    builtins.fetchGit {
+      url = "https://github.com/NixOS/nix.git";
+      ref = "refs/heads/0.5-release";
+    }
+    ```
+
+  - If the revision you're looking for is in the default branch of
+    the git repository you don't strictly need to specify the branch
+    name in the `ref` attribute.
+
+    However, if the revision you're looking for is in a future
+    branch for the non-default branch you will need to specify the
+    the `ref` attribute as well.
+
+    ```nix
+    builtins.fetchGit {
+      url = "https://github.com/nixos/nix.git";
+      rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
+      ref = "1.11-maintenance";
+    }
+    ```
+
+    > **Note**
+    >
+    > It is nice to always specify the branch which a revision
+    > belongs to. Without the branch being specified, the fetcher
+    > might fail if the default branch changes. Additionally, it can
+    > be confusing to try a commit from a non-default branch and see
+    > the fetch fail. If the branch is specified the fault is much
+    > more obvious.
+
+  - If the revision you're looking for is in the default branch of
+    the git repository you may omit the `ref` attribute.
+
+    ```nix
+    builtins.fetchGit {
+      url = "https://github.com/nixos/nix.git";
+      rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
+    }
+    ```
+
+  - To fetch a specific tag:
+
+    ```nix
+    builtins.fetchGit {
+      url = "https://github.com/nixos/nix.git";
+      ref = "refs/tags/1.9";
+    }
+    ```
+
+  - To fetch the latest version of a remote branch:
+
+    ```nix
+    builtins.fetchGit {
+      url = "ssh://git@github.com/nixos/nix.git";
+      ref = "master";
+    }
+    ```
+
+    Nix will refetch the branch according to the [`tarball-ttl`](@docroot@/command-ref/conf-file.md#conf-tarball-ttl) setting.
+
+    This behavior is disabled in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
+
+  - To fetch the content of a checked-out work directory:
+
+    ```nix
+    builtins.fetchGit ./work-dir
+    ```
+
+If the URL points to a local directory, and no `ref` or `rev` is
+given, `fetchGit` will use the current content of the checked-out
+files, even if they are not committed or added to Git's index. It will
+only consider files added to the Git repository, as listed by `git ls-files`.

src/libexpr/builtins/fetchTarball.md

@@ -0,0 +1,42 @@
+---
+name: fetchTarball
+args: [args]
+renameInGlobalScope: false
+---
+Download the specified URL, unpack it and return the path of the
+unpacked tree. The file must be a tape archive (`.tar`) compressed
+with `gzip`, `bzip2` or `xz`. The top-level path component of the
+files in the tarball is removed, so it is best if the tarball
+contains a single directory at top level. The typical use of the
+function is to obtain external Nix expression dependencies, such as
+a particular version of Nixpkgs, e.g.
+
+```nix
+with import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz") {};
+
+stdenv.mkDerivation { … }
+```
+
+The fetched tarball is cached for a certain amount of time (1
+hour by default) in `~/.cache/nix/tarballs/`. You can change the
+cache timeout either on the command line with `--tarball-ttl`
+*number-of-seconds* or in the Nix configuration file by adding
+the line `tarball-ttl = ` *number-of-seconds*.
+
+Note that when obtaining the hash with `nix-prefetch-url` the
+option `--unpack` is required.
+
+This function can also verify the contents against a hash. In that
+case, the function takes a set instead of a URL. The set requires
+the attribute `url` and the attribute `sha256`, e.g.
+
+```nix
+with import (fetchTarball {
+  url = "https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz";
+  sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2";
+}) {};
+
+stdenv.mkDerivation { … }
+```
+
+Not available in [restricted evaluation mode](@docroot@/command-ref/conf-file.md#conf-restrict-eval).

src/libexpr/builtins/fetchurl.md

@@ -0,0 +1,7 @@
+---
+name: fetchurl
+args: [url]
+---
+Download the specified URL and return the path of the downloaded file.
+
+Not available in [restricted evaluation mode](@docroot@/command-ref/conf-file.md#conf-restrict-eval).

src/libexpr/builtins/filter.md

@@ -0,0 +1,6 @@
+---
+name: filter
+args: [f, list]
+---
+Return a list consisting of the elements of *list* for which the
+function *f* returns `true`.

src/libexpr/builtins/filterSource.md

@@ -0,0 +1,51 @@
+---
+name: filterSource
+args: [e1, e2]
+---
+> **Warning**
+>
+> `filterSource` should not be used to filter store paths. Since
+> `filterSource` uses the name of the input directory while naming
+> the output directory, doing so will produce a directory name in
+> the form of `<hash2>-<hash>-<name>`, where `<hash>-<name>` is
+> the name of the input directory. Since `<hash>` depends on the
+> unfiltered directory, the name of the output directory will
+> indirectly depend on files that are filtered out by the
+> function. This will trigger a rebuild even when a filtered out
+> file is changed. Use `builtins.path` instead, which allows
+> specifying the name of the output directory.
+
+This function allows you to copy sources into the Nix store while
+filtering certain files. For instance, suppose that you want to use
+the directory `source-dir` as an input to a Nix expression, e.g.
+
+```nix
+stdenv.mkDerivation {
+  ...
+  src = ./source-dir;
+}
+```
+
+However, if `source-dir` is a Subversion working copy, then all
+those annoying `.svn` subdirectories will also be copied to the
+store. Worse, the contents of those directories may change a lot,
+causing lots of spurious rebuilds. With `filterSource` you can
+filter out the `.svn` directories:
+
+```nix
+src = builtins.filterSource
+  (path: type: type != "directory" || baseNameOf path != ".svn")
+  ./source-dir;
+```
+
+Thus, the first argument *e1* must be a predicate function that is
+called for each regular file, directory or symlink in the source
+tree *e2*. If the function returns `true`, the file is copied to the
+Nix store, otherwise it is omitted. The function is called with two
+arguments. The first is the full path of the file. The second is a
+string that identifies the type of the file, which is either
+`"regular"`, `"directory"`, `"symlink"` or `"unknown"` (for other
+kinds of files such as device nodes or fifos — but note that those
+cannot be copied to the Nix store, so if the predicate returns
+`true` for them, the copy will fail). If you exclude a directory,
+the entire corresponding subtree of *e2* will be excluded.

src/libexpr/builtins/findFile.md

@@ -0,0 +1,45 @@
+---
+name: findFile
+args: ['search path', 'lookup path']
+---
+Look up the given path with the given search path.
+
+A search path is represented list of [attribute sets](./values.md#attribute-set) with two attributes, `prefix`, and `path`.
+`prefix` is a relative path.
+`path` denotes a file system location; the exact syntax depends on the command line interface.
+
+Examples of search path attribute sets:
+
+- ```
+  {
+    prefix = "nixos-config";
+    path = "/etc/nixos/configuration.nix";
+  }
+  ```
+
+- ```
+  {
+    prefix = "";
+    path = "/nix/var/nix/profiles/per-user/root/channels";
+  }
+  ```
+
+The lookup algorithm checks each entry until a match is found, returning a [path value](@docroot@/language/values.html#type-path) of the match.
+
+This is the process for each entry:
+If the lookup path matches `prefix`, then the remainder of the lookup path (the "suffix") is searched for within the directory denoted by `patch`.
+Note that the `path` may need to be downloaded at this point to look inside.
+If the suffix is found inside that directory, then the entry is a match;
+the combined absolute path of the directory (now downloaded if need be) and the suffix is returned.
+
+The syntax
+
+```nix
+<nixpkgs>
+```
+
+is equivalent to:
+
+```nix
+builtins.findFile builtins.nixPath "nixpkgs"
+```

src/libexpr/builtins/flakeRefToString.md

@@ -0,0 +1,21 @@
+---
+name: flakeRefToString
+implementation: flake::prim_flakeRefToString
+args: [attrs]
+experimentalFeature: flakes
+---
+Convert a flake reference from attribute set format to URL format.
+
+For example:
+
+```nix
+builtins.flakeRefToString {
+  dir = "lib"; owner = "NixOS"; ref = "23.05"; repo = "nixpkgs"; type = "github";
+}
+```
+
+evaluates to
+
+```nix
+"github:NixOS/nixpkgs/23.05?dir=lib"
+```

src/libexpr/builtins/floor.md

@@ -0,0 +1,9 @@
+---
+name: floor
+args: [double]
+---
+Converts an IEEE-754 double-precision floating-point number (*double*) to
+the next lower integer.
+
+If the datatype is neither an integer nor a "float", an evaluation error will be
+thrown.

src/libexpr/builtins/foldlStrict.md

@@ -0,0 +1,10 @@
+---
+name: foldl'
+implementation: prim_foldlStrict
+args: [op, nul, list]
+---
+Reduce a list by applying a binary operator, from left to right,
+e.g. `foldl' op nul [x0 x1 x2 ...] = op (op (op nul x0) x1) x2)
+...`. For example, `foldl' (x: y: x + y) 0 [1 2 3]` evaluates to 6.
+The return value of each application of `op` is evaluated immediately,
+even for intermediate values.

src/libexpr/builtins/fromJSON.md

@@ -0,0 +1,11 @@
+---
+name: fromJSON
+args: [e]
+---
+Convert a JSON string to a Nix value. For example,
+
+```nix
+builtins.fromJSON ''{"x": [1, 2, 3], "y": null}''
+```
+
+returns the value `{ x = [ 1 2 3 ]; y = null; }`.

src/libexpr/builtins/fromTOML.md

@@ -0,0 +1,17 @@
+---
+name: fromTOML
+args: [e]
+renameInGlobalScope: false
+---
+Convert a TOML string to a Nix value. For example,
+
+```nix
+builtins.fromTOML ''
+  x=1
+  s="a"
+  [table]
+  y=2
+''
+```
+
+returns the value `{ s = "a"; table = { y = 2; }; x = 1; }`.

src/libexpr/builtins/functionArgs.md

@@ -0,0 +1,13 @@
+---
+name: functionArgs
+args: [f]
+---
+Return a set containing the names of the formal arguments expected
+by the function *f*. The value of each attribute is a Boolean
+denoting whether the corresponding argument has a default value. For
+instance, `functionArgs ({ x, y ? 123}: ...) = { x = false; y =
+true; }`.
+
+"Formal argument" here refers to the attributes pattern-matched by
+the function. Plain lambdas are not included, e.g. `functionArgs (x:
+...) = { }`.

src/libexpr/builtins/genList.md

@@ -0,0 +1,12 @@
+---
+name: genList
+args: [generator, length]
+---
+Generate list of size *length*, with each element *i* equal to the
+value returned by *generator* `i`. For example,
+
+```nix
+builtins.genList (x: x * x) 5
+```
+
+returns the list `[ 0 1 4 9 16 ]`.

src/libexpr/builtins/genericClosure.md

@@ -0,0 +1,28 @@
+---
+name: genericClosure
+args: [attrset]
+---
+Take an *attrset* with values named `startSet` and `operator` in order to
+return a *list of attrsets* by starting with the `startSet` and recursively
+applying the `operator` function to each `item`. The *attrsets* in the
+`startSet` and the *attrsets* produced by `operator` must contain a value
+named `key` which is comparable. The result is produced by calling `operator`
+for each `item` with a value for `key` that has not been called yet including
+newly produced `item`s. The function terminates when no new `item`s are
+produced. The resulting *list of attrsets* contains only *attrsets* with a
+unique key. For example,
+
+```
+builtins.genericClosure {
+  startSet = [ {key = 5;} ];
+  operator = item: [{
+    key = if (item.key / 2 ) * 2 == item.key
+         then item.key / 2
+         else 3 * item.key + 1;
+  }];
+}
+```
+evaluates to
+```
+[ { key = 5; } { key = 16; } { key = 8; } { key = 4; } { key = 2; } { key = 1; } ]
+```

src/libexpr/builtins/getAttr.md

@@ -0,0 +1,8 @@
+---
+name: getAttr
+args: [s, set]
+---
+`getAttr` returns the attribute named *s* from *set*. Evaluation
+aborts if the attribute doesn’t exist. This is a dynamic version of
+the `.` operator, since *s* is an expression rather than an
+identifier.

src/libexpr/builtins/getContext.md

@@ -0,0 +1,21 @@
+---
+name: getContext
+args: [s]
+---
+Return the string context of *s*.
+
+The string context tracks references to derivations within a string.
+It is represented as an attribute set of [store derivation](@docroot@/glossary.md#gloss-store-derivation) paths mapping to output names.
+
+Using [string interpolation](@docroot@/language/string-interpolation.md) on a derivation will add that derivation to the string context.
+For example,
+
+```nix
+builtins.getContext "${derivation { name = "a"; builder = "b"; system = "c"; }}"
+```
+
+evaluates to
+
+```
+{ "/nix/store/arhvjaf6zmlyn8vh8fgn55rpwnxq0n7l-a.drv" = { outputs = [ "out" ]; }; }
+```

src/libexpr/builtins/getEnv.md

@@ -0,0 +1,14 @@
+---
+name: getEnv
+args: [s]
+---
+`getEnv` returns the value of the environment variable *s*, or an
+empty string if the variable doesn't exist. This function should be
+used with care, as it can introduce all sorts of nasty environment
+dependencies in your Nix expression.
+
+`getEnv` is used in nixpkgs for evil impurities such as locating the file
+`~/.config/nixpkgs/config.nix` which contains user-local settings for nixpkgs.
+(That is, it does a `getEnv "HOME"` to locate the user's home directory.)
+
+When in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval), this function always returns an empty string.

src/libexpr/builtins/getFlake.md

@@ -0,0 +1,19 @@
+---
+name: getFlake
+implementation: flake::prim_getFlake
+args: [args]
+experimentalFeature: flakes
+---
+Fetch a flake from a flake reference, and return its output attributes and some metadata. For example:
+
+```nix
+(builtins.getFlake "nix/55bc52401966fbffa525c574c14f67b00bc4fb3a").packages.x86_64-linux.nix
+```
+
+Unless impure evaluation is allowed (`--impure`), the flake reference
+must be "locked", e.g. contain a Git revision or content hash. An
+example of an unlocked usage is:
+
+```nix
+(builtins.getFlake "github:edolstra/dwarffs").rev
+```

src/libexpr/builtins/groupBy.md

@@ -0,0 +1,20 @@
+---
+name: groupBy
+args: [f, list]
+---
+Groups elements of *list* together by the string returned from the
+function *f* called on each element. It returns an attribute set
+where each attribute value contains the elements of *list* that are
+mapped to the same corresponding attribute name returned by *f*.
+
+For example,
+
+```nix
+builtins.groupBy (builtins.substring 0 1) ["foo" "bar" "baz"]
+```
+
+evaluates to
+
+```nix
+{ b = [ "bar" "baz" ]; f = [ "foo" ]; }
+```

src/libexpr/builtins/hasAttr.md

@@ -0,0 +1,7 @@
+---
+name: hasAttr
+args: [s, set]
+---
+`hasAttr` returns `true` if *set* has an attribute named *s*, and
+`false` otherwise. This is a dynamic version of the `?` operator,
+since *s* is an expression rather than an identifier.

src/libexpr/builtins/hasContext.md

@@ -0,0 +1,20 @@
+---
+name: hasContext
+args: [s]
+---
+Return `true` if string *s* has a non-empty context.
+The context can be obtained with
+[`getContext`](#builtins-getContext).
+
+> **Example**
+>
+> Many operations require a string context to be empty because they are intended only to work with "regular" strings, and also to help users avoid unintentionally losing track of string context elements.
+> `builtins.hasContext` can help create better domain-specific errors in those case.
+>
+> ```nix
+> name: meta:
+>
+> if builtins.hasContext name
+> then throw "package name cannot contain string context"
+> else { ${name} = meta; }
+> ```

src/libexpr/builtins/hashFile.md

@@ -0,0 +1,7 @@
+---
+name: hashFile
+args: [type, p]
+---
+Return a base-16 representation of the cryptographic hash of the
+file at path *p*. The hash algorithm specified by *type* must be one
+of `"md5"`, `"sha1"`, `"sha256"` or `"sha512"`.

src/libexpr/builtins/hashString.md

@@ -0,0 +1,7 @@
+---
+name: hashString
+args: [type, s]
+---
+Return a base-16 representation of the cryptographic hash of string
+*s*. The hash algorithm specified by *type* must be one of `"md5"`,
+`"sha1"`, `"sha256"` or `"sha512"`.

src/libexpr/builtins/head.md

@@ -0,0 +1,7 @@
+---
+name: head
+args: [list]
+---
+Return the first element of a list; abort evaluation if the argument
+isn’t a list or is an empty list. You can test whether a list is
+empty by comparing it with `[]`.

src/libexpr/builtins/import.md

@@ -0,0 +1,63 @@
+---
+name: import
+args: [path]
+renameInGlobalScope: false
+---
+Load, parse and return the Nix expression in the file *path*.
+
+The value *path* can be a path, a string, or an attribute set with an
+`__toString` attribute or a `outPath` attribute (as derivations or flake
+inputs typically have).
+
+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` *\<foo\>*)
+> are normal [path values](@docroot@/language/values.md#type-path).
+
+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.)

src/libexpr/builtins/intersectAttrs.md

@@ -0,0 +1,8 @@
+---
+name: intersectAttrs
+args: [e1, e2]
+---
+Return a set consisting of the attributes in the set *e2* which have the
+same name as some attribute in *e1*.
+
+Performs in O(*n* log *m*) where *n* is the size of the smaller set and *m* the larger set's size.

src/libexpr/builtins/isAttrs.md

@@ -0,0 +1,5 @@
+---
+name: isAttrs
+args: [e]
+---
+Return `true` if *e* evaluates to a set, and `false` otherwise.

src/libexpr/builtins/isBool.md

@@ -0,0 +1,5 @@
+---
+name: isBool
+args: [e]
+---
+Return `true` if *e* evaluates to a bool, and `false` otherwise.

src/libexpr/builtins/isFloat.md

@@ -0,0 +1,5 @@
+---
+name: isFloat
+args: [e]
+---
+Return `true` if *e* evaluates to a float, and `false` otherwise.

src/libexpr/builtins/isFunction.md

@@ -0,0 +1,5 @@
+---
+name: isFunction
+args: [e]
+---
+Return `true` if *e* evaluates to a function, and `false` otherwise.

src/libexpr/builtins/isInt.md

@@ -0,0 +1,5 @@
+---
+name: isInt
+args: [e]
+---
+Return `true` if *e* evaluates to an integer, and `false` otherwise.

src/libexpr/builtins/isList.md

@@ -0,0 +1,5 @@
+---
+name: isList
+args: [e]
+---
+Return `true` if *e* evaluates to a list, and `false` otherwise.

src/libexpr/builtins/isNull.md

@@ -0,0 +1,8 @@
+---
+name: isNull
+args: [e]
+renameInGlobalScope: false
+---
+Return `true` if *e* evaluates to `null`, and `false` otherwise.
+
+This is equivalent to `e == null`.

src/libexpr/builtins/isPath.md

@@ -0,0 +1,5 @@
+---
+name: isPath
+args: [e]
+---
+Return `true` if *e* evaluates to a path, and `false` otherwise.

src/libexpr/builtins/isString.md

@@ -0,0 +1,5 @@
+---
+name: isString
+args: [e]
+---
+Return `true` if *e* evaluates to a string, and `false` otherwise.

src/libexpr/builtins/length.md

@@ -0,0 +1,5 @@
+---
+name: length
+args: [e]
+---
+Return the length of the list *e*.

src/libexpr/builtins/lessThan.md

@@ -0,0 +1,7 @@
+---
+name: lessThan
+args: [e1, e2]
+---
+Return `true` if the number *e1* is less than the number *e2*, and
+`false` otherwise. Evaluation aborts if either *e1* or *e2* does not
+evaluate to a number.

src/libexpr/builtins/listToAttrs.md

@@ -0,0 +1,27 @@
+---
+name: listToAttrs
+args: [e]
+---
+Construct a set from a list specifying the names and values of each
+attribute. Each element of the list should be a set consisting of a
+string-valued attribute `name` specifying the name of the attribute,
+and an attribute `value` specifying its value.
+
+In case of duplicate occurrences of the same name, the first
+takes precedence.
+
+Example:
+
+```nix
+builtins.listToAttrs
+  [ { name = "foo"; value = 123; }
+    { name = "bar"; value = 456; }
+    { name = "bar"; value = 420; }
+  ]
+```
+
+evaluates to
+
+```nix
+{ foo = 123; bar = 456; }
+```

src/libexpr/builtins/map.md

@@ -0,0 +1,13 @@
+---
+name: map
+args: [f, list]
+renameInGlobalScope: false
+---
+Apply the function *f* to each element in the list *list*. For
+example,
+
+```nix
+map (x: "foo" + x) [ "bar" "bla" "abc" ]
+```
+
+evaluates to `[ "foobar" "foobla" "fooabc" ]`.

src/libexpr/builtins/mapAttrs.md

@@ -0,0 +1,11 @@
+---
+name: mapAttrs
+args: [f, attrset]
+---
+Apply function *f* to every element of *attrset*. For example,
+
+```nix
+builtins.mapAttrs (name: value: value * 10) { a = 1; b = 2; }
+```
+
+evaluates to `{ a = 10; b = 20; }`.

src/libexpr/builtins/match.md

@@ -0,0 +1,32 @@
+---
+name: match
+args: [regex, str]
+---
+Returns a list if the [extended POSIX regular
+expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)
+*regex* matches *str* precisely, otherwise returns `null`. Each item
+in the list is a regex group.
+
+```nix
+builtins.match "ab" "abc"
+```
+
+Evaluates to `null`.
+
+```nix
+builtins.match "abc" "abc"
+```
+
+Evaluates to `[ ]`.
+
+```nix
+builtins.match "a(b)(c)" "abc"
+```
+
+Evaluates to `[ "b" "c" ]`.
+
+```nix
+builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" "  FOO   "
+```
+
+Evaluates to `[ "FOO" ]`.

src/libexpr/builtins/mul.md

@@ -0,0 +1,5 @@
+---
+name: mul
+args: [e1, e2]
+---
+Return the product of the numbers *e1* and *e2*.

src/libexpr/builtins/outputOf.md

@@ -0,0 +1,23 @@
+---
+name: outputOf
+args: [derivation-reference, output-name]
+experimentalFeature: dynamic-derivations
+---
+Return the output path of a derivation, literally or using a placeholder if needed.
+
+If the derivation has a statically-known output path (i.e. the derivation output is input-addressed, or fixed content-addresed), the output path will just be returned.
+But if the derivation is content-addressed or if the derivation is itself not-statically produced (i.e. is the output of another derivation), a placeholder will be returned instead.
+
+*`derivation reference`* must be a string that may contain a regular store path to a derivation, or may be a placeholder reference. If the derivation is produced by a derivation, you must explicitly select `drv.outPath`.
+This primop can be chained arbitrarily deeply.
+For instance,
+
+```nix
+builtins.outputOf
+  (builtins.outputOf myDrv "out)
+  "out"
+```
+
+will return a placeholder for the output of the output of `myDrv`.
+
+This primop corresponds to the `^` sigil for derivable paths, e.g. as part of installable syntax on the command line.

src/libexpr/builtins/parseDrvName.md

@@ -0,0 +1,10 @@
+---
+name: parseDrvName
+args: [s]
+---
+Split the string *s* into a package name and version. The package
+name is everything up to but not including the first dash not followed
+by a letter, and the version is everything following that dash. The
+result is returned in a set `{ name, version }`. Thus,
+`builtins.parseDrvName "nix-0.12pre12876"` returns `{ name =
+"nix"; version = "0.12pre12876"; }`.

src/libexpr/builtins/parseFlakeRef.md

@@ -0,0 +1,19 @@
+---
+name: parseFlakeRef
+implementation: flake::prim_parseFlakeRef
+args: [flake-ref]
+experimentalFeature: flakes
+---
+Parse a flake reference, and return its exploded form.
+
+For example:
+
+```nix
+builtins.parseFlakeRef "github:NixOS/nixpkgs/23.05?dir=lib"
+```
+
+evaluates to:
+
+```nix
+{ dir = "lib"; owner = "NixOS"; ref = "23.05"; repo = "nixpkgs"; type = "github"; }
+```

src/libexpr/builtins/partition.md

@@ -0,0 +1,19 @@
+---
+name: partition
+args: [pred, list]
+---
+Given a predicate function *pred*, this function returns an
+attrset containing a list named `right`, containing the elements
+in *list* for which *pred* returned `true`, and a list named
+`wrong`, containing the elements for which it returned
+`false`. For example,
+
+```nix
+builtins.partition (x: x > 10) [1 23 9 3 42]
+```
+
+evaluates to
+
+```nix
+{ right = [ 23 42 ]; wrong = [ 1 9 3 ]; }
+```

src/libexpr/builtins/path.md

@@ -0,0 +1,31 @@
+---
+name: path
+args: [args]
+---
+An enrichment of the built-in path type, based on the attributes
+present in *args*. All are optional except `path`:
+
+  - path\
+    The underlying path.
+
+  - name\
+    The name of the path when added to the store. This can used to
+    reference paths that have nix-illegal characters in their names,
+    like `@`.
+
+  - filter\
+    A function of the type expected by `builtins.filterSource`,
+    with the same semantics.
+
+  - recursive\
+    When `false`, when `path` is added to the store it is with a
+    flat hash, rather than a hash of the NAR serialization of the
+    file. Thus, `path` must refer to a regular file, not a
+    directory. This allows similar behavior to `fetchurl`. Defaults
+    to `true`.
+
+  - sha256\
+    When provided, this is the expected hash of the file at the
+    path. Evaluation will fail if the hash is incorrect, and
+    providing a hash allows `builtins.path` to be used even when the
+    `pure-eval` nix config option is on.

src/libexpr/builtins/pathExists.md

@@ -0,0 +1,6 @@
+---
+name: pathExists
+args: [path]
+---
+Return `true` if the path *path* exists at evaluation time, and
+`false` otherwise.

src/libexpr/builtins/placeholder.md

@@ -0,0 +1,8 @@
+---
+name: placeholder
+args: [output]
+renameInGlobalScope: false
+---
+Return a placeholder string for the specified *output* that will be
+substituted by the corresponding output path at build time. Typical
+outputs would be `"out"`, `"bin"` or `"dev"`.

src/libexpr/builtins/readDir.md

@@ -0,0 +1,15 @@
+---
+name: readDir
+args: [path]
+---
+Return the contents of the directory *path* as a set mapping
+directory entries to the corresponding file type. For instance, if
+directory `A` contains a regular file `B` and another directory
+`C`, then `builtins.readDir ./A` will return the set
+
+```nix
+{ B = "regular"; C = "directory"; }
+```
+
+The possible values for the file type are `"regular"`,
+`"directory"`, `"symlink"` and `"unknown"`.

src/libexpr/builtins/readFile.md

@@ -0,0 +1,5 @@
+---
+name: readFile
+args: [path]
+---
+Return the contents of the file *path* as a string.

src/libexpr/builtins/readFileType.md

@@ -0,0 +1,6 @@
+---
+name: readFileType
+args: [p]
+---
+Determine the directory entry type of a filesystem node, being
+one of "directory", "regular", "symlink", or "unknown".

src/libexpr/builtins/removeAttrs.md

@@ -0,0 +1,13 @@
+---
+name: removeAttrs
+args: [set, list]
+renameInGlobalScope: false
+---
+Remove the attributes listed in *list* from *set*. The attributes
+don’t have to exist in *set*. For instance,
+
+```nix
+removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]
+```
+
+evaluates to `{ y = 2; }`.

src/libexpr/builtins/replaceStrings.md

@@ -0,0 +1,16 @@
+---
+name: replaceStrings
+args: [from, to, s]
+---
+Given string *s*, replace every occurrence of the strings in *from*
+with the corresponding string in *to*.
+
+The argument *to* is lazy, that is, it is only evaluated when its corresponding pattern in *from* is matched in the string *s*
+
+Example:
+
+```nix
+builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar"
+```
+
+evaluates to `"fabir"`.

src/libexpr/builtins/seq.md

@@ -0,0 +1,6 @@
+---
+name: seq
+args: [e1, e2]
+---
+Evaluate *e1*, then evaluate and return *e2*. This ensures that a
+computation is strict in the value of *e1*.

src/libexpr/builtins/sort.md

@@ -0,0 +1,17 @@
+---
+name: sort
+args: [comparator, list]
+---
+Return *list* in sorted order. It repeatedly calls the function
+*comparator* with two elements. The comparator should return `true`
+if the first element is less than the second, and `false` otherwise.
+For example,
+
+```nix
+builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ]
+```
+
+produces the list `[ 42 77 147 249 483 526 ]`.
+
+This is a stable sort: it preserves the relative order of elements
+deemed equal by the comparator.

src/libexpr/builtins/split.md

@@ -0,0 +1,33 @@
+---
+name: split
+args: [regex, str]
+---
+Returns a list composed of non matched strings interleaved with the
+lists of the [extended POSIX regular
+expression](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04)
+*regex* matches of *str*. Each item in the lists of matched
+sequences is a regex group.
+
+```nix
+builtins.split "(a)b" "abc"
+```
+
+Evaluates to `[ "" [ "a" ] "c" ]`.
+
+```nix
+builtins.split "([ac])" "abc"
+```
+
+Evaluates to `[ "" [ "a" ] "b" [ "c" ] "" ]`.
+
+```nix
+builtins.split "(a)|(c)" "abc"
+```
+
+Evaluates to `[ "" [ "a" null ] "b" [ null "c" ] "" ]`.
+
+```nix
+builtins.split "([[:upper:]]+)" " FOO "
+```
+
+Evaluates to `[ " " [ "FOO" ] " " ]`.

src/libexpr/builtins/splitVersion.md

@@ -0,0 +1,7 @@
+---
+name: splitVersion
+args: [s]
+---
+Split a string representing a version into its components, by the
+same version splitting logic underlying the version comparison in
+[`nix-env -u`](../command-ref/nix-env.md#operation---upgrade).

src/libexpr/builtins/storePath.md

@@ -0,0 +1,17 @@
+---
+name: storePath
+args: [path]
+---
+This function allows you to define a dependency on an already
+existing store path. For example, the derivation attribute `src
+= builtins.storePath /nix/store/f1d18v1y…-source` causes the
+derivation to depend on the specified path, which must exist or
+be substitutable. Note that this differs from a plain path
+(e.g. `src = /nix/store/f1d18v1y…-source`) in that the latter
+causes the path to be *copied* again to the Nix store, resulting
+in a new path (e.g. `/nix/store/ld01dnzc…-source-source`).
+
+Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
+Lix may change this, tracking issue: <https://git.lix.systems/lix-project/lix/issues/402>
+
+See also [`builtins.fetchClosure`](#builtins-fetchClosure).