Document some primops

This commit is contained in:
Eelco Dolstra 2020-08-25 11:16:45 +02:00
parent 24b1c2c66b
commit b8416779e3
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE

View file

@ -1053,7 +1053,7 @@ static RegisterPrimOp primop_toPath({
.name = "__toPath", .name = "__toPath",
.args = {"s"}, .args = {"s"},
.doc = R"( .doc = R"(
DEPRECATED. Use `/. + "/path"` to convert a string into an absolute **DEPRECATED.** Use `/. + "/path"` to convert a string into an absolute
path. For relative paths, use `./. + "/path"`. path. For relative paths, use `./. + "/path"`.
)", )",
.fun = prim_toPath, .fun = prim_toPath,
@ -1090,6 +1090,23 @@ static void prim_storePath(EvalState & state, const Pos & pos, Value * * args, V
mkString(v, path, context); mkString(v, path, context);
} }
static RegisterPrimOp primop_storePath({
.name = "__storePath",
.args = {"path"},
.doc = R"(
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`).
This function is not available in pure evaluation mode.
)",
.fun = prim_storePath,
});
static void prim_pathExists(EvalState & state, const Pos & pos, Value * * args, Value & v) static void prim_pathExists(EvalState & state, const Pos & pos, Value * * args, Value & v)
{ {
@ -2022,9 +2039,6 @@ static RegisterPrimOp primop_listToAttrs({
.fun = prim_listToAttrs, .fun = prim_listToAttrs,
}); });
/* Return the right-biased intersection of two sets as1 and as2,
i.e. a set that contains every attribute from as2 that is also a
member of as1. */
static void prim_intersectAttrs(EvalState & state, const Pos & pos, Value * * args, Value & v) static void prim_intersectAttrs(EvalState & state, const Pos & pos, Value * * args, Value & v)
{ {
state.forceAttrs(*args[0], pos); state.forceAttrs(*args[0], pos);
@ -2049,13 +2063,6 @@ static RegisterPrimOp primop_intersectAttrs({
.fun = prim_intersectAttrs, .fun = prim_intersectAttrs,
}); });
/* Collect each attribute named `attr' from a list of attribute sets.
Sets that don't contain the named attribute are ignored.
Example:
catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
=> [1 2]
*/
static void prim_catAttrs(EvalState & state, const Pos & pos, Value * * args, Value & v) static void prim_catAttrs(EvalState & state, const Pos & pos, Value * * args, Value & v)
{ {
Symbol attrName = state.symbols.create(state.forceStringNoCtx(*args[0], pos)); Symbol attrName = state.symbols.create(state.forceStringNoCtx(*args[0], pos));
@ -2077,19 +2084,23 @@ static void prim_catAttrs(EvalState & state, const Pos & pos, Value * * args, Va
v.listElems()[n] = res[n]; v.listElems()[n] = res[n];
} }
/* Return a set containing the names of the formal arguments expected static RegisterPrimOp primop_catAttrs({
by the function `f'. The value of each attribute is a Boolean .name = "__catAttrs",
denoting whether the corresponding argument has a default value. For instance, .args = {"attr", "list"},
.doc = R"(
Collect each attribute named *attr* from a list of attribute
sets. Attrsets that don't contain the named attribute are
ignored. For example,
functionArgs ({ x, y ? 123}: ...) ```nix
=> { x = false; y = true; } builtins.catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
```
"Formal argument" here refers to the attributes pattern-matched by evaluates to `[1 2]`.
the function. Plain lambdas are not included, e.g. )",
.fun = prim_catAttrs,
});
functionArgs (x: ...)
=> { }
*/
static void prim_functionArgs(EvalState & state, const Pos & pos, Value * * args, Value & v) static void prim_functionArgs(EvalState & state, const Pos & pos, Value * * args, Value & v)
{ {
state.forceValue(*args[0], pos); state.forceValue(*args[0], pos);
@ -2131,7 +2142,7 @@ static RegisterPrimOp primop_functionArgs({
.fun = prim_functionArgs, .fun = prim_functionArgs,
}); });
/* Apply a function to every element of an attribute set. */ /* */
static void prim_mapAttrs(EvalState & state, const Pos & pos, Value * * args, Value & v) static void prim_mapAttrs(EvalState & state, const Pos & pos, Value * * args, Value & v)
{ {
state.forceAttrs(*args[1], pos); state.forceAttrs(*args[1], pos);
@ -2147,6 +2158,21 @@ static void prim_mapAttrs(EvalState & state, const Pos & pos, Value * * args, Va
} }
} }
static RegisterPrimOp primop_mapAttrs({
.name = "__mapAttrs",
.args = {"f", "attrset"},
.doc = R"(
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; }`.
)",
.fun = prim_mapAttrs,
});
/************************************************************* /*************************************************************
* Lists * Lists
@ -2582,9 +2608,29 @@ static void prim_partition(EvalState & state, const Pos & pos, Value * * args, V
v.attrs->sort(); v.attrs->sort();
} }
static RegisterPrimOp primop_partition({
.name = "__partition",
.args = {"pred", "list"},
.doc = R"(
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 ]; }
```
)",
.fun = prim_partition,
});
/* concatMap = f: list: concatLists (map f list); */
/* C++-version is to avoid allocating `mkApp', call `f' eagerly */
static void prim_concatMap(EvalState & state, const Pos & pos, Value * * args, Value & v) static void prim_concatMap(EvalState & state, const Pos & pos, Value * * args, Value & v)
{ {
state.forceFunction(*args[0], pos); state.forceFunction(*args[0], pos);
@ -2611,6 +2657,16 @@ static void prim_concatMap(EvalState & state, const Pos & pos, Value * * args, V
} }
} }
static RegisterPrimOp primop_concatMap({
.name = "__concatMap",
.args = {"f", "list"},
.doc = R"(
This function is equivalent to `builtins.concatLists (map f list)`
but is more efficient.
)",
.fun = prim_concatMap,
});
/************************************************************* /*************************************************************
* Integer arithmetic * Integer arithmetic
@ -3361,17 +3417,10 @@ void EvalState::createBaseEnv()
addPrimOp("__addErrorContext", 2, prim_addErrorContext); addPrimOp("__addErrorContext", 2, prim_addErrorContext);
// Paths // Paths
addPrimOp("__storePath", 1, prim_storePath);
addPrimOp("__findFile", 2, prim_findFile); addPrimOp("__findFile", 2, prim_findFile);
// Sets // Sets
addPrimOp("__unsafeGetAttrPos", 2, prim_unsafeGetAttrPos); addPrimOp("__unsafeGetAttrPos", 2, prim_unsafeGetAttrPos);
addPrimOp("__catAttrs", 2, prim_catAttrs);
addPrimOp("__mapAttrs", 2, prim_mapAttrs);
// Lists
addPrimOp("__partition", 2, prim_partition);
addPrimOp("__concatMap", 2, prim_concatMap);
// Derivations // Derivations
addPrimOp("derivationStrict", 1, prim_derivationStrict); addPrimOp("derivationStrict", 1, prim_derivationStrict);