diff options
Diffstat (limited to 'doc/manual/expressions/builtins.xml')
| -rw-r--r-- | doc/manual/expressions/builtins.xml | 129 |
1 files changed, 120 insertions, 9 deletions
diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml index 6bdfdd55c4b6..eae5f5a029bf 100644 --- a/doc/manual/expressions/builtins.xml +++ b/doc/manual/expressions/builtins.xml @@ -32,13 +32,35 @@ available as <function>builtins.derivation</function>.</para> <varlistentry><term><function>builtins.add</function> <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - <listitem><para>Return the sum of the integers + <listitem><para>Return the sum of the numbers <replaceable>e1</replaceable> and <replaceable>e2</replaceable>.</para></listitem> </varlistentry> + <varlistentry><term><function>builtins.all</function> + <replaceable>pred</replaceable> <replaceable>list</replaceable></term> + + <listitem><para>Return <literal>true</literal> if the function + <replaceable>pred</replaceable> returns <literal>true</literal> + for all elements of <replaceable>list</replaceable>, + and <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + + <varlistentry><term><function>builtins.any</function> + <replaceable>pred</replaceable> <replaceable>list</replaceable></term> + + <listitem><para>Return <literal>true</literal> if the function + <replaceable>pred</replaceable> returns <literal>true</literal> + for at least one element of <replaceable>list</replaceable>, + and <literal>false</literal> otherwise.</para></listitem> + + </varlistentry> + + <varlistentry><term><function>builtins.attrNames</function> <replaceable>set</replaceable></term> @@ -182,7 +204,7 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting> <varlistentry><term><function>builtins.div</function> <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - <listitem><para>Return the quotient of the integers + <listitem><para>Return the quotient of the numbers <replaceable>e1</replaceable> and <replaceable>e2</replaceable>.</para></listitem> @@ -313,6 +335,37 @@ stdenv.mkDerivation { </varlistentry> + <varlistentry><term><function>builtins.foldl’</function> + <replaceable>op</replaceable> <replaceable>nul</replaceable> <replaceable>list</replaceable></term> + + <listitem><para>Reduce a list by applying a binary operator, from + left to right, e.g. <literal>foldl’ op nul [x0 x1 x2 ...] = op (op + (op nul x0) x1) x2) ...</literal>. The operator is applied + strictly, i.e., its arguments are evaluated first. For example, + <literal>foldl’ (x: y: x + y) 0 [1 2 3]</literal> evaluates to + 6.</para></listitem> + + </varlistentry> + + + <varlistentry><term><function>builtins.functionArgs</function> + <replaceable>f</replaceable></term> + + <listitem><para> + Return a set containing the names of the formal arguments expected + by the function <replaceable>f</replaceable>. + The value of each attribute is a Boolean denoting whether the corresponding + argument has a default value. For instance, + <literal>functionArgs ({ x, y ? 123}: ...) = { x = false; y = true; }</literal>. + </para> + + <para>"Formal argument" here refers to the attributes pattern-matched by + the function. Plain lambdas are not included, e.g. + <literal>functionArgs (x: ...) = { }</literal>. + </para></listitem> + </varlistentry> + + <varlistentry><term><function>builtins.fromJSON</function> <replaceable>e</replaceable></term> <listitem><para>Convert a JSON string to a Nix @@ -329,6 +382,24 @@ builtins.fromJSON ''{"x": [1, 2, 3], "y": null}'' </varlistentry> + <varlistentry><term><function>builtins.genList</function> + <replaceable>generator</replaceable> <replaceable>length</replaceable></term> + + <listitem><para>Generate list of size + <replaceable>length</replaceable>, with each element + <replaceable>i></replaceable> equal to the value returned by + <replaceable>generator</replaceable> <literal>i</literal>. For + example, + +<programlisting> +builtins.genList (x: x * x) 5 +</programlisting> + + returns the list <literal>[ 0 1 4 9 16 ]</literal>.</para></listitem> + + </varlistentry> + + <varlistentry><term><function>builtins.getAttr</function> <replaceable>s</replaceable> <replaceable>set</replaceable></term> @@ -549,12 +620,12 @@ x: x + 456</programlisting> <varlistentry><term><function>builtins.lessThan</function> <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - <listitem><para>Return <literal>true</literal> if the integer - <replaceable>e1</replaceable> is less than the integer + <listitem><para>Return <literal>true</literal> if the number + <replaceable>e1</replaceable> is less than the number <replaceable>e2</replaceable>, and <literal>false</literal> otherwise. Evaluation aborts if either <replaceable>e1</replaceable> or <replaceable>e2</replaceable> - does not evaluate to an integer.</para></listitem> + does not evaluate to a number.</para></listitem> </varlistentry> @@ -605,7 +676,7 @@ map (x: "foo" + x) [ "bar" "bla" "abc" ]</programlisting> <varlistentry><term><function>builtins.mul</function> <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - <listitem><para>Return the product of the integers + <listitem><para>Return the product of the numbers <replaceable>e1</replaceable> and <replaceable>e2</replaceable>.</para></listitem> @@ -663,7 +734,7 @@ in config.someSetting</programlisting> ./A</literal> will return the set <programlisting> -{ A = "regular"; B = "directory"; }</programlisting> +{ B = "regular"; C = "directory"; }</programlisting> The possible values for the file type are <literal>"regular"</literal>, <literal>"directory"</literal>, @@ -698,6 +769,23 @@ removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting> </varlistentry> + <varlistentry><term><function>builtins.replaceStrings</function> + <replaceable>from</replaceable> <replaceable>to</replaceable> <replaceable>s</replaceable></term> + + <listitem><para>Given string <replaceable>s</replaceable>, replace + every occurrence of the strings in <replaceable>from</replaceable> + with the corresponding string in + <replaceable>to</replaceable>. For example, + +<programlisting> +builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar" +</programlisting> + + evaluates to <literal>"fabir"</literal>.</para></listitem> + + </varlistentry> + + <varlistentry><term><function>builtins.seq</function> <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> @@ -709,6 +797,29 @@ removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting> </varlistentry> + <varlistentry><term><function>builtins.sort</function> + <replaceable>comparator</replaceable> <replaceable>list</replaceable></term> + + <listitem><para>Return <replaceable>list</replaceable> in sorted + order. It repeatedly calls the function + <replaceable>comparator</replaceable> with two elements. The + comparator should return <literal>true</literal> if the first + element is less than the second, and <literal>false</literal> + otherwise. For example, + +<programlisting> +builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ] +</programlisting> + + produces the list <literal>[ 42 77 147 249 483 526 + ]</literal>.</para> + + <para>This is a stable sort: it preserves the relative order of + elements deemed equal by the comparator.</para></listitem> + + </varlistentry> + + <varlistentry><term><function>builtins.stringLength</function> <replaceable>e</replaceable></term> @@ -722,7 +833,7 @@ removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ]</programlisting> <varlistentry><term><function>builtins.sub</function> <replaceable>e1</replaceable> <replaceable>e2</replaceable></term> - <listitem><para>Return the difference between the integers + <listitem><para>Return the difference between the numbers <replaceable>e1</replaceable> and <replaceable>e2</replaceable>.</para></listitem> @@ -849,7 +960,7 @@ in foo</programlisting> <varlistentry><term><function>builtins.toJSON</function> <replaceable>e</replaceable></term> <listitem><para>Return a string containing a JSON representation - of <replaceable>e</replaceable>. Strings, integers, booleans, + of <replaceable>e</replaceable>. Strings, integers, floats, booleans, nulls and lists are mapped to their JSON equivalents. Sets (except derivations) are represented as objects. Derivations are translated to a JSON string containing the derivation’s output |