diff options
Diffstat (limited to 'doc/functions')
| -rw-r--r-- | doc/functions/debug.section.md | 5 | ||||
| -rw-r--r-- | doc/functions/generators.section.md | 56 | ||||
| -rw-r--r-- | doc/functions/library.xml | 30 | ||||
| -rw-r--r-- | doc/functions/library/asserts.xml | 112 | ||||
| -rw-r--r-- | doc/functions/library/attrsets.xml | 1751 | ||||
| -rw-r--r-- | doc/functions/nix-gitignore.section.md | 49 | ||||
| -rw-r--r-- | doc/functions/prefer-remote-fetch.section.md | 17 |
7 files changed, 2020 insertions, 0 deletions
diff --git a/doc/functions/debug.section.md b/doc/functions/debug.section.md new file mode 100644 index 00000000000..b2d8589431a --- /dev/null +++ b/doc/functions/debug.section.md @@ -0,0 +1,5 @@ +# Debugging Nix Expressions {#sec-debug} + +Nix is a unityped, dynamic language, this means every value can potentially appear anywhere. Since it is also non-strict, evaluation order and what ultimately is evaluated might surprise you. Therefore it is important to be able to debug nix expressions. + +In the `lib/debug.nix` file you will find a number of functions that help (pretty-)printing values while evaluation is running. You can even specify how deep these values should be printed recursively, and transform them on the fly. Please consult the docstrings in `lib/debug.nix` for usage information. diff --git a/doc/functions/generators.section.md b/doc/functions/generators.section.md new file mode 100644 index 00000000000..d54e5027c79 --- /dev/null +++ b/doc/functions/generators.section.md @@ -0,0 +1,56 @@ +# Generators {#sec-generators} +Generators are functions that create file formats from nix data structures, e. g. for configuration files. There are generators available for: `INI`, `JSON` and `YAML` + +All generators follow a similar call interface: `generatorName configFunctions data`, where `configFunctions` is an attrset of user-defined functions that format nested parts of the content. They each have common defaults, so often they do not need to be set manually. An example is `mkSectionName ? (name: libStr.escape [ "[" "]" ] name)` from the `INI` generator. It receives the name of a section and sanitizes it. The default `mkSectionName` escapes `[` and `]` with a backslash. + +Generators can be fine-tuned to produce exactly the file format required by your application/service. One example is an INI-file format which uses `: ` as separator, the strings `"yes"`/`"no"` as boolean values and requires all string values to be quoted: + +```nix +with lib; +let + customToINI = generators.toINI { + # specifies how to format a key/value pair + mkKeyValue = generators.mkKeyValueDefault { + # specifies the generated string for a subset of nix values + mkValueString = v: + if v == true then ''"yes"'' + else if v == false then ''"no"'' + else if isString v then ''"${v}"'' + # and delegats all other values to the default generator + else generators.mkValueStringDefault {} v; + } ":"; + }; + +# the INI file can now be given as plain old nix values +in customToINI { + main = { + pushinfo = true; + autopush = false; + host = "localhost"; + port = 42; + }; + mergetool = { + merge = "diff3"; + }; +} +``` + +This will produce the following INI file as nix string: + +```INI +[main] +autopush:"no" +host:"localhost" +port:42 +pushinfo:"yes" +str\:ange:"very::strange" + +[mergetool] +merge:"diff3" +``` + +::: {.note} +Nix store paths can be converted to strings by enclosing a derivation attribute like so: `"${drv}"`. +::: + +Detailed documentation for each generator can be found in `lib/generators.nix`. diff --git a/doc/functions/library.xml b/doc/functions/library.xml new file mode 100644 index 00000000000..21bcf5b88c9 --- /dev/null +++ b/doc/functions/library.xml @@ -0,0 +1,30 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="sec-functions-library"> + <title>Nixpkgs Library Functions</title> + + <para> + Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or through <code>import <nixpkgs/lib></code>. + </para> + + <xi:include href="./library/asserts.xml" /> + + <xi:include href="./library/attrsets.xml" /> + +<!-- These docs are generated via nixdoc. To add another generated + library function file to this list, the file + `lib-function-docs.nix` must also be updated. --> + + <xi:include href="./library/generated/strings.xml" /> + + <xi:include href="./library/generated/trivial.xml" /> + + <xi:include href="./library/generated/lists.xml" /> + + <xi:include href="./library/generated/debug.xml" /> + + <xi:include href="./library/generated/options.xml" /> + + <xi:include href="./library/generated/sources.xml" /> +</section> diff --git a/doc/functions/library/asserts.xml b/doc/functions/library/asserts.xml new file mode 100644 index 00000000000..7c94222ef13 --- /dev/null +++ b/doc/functions/library/asserts.xml @@ -0,0 +1,112 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="sec-functions-library-asserts"> + <title>Assert functions</title> + + <section xml:id="function-library-lib.asserts.assertMsg"> + <title><function>lib.asserts.assertMsg</function></title> + + <subtitle><literal>assertMsg :: Bool -> String -> Bool</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.asserts.assertMsg" /> + + <para> + Print a trace message if <literal>pred</literal> is false. + </para> + + <para> + Intended to be used to augment asserts with helpful error messages. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + Condition under which the <varname>msg</varname> should <emphasis>not</emphasis> be printed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>msg</varname> + </term> + <listitem> + <para> + Message to print. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.asserts.assertMsg-example-false"> + <title>Printing when the predicate is false</title> +<programlisting><![CDATA[ +assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly" +stderr> trace: foo is not bar, silly +stderr> assert failed +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.asserts.assertOneOf"> + <title><function>lib.asserts.assertOneOf</function></title> + + <subtitle><literal>assertOneOf :: String -> String -> + StringList -> Bool</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" /> + + <para> + Specialized <function>asserts.assertMsg</function> for checking if <varname>val</varname> is one of the elements of <varname>xs</varname>. Useful for checking enums. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the variable the user entered <varname>val</varname> into, for inclusion in the error message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>val</varname> + </term> + <listitem> + <para> + The value of what the user provided, to be compared against the values in <varname>xs</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>xs</varname> + </term> + <listitem> + <para> + The list of valid values. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.asserts.assertOneOf-example"> + <title>Ensuring a user provided a possible value</title> +<programlisting><![CDATA[ +let sslLibrary = "bearssl"; +in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "libressl" ]; +=> false +stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl" + ]]></programlisting> + </example> + </section> +</section> diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml new file mode 100644 index 00000000000..052bfa1f6ae --- /dev/null +++ b/doc/functions/library/attrsets.xml @@ -0,0 +1,1751 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="sec-functions-library-attrset"> + <title>Attribute-Set Functions</title> + + <section xml:id="function-library-lib.attrsets.attrByPath"> + <title><function>lib.attrset.attrByPath</function></title> + + <subtitle><literal>attrByPath :: [String] -> Any -> AttrSet -> Any</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.attrByPath" /> + + <para> + Return an attribute from within nested attribute sets. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attrPath</varname> + </term> + <listitem> + <para> + A list of strings representing the path through the nested attribute set <varname>set</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>default</varname> + </term> + <listitem> + <para> + Default value if <varname>attrPath</varname> does not resolve to an existing value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The nested attributeset to select values from. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrset.attrByPath-example-value-exists"> + <title>Extracting a value from a nested attribute set</title> +<programlisting><![CDATA[ +let set = { a = { b = 3; }; }; +in lib.attrsets.attrByPath [ "a" "b" ] 0 set +=> 3 +]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrset.attrByPath-example-default-value"> + <title>No value at the path, instead using the default</title> +<programlisting><![CDATA[ +lib.attrsets.attrByPath [ "a" "b" ] 0 {} +=> 0 +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.hasAttrByPath"> + <title><function>lib.attrsets.hasAttrByPath</function></title> + + <subtitle><literal>hasAttrByPath :: [String] -> AttrSet -> Bool</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.hasAttrByPath" /> + + <para> + Determine if an attribute exists within a nested attribute set. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attrPath</varname> + </term> + <listitem> + <para> + A list of strings representing the path through the nested attribute set <varname>set</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The nested attributeset to check. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.hasAttrByPath-example"> + <title>A nested value does exist inside a set</title> +<programlisting><![CDATA[ +lib.attrsets.hasAttrByPath + [ "a" "b" "c" "d" ] + { a = { b = { c = { d = 123; }; }; }; } +=> true +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.setAttrByPath"> + <title><function>lib.attrsets.setAttrByPath</function></title> + + <subtitle><literal>setAttrByPath :: [String] -> Any -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.setAttrByPath" /> + + <para> + Create a new attribute set with <varname>value</varname> set at the nested attribute location specified in <varname>attrPath</varname>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attrPath</varname> + </term> + <listitem> + <para> + A list of strings representing the path through the nested attribute set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The value to set at the location described by <varname>attrPath</varname>. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.setAttrByPath-example"> + <title>Creating a new nested attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.setAttrByPath [ "a" "b" ] 3 +=> { a = { b = 3; }; } +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.getAttrFromPath"> + <title><function>lib.attrsets.getAttrFromPath</function></title> + + <subtitle><literal>getAttrFromPath :: [String] -> AttrSet -> Value</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.getAttrFromPath" /> + + <para> + Like <xref linkend="function-library-lib.attrsets.attrByPath" /> except without a default, and it will throw if the value doesn't exist. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attrPath</varname> + </term> + <listitem> + <para> + A list of strings representing the path through the nested attribute set <varname>set</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The nested attribute set to find the value in. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.getAttrPath-example-success"> + <title>Succesfully getting a value from an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.getAttrFromPath [ "a" "b" ] { a = { b = 3; }; } +=> 3 +]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrsets.getAttrPath-example-throw"> + <title>Throwing after failing to get a value from an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.getAttrFromPath [ "x" "y" ] { } +=> error: cannot find attribute `x.y' +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.attrVals"> + <title><function>lib.attrsets.attrVals</function></title> + + <subtitle><literal>attrVals :: [String] -> AttrSet -> [Any]</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.attrVals" /> + + <para> + Return the specified attributes from a set. All values must exist. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>nameList</varname> + </term> + <listitem> + <para> + The list of attributes to fetch from <varname>set</varname>. Each attribute name must exist on the attrbitue set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The set to get attribute values from. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.attrVals-example-success"> + <title>Getting several values from an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.attrVals [ "a" "b" "c" ] { a = 1; b = 2; c = 3; } +=> [ 1 2 3 ] +]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrsets.attrVals-failure"> + <title>Getting missing values from an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.attrVals [ "d" ] { } +error: attribute 'd' missing +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.attrValues"> + <title><function>lib.attrsets.attrValues</function></title> + + <subtitle><literal>attrValues :: AttrSet -> [Any]</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.attrValues" /> + + <para> + Get all the attribute values from an attribute set. + </para> + + <para> + Provides a backwards-compatible interface of <function>builtins.attrValues</function> for Nix version older than 1.8. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attrs</varname> + </term> + <listitem> + <para> + The attribute set. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.attrValues-example"> + <title></title> +<programlisting><![CDATA[ +lib.attrsets.attrValues { a = 1; b = 2; c = 3; } +=> [ 1 2 3 ] +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.catAttrs"> + <title><function>lib.attrsets.catAttrs</function></title> + + <subtitle><literal>catAttrs :: String -> [AttrSet] -> [Any]</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.catAttrs" /> + + <para> + Collect each attribute named `attr' from the list of attribute sets, <varname>sets</varname>. Sets that don't contain the named attribute are ignored. + </para> + + <para> + Provides a backwards-compatible interface of <function>builtins.catAttrs</function> for Nix version older than 1.9. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attr</varname> + </term> + <listitem> + <para> + Attribute name to select from each attribute set in <varname>sets</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>sets</varname> + </term> + <listitem> + <para> + The list of attribute sets to select <varname>attr</varname> from. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.catAttrs-example"> + <title>Collect an attribute from a list of attribute sets.</title> + <para> + Attribute sets which don't have the attribute are ignored. + </para> +<programlisting><![CDATA[ +catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}] +=> [ 1 2 ] + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.filterAttrs"> + <title><function>lib.attrsets.filterAttrs</function></title> + + <subtitle><literal>filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrs" /> + + <para> + Filter an attribute set by removing all attributes for which the given predicate return false. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + <literal>String -> Any -> Bool</literal> + </para> + <para> + Predicate which returns true to include an attribute, or returns false to exclude it. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The attribute's name + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Returns <literal>true</literal> to include the attribute, <literal>false</literal> to exclude the attribute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to filter + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.filterAttrs-example"> + <title>Filtering an attributeset</title> +<programlisting><![CDATA[ +filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; } +=> { foo = 1; } +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.filterAttrsRecursive"> + <title><function>lib.attrsets.filterAttrsRecursive</function></title> + + <subtitle><literal>filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrsRecursive" /> + + <para> + Filter an attribute set recursively by removing all attributes for which the given predicate return false. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + <literal>String -> Any -> Bool</literal> + </para> + <para> + Predicate which returns true to include an attribute, or returns false to exclude it. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The attribute's name + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + Returns <literal>true</literal> to include the attribute, <literal>false</literal> to exclude the attribute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to filter + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.filterAttrsRecursive-example"> + <title>Recursively filtering an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.filterAttrsRecursive + (n: v: v != null) + { + levelA = { + example = "hi"; + levelB = { + hello = "there"; + this-one-is-present = { + this-is-excluded = null; + }; + }; + this-one-is-also-excluded = null; + }; + also-excluded = null; + } +=> { + levelA = { + example = "hi"; + levelB = { + hello = "there"; + this-one-is-present = { }; + }; + }; + } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.foldAttrs"> + <title><function>lib.attrsets.foldAttrs</function></title> + + <subtitle><literal>foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.foldAttrs" /> + + <para> + Apply fold function to values grouped by key. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>op</varname> + </term> + <listitem> + <para> + <literal>Any -> Any -> Any</literal> + </para> + <para> + Given a value <varname>val</varname> and a collector <varname>col</varname>, combine the two. + </para> + <variablelist> + <varlistentry> + <term> + <varname>val</varname> + </term> + <listitem> + <para> + An attribute's value + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>col</varname> + </term> + <listitem> +<!-- TODO: make this not bad, use more fold-ey terms --> + <para> + The result of previous <function>op</function> calls with other values and <function>nul</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>nul</varname> + </term> + <listitem> + <para> + The null-value, the starting value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>list_of_attrs</varname> + </term> + <listitem> + <para> + A list of attribute sets to fold together by key. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.foldAttrs-example"> + <title>Combining an attribute of lists in to one attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.foldAttrs + (n: a: [n] ++ a) [] + [ + { a = 2; b = 7; } + { a = 3; } + { b = 6; } + ] +=> { a = [ 2 3 ]; b = [ 7 6 ]; } +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.collect"> + <title><function>lib.attrsets.collect</function></title> + + <subtitle><literal>collect :: (Any -> Bool) -> AttrSet -> [Any]</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.collect" /> + + <para> + Recursively collect sets that verify a given predicate named <varname>pred</varname> from the set <varname>attrs</varname>. The recursion stops when <varname>pred</varname> returns <literal>true</literal>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + <literal>Any -> Bool</literal> + </para> + <para> + Given an attribute's value, determine if recursion should stop. + </para> + <variablelist> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute set value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>attrs</varname> + </term> + <listitem> + <para> + The attribute set to recursively collect. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.collect-example-lists"> + <title>Collecting all lists from an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.collect isList { a = { b = ["b"]; }; c = [1]; } +=> [["b"] [1]] +]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrsets.collect-example-outpath"> + <title>Collecting all attribute-sets which contain the <literal>outPath</literal> attribute name.</title> +<programlisting><![CDATA[ +collect (x: x ? outPath) + { a = { outPath = "a/"; }; b = { outPath = "b/"; }; } +=> [{ outPath = "a/"; } { outPath = "b/"; }] +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.nameValuePair"> + <title><function>lib.attrsets.nameValuePair</function></title> + + <subtitle><literal>nameValuePair :: String -> Any -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.nameValuePair" /> + + <para> + Utility function that creates a <literal>{name, value}</literal> pair as expected by <function>builtins.listToAttrs</function>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The attribute name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute value. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.nameValuePair-example"> + <title>Creating a name value pair</title> +<programlisting><![CDATA[ +nameValuePair "some" 6 +=> { name = "some"; value = 6; } +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.mapAttrs"> + <title><function>lib.attrsets.mapAttrs</function></title> + + <subtitle><literal></literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs" /> + + <para> + Apply a function to each element in an attribute set, creating a new attribute set. + </para> + + <para> + Provides a backwards-compatible interface of <function>builtins.mapAttrs</function> for Nix version older than 2.1. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>fn</varname> + </term> + <listitem> + <para> + <literal>String -> Any -> Any</literal> + </para> + <para> + Given an attribute's name and value, return a new value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.mapAttrs-example"> + <title>Modifying each value of an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.mapAttrs + (name: value: name + "-" + value) + { x = "foo"; y = "bar"; } +=> { x = "x-foo"; y = "y-bar"; } +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.mapAttrs-prime"> + <title><function>lib.attrsets.mapAttrs'</function></title> + + <subtitle><literal>mapAttrs' :: (String -> Any -> { name = String; value = Any }) -> AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs-prime" /> + + <para> + Like <function>mapAttrs</function>, but allows the name of each attribute to be changed in addition to the value. The applied function should return both the new name and value as a <function>nameValuePair</function>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>fn</varname> + </term> + <listitem> + <para> + <literal>String -> Any -> { name = String; value = Any }</literal> + </para> + <para> + Given an attribute's name and value, return a new <link + linkend="function-library-lib.attrsets.nameValuePair">name value pair</link>. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to map over. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.mapAttrs-prime-example"> + <title>Change the name and value of each attribute of an attribute set</title> +<programlisting><![CDATA[ +lib.attrsets.mapAttrs' (name: value: lib.attrsets.nameValuePair ("foo_" + name) ("bar-" + value)) + { x = "a"; y = "b"; } +=> { foo_x = "bar-a"; foo_y = "bar-b"; } + + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.mapAttrsToList"> + <title><function>lib.attrsets.mapAttrsToList</function></title> + + <subtitle><literal>mapAttrsToList :: (String -> Any -> Any) -> + AttrSet -> [Any]</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsToList" /> + + <para> + Call <varname>fn</varname> for each attribute in the given <varname>set</varname> and return the result in a list. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>fn</varname> + </term> + <listitem> + <para> + <literal>String -> Any -> Any</literal> + </para> + <para> + Given an attribute's name and value, return a new value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to map over. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.mapAttrsToList-example"> + <title>Combine attribute values and names in to a list</title> +<programlisting><![CDATA[ +lib.attrsets.mapAttrsToList (name: value: "${name}=${value}") + { x = "a"; y = "b"; } +=> [ "x=a" "y=b" ] +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.mapAttrsRecursive"> + <title><function>lib.attrsets.mapAttrsRecursive</function></title> + + <subtitle><literal>mapAttrsRecursive :: ([String] > Any -> Any) -> AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsRecursive" /> + + <para> + Like <function>mapAttrs</function>, except that it recursively applies itself to attribute sets. Also, the first argument of the argument function is a <emphasis>list</emphasis> of the names of the containing attributes. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>f</varname> + </term> + <listitem> + <para> + <literal>[ String ] -> Any -> Any</literal> + </para> + <para> + Given a list of attribute names and value, return a new value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name_path</varname> + </term> + <listitem> + <para> + The list of attribute names to this value. + </para> + <para> + For example, the <varname>name_path</varname> for the <literal>example</literal> string in the attribute set <literal>{ foo = { bar = "example"; }; }</literal> is <literal>[ "foo" "bar" ]</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to recursively map over. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.mapAttrsRecursive-example"> + <title>A contrived example of using <function>lib.attrsets.mapAttrsRecursive</function></title> +<programlisting><![CDATA[ +mapAttrsRecursive + (path: value: concatStringsSep "-" (path ++ [value])) + { + n = { + a = "A"; + m = { + b = "B"; + c = "C"; + }; + }; + d = "D"; + } +=> { + n = { + a = "n-a-A"; + m = { + b = "n-m-b-B"; + c = "n-m-c-C"; + }; + }; + d = "d-D"; + } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.mapAttrsRecursiveCond"> + <title><function>lib.attrsets.mapAttrsRecursiveCond</function></title> + + <subtitle><literal>mapAttrsRecursiveCond :: (AttrSet -> Bool) -> ([ String ] -> Any -> Any) -> AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsRecursiveCond" /> + + <para> + Like <function>mapAttrsRecursive</function>, but it takes an additional predicate function that tells it whether to recursive into an attribute set. If it returns false, <function>mapAttrsRecursiveCond</function> does not recurse, but does apply the map function. It is returns true, it does recurse, and does not apply the map function. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>cond</varname> + </term> + <listitem> + <para> + <literal>(AttrSet -> Bool)</literal> + </para> + <para> + Determine if <function>mapAttrsRecursive</function> should recurse deeper in to the attribute set. + </para> + <variablelist> + <varlistentry> + <term> + <varname>attributeset</varname> + </term> + <listitem> + <para> + An attribute set. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>f</varname> + </term> + <listitem> + <para> + <literal>[ String ] -> Any -> Any</literal> + </para> + <para> + Given a list of attribute names and value, return a new value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name_path</varname> + </term> + <listitem> + <para> + The list of attribute names to this value. + </para> + <para> + For example, the <varname>name_path</varname> for the <literal>example</literal> string in the attribute set <literal>{ foo = { bar = "example"; }; }</literal> is <literal>[ "foo" "bar" ]</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The attribute's value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + The attribute set to recursively map over. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.mapAttrsRecursiveCond-example"> + <title>Only convert attribute values to JSON if the containing attribute set is marked for recursion</title> +<programlisting><![CDATA[ +lib.attrsets.mapAttrsRecursiveCond + ({ recurse ? false, ... }: recurse) + (name: value: builtins.toJSON value) + { + dorecur = { + recurse = true; + hello = "there"; + }; + dontrecur = { + converted-to- = "json"; + }; + } +=> { + dorecur = { + hello = "\"there\""; + recurse = "true"; + }; + dontrecur = "{\"converted-to\":\"json\"}"; + } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.genAttrs"> + <title><function>lib.attrsets.genAttrs</function></title> + + <subtitle><literal>genAttrs :: [ String ] -> (String -> Any) -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.genAttrs" /> + + <para> + Generate an attribute set by mapping a function over a list of attribute names. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>names</varname> + </term> + <listitem> + <para> + Names of values in the resulting attribute set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>f</varname> + </term> + <listitem> + <para> + <literal>String -> Any</literal> + </para> + <para> + Takes the name of the attribute and return the attribute's value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute to generate a value for. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.genAttrs-example"> + <title>Generate an attrset based on names only</title> +<programlisting><![CDATA[ +lib.attrsets.genAttrs [ "foo" "bar" ] (name: "x_${name}") +=> { foo = "x_foo"; bar = "x_bar"; } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.isDerivation"> + <title><function>lib.attrsets.isDerivation</function></title> + + <subtitle><literal>isDerivation :: Any -> Bool</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.isDerivation" /> + + <para> + Check whether the argument is a derivation. Any set with <code>{ type = "derivation"; }</code> counts as a derivation. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>value</varname> + </term> + <listitem> + <para> + The value which is possibly a derivation. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.isDerivation-example-true"> + <title>A package is a derivation</title> +<programlisting><![CDATA[ +lib.attrsets.isDerivation (import <nixpkgs> {}).ruby +=> true + ]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrsets.isDerivation-example-false"> + <title>Anything else is not a derivation</title> +<programlisting><![CDATA[ +lib.attrsets.isDerivation "foobar" +=> false + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.toDerivation"> + <title><function>lib.attrsets.toDerivation</function></title> + + <subtitle><literal>toDerivation :: Path -> Derivation</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.toDerivation" /> + + <para> + Converts a store path to a fake derivation. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>path</varname> + </term> + <listitem> + <para> + A store path to convert to a derivation. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section xml:id="function-library-lib.attrsets.optionalAttrs"> + <title><function>lib.attrsets.optionalAttrs</function></title> + + <subtitle><literal>optionalAttrs :: Bool -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.optionalAttrs" /> + + <para> + Conditionally return an attribute set or an empty attribute set. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>cond</varname> + </term> + <listitem> + <para> + Condition under which the <varname>as</varname> attribute set is returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>as</varname> + </term> + <listitem> + <para> + The attribute set to return if <varname>cond</varname> is true. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.optionalAttrs-example-true"> + <title>Return the provided attribute set when <varname>cond</varname> is true</title> +<programlisting><![CDATA[ +lib.attrsets.optionalAttrs true { my = "set"; } +=> { my = "set"; } + ]]></programlisting> + </example> + + <example xml:id="function-library-lib.attrsets.optionalAttrs-example-false"> + <title>Return an empty attribute set when <varname>cond</varname> is false</title> +<programlisting><![CDATA[ +lib.attrsets.optionalAttrs false { my = "set"; } +=> { } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.zipAttrsWithNames"> + <title><function>lib.attrsets.zipAttrsWithNames</function></title> + + <subtitle><literal>zipAttrsWithNames :: [ String ] -> (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrsWithNames" /> + + <para> + Merge sets of attributes and use the function <varname>f</varname> to merge attribute values where the attribute name is in <varname>names</varname>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>names</varname> + </term> + <listitem> + <para> + A list of attribute names to zip. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>f</varname> + </term> + <listitem> + <para> + <literal>(String -> [ Any ] -> Any</literal> + </para> + <para> + Accepts an attribute name, all the values, and returns a combined value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute each value came from. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>vs</varname> + </term> + <listitem> + <para> + A list of values collected from the list of attribute sets. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>sets</varname> + </term> + <listitem> + <para> + A list of attribute sets to zip together. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.zipAttrsWithNames-example"> + <title>Summing a list of attribute sets of numbers</title> +<programlisting><![CDATA[ +lib.attrsets.zipAttrsWithNames + [ "a" "b" ] + (name: vals: "${name} ${toString (builtins.foldl' (a: b: a + b) 0 vals)}") + [ + { a = 1; b = 1; c = 1; } + { a = 10; } + { b = 100; } + { c = 1000; } + ] +=> { a = "a 11"; b = "b 101"; } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.zipAttrsWith"> + <title><function>lib.attrsets.zipAttrsWith</function></title> + + <subtitle><literal>zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrsWith" /> + + <para> + Merge sets of attributes and use the function <varname>f</varname> to merge attribute values. Similar to <xref + linkend="function-library-lib.attrsets.zipAttrsWithNames" /> where all key names are passed for <varname>names</varname>. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>f</varname> + </term> + <listitem> + <para> + <literal>(String -> [ Any ] -> Any</literal> + </para> + <para> + Accepts an attribute name, all the values, and returns a combined value. + </para> + <variablelist> + <varlistentry> + <term> + <varname>name</varname> + </term> + <listitem> + <para> + The name of the attribute each value came from. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>vs</varname> + </term> + <listitem> + <para> + A list of values collected from the list of attribute sets. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>sets</varname> + </term> + <listitem> + <para> + A list of attribute sets to zip together. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.zipAttrsWith-example"> + <title>Summing a list of attribute sets of numbers</title> +<programlisting><![CDATA[ +lib.attrsets.zipAttrsWith + (name: vals: "${name} ${toString (builtins.foldl' (a: b: a + b) 0 vals)}") + [ + { a = 1; b = 1; c = 1; } + { a = 10; } + { b = 100; } + { c = 1000; } + ] +=> { a = "a 11"; b = "b 101"; c = "c 1001"; } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.zipAttrs"> + <title><function>lib.attrsets.zipAttrs</function></title> + + <subtitle><literal>zipAttrs :: [ AttrSet ] -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrs" /> + + <para> + Merge sets of attributes and combine each attribute value in to a list. Similar to <xref linkend="function-library-lib.attrsets.zipAttrsWith" /> where the merge function returns a list of all values. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>sets</varname> + </term> + <listitem> + <para> + A list of attribute sets to zip together. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.zipAttrs-example"> + <title>Combining a list of attribute sets</title> +<programlisting><![CDATA[ +lib.attrsets.zipAttrs + [ + { a = 1; b = 1; c = 1; } + { a = 10; } + { b = 100; } + { c = 1000; } + ] +=> { a = [ 1 10 ]; b = [ 1 100 ]; c = [ 1 1000 ]; } + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.recursiveUpdateUntil"> + <title><function>lib.attrsets.recursiveUpdateUntil</function></title> + + <subtitle><literal>recursiveUpdateUntil :: ( [ String ] -> AttrSet -> AttrSet -> Bool ) -> AttrSet -> AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.recursiveUpdateUntil" /> + + <para> + Does the same as the update operator <literal>//</literal> except that attributes are merged until the given predicate is verified. The predicate should accept 3 arguments which are the path to reach the attribute, a part of the first attribute set and a part of the second attribute set. When the predicate is verified, the value of the first attribute set is replaced by the value of the second attribute set. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>pred</varname> + </term> + <listitem> + <para> + <literal>[ String ] -> AttrSet -> AttrSet -> Bool</literal> + </para> + <variablelist> + <varlistentry> + <term> + <varname>path</varname> + </term> + <listitem> + <para> + The path to the values in the left and right hand sides. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>l</varname> + </term> + <listitem> + <para> + The left hand side value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>r</varname> + </term> + <listitem> + <para> + The right hand side value. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>lhs</varname> + </term> + <listitem> + <para> + The left hand attribute set of the merge. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>rhs</varname> + </term> + <listitem> + <para> + The right hand attribute set of the merge. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.recursiveUpdateUntil-example"> + <title>Recursively merging two attribute sets</title> +<programlisting><![CDATA[ +lib.attrsets.recursiveUpdateUntil (path: l: r: path == ["foo"]) + { + # first attribute set + foo.bar = 1; + foo.baz = 2; + bar = 3; + } + { + #second attribute set + foo.bar = 1; + foo.quz = 2; + baz = 4; + } +=> { + foo.bar = 1; # 'foo.*' from the second set + foo.quz = 2; # + bar = 3; # 'bar' from the first set + baz = 4; # 'baz' from the second set +} + ]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.recursiveUpdate"> + <title><function>lib.attrsets.recursiveUpdate</function></title> + + <subtitle><literal>recursiveUpdate :: AttrSet -> AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.recursiveUpdate" /> + + <para> + A recursive variant of the update operator <literal>//</literal>. The recursion stops when one of the attribute values is not an attribute set, in which case the right hand side value takes precedence over the left hand side value. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>lhs</varname> + </term> + <listitem> + <para> + The left hand attribute set of the merge. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <varname>rhs</varname> + </term> + <listitem> + <para> + The right hand attribute set of the merge. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.recursiveUpdate-example"> + <title>Recursively merging two attribute sets</title> +<programlisting><![CDATA[ +recursiveUpdate + { + boot.loader.grub.enable = true; + boot.loader.grub.device = "/dev/hda"; + } + { + boot.loader.grub.device = ""; + } +=> { + boot.loader.grub.enable = true; + boot.loader.grub.device = ""; +} +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.recurseIntoAttrs"> + <title><function>lib.attrsets.recurseIntoAttrs</function></title> + + <subtitle><literal>recurseIntoAttrs :: AttrSet -> AttrSet</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.recurseIntoAttrs" /> + + <para> + Make various Nix tools consider the contents of the resulting attribute set when looking for what to build, find, etc. + </para> + + <para> + This function only affects a single attribute set; it does not apply itself recursively for nested attribute sets. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>attrs</varname> + </term> + <listitem> + <para> + An attribute set to scan for derivations. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.recurseIntoAttrs-example"> + <title>Making Nix look inside an attribute set</title> +<programlisting><![CDATA[ +{ pkgs ? import <nixpkgs> {} }: +{ + myTools = pkgs.lib.recurseIntoAttrs { + inherit (pkgs) hello figlet; + }; +} +]]></programlisting> + </example> + </section> + + <section xml:id="function-library-lib.attrsets.cartesianProductOfSets"> + <title><function>lib.attrsets.cartesianProductOfSets</function></title> + + <subtitle><literal>cartesianProductOfSets :: AttrSet -> [ AttrSet ]</literal> + </subtitle> + + <xi:include href="./locations.xml" xpointer="lib.attrsets.cartesianProductOfSets" /> + + <para> + Return the cartesian product of attribute set value combinations. + </para> + + <variablelist> + <varlistentry> + <term> + <varname>set</varname> + </term> + <listitem> + <para> + An attribute set with attributes that carry lists of values. + </para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="function-library-lib.attrsets.cartesianProductOfSets-example"> + <title>Creating the cartesian product of a list of attribute values</title> +<programlisting><![CDATA[ +cartesianProductOfSets { a = [ 1 2 ]; b = [ 10 20 ]; } +=> [ + { a = 1; b = 10; } + { a = 1; b = 20; } + { a = 2; b = 10; } + { a = 2; b = 20; } + ] +]]></programlisting> + </example> + </section> +</section> diff --git a/doc/functions/nix-gitignore.section.md b/doc/functions/nix-gitignore.section.md new file mode 100644 index 00000000000..2fb833b2300 --- /dev/null +++ b/doc/functions/nix-gitignore.section.md @@ -0,0 +1,49 @@ +# pkgs.nix-gitignore {#sec-pkgs-nix-gitignore} + +`pkgs.nix-gitignore` is a function that acts similarly to `builtins.filterSource` but also allows filtering with the help of the gitignore format. + +## Usage {#sec-pkgs-nix-gitignore-usage} + +`pkgs.nix-gitignore` exports a number of functions, but you\'ll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string. + +```nix +{ pkgs ? import <nixpkgs> {} }: + + nix-gitignore.gitignoreSource [] ./source + # Simplest version + + nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source + # This one reads the ./source/.gitignore and concats the auxiliary ignores + + nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source + # Use this string as gitignore, don't read ./source/.gitignore. + + nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n", ~/.gitignore] ./source + # It also accepts a list (of strings and paths) that will be concatenated + # once the paths are turned to strings via readFile. +``` + +These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`: + +```nix +gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true); +gitignoreSource = gitignoreFilterSource (_: _: true); +``` + +Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it\'s blacklisted by either your filter or the gitignoreFilter. + +If you want to make your own filter from scratch, you may use + +```nix +gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root; +``` + +## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive} + +If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function: + +```nix +gitignoreFilterRecursiveSource = filter: patterns: root: +# OR +gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true); +``` diff --git a/doc/functions/prefer-remote-fetch.section.md b/doc/functions/prefer-remote-fetch.section.md new file mode 100644 index 00000000000..8760c100224 --- /dev/null +++ b/doc/functions/prefer-remote-fetch.section.md @@ -0,0 +1,17 @@ +# prefer-remote-fetch overlay {#sec-prefer-remote-fetch} + +`prefer-remote-fetch` is an overlay that download sources on remote builder. This is useful when the evaluating machine has a slow upload while the builder can fetch faster directly from the source. To use it, put the following snippet as a new overlay: + +```nix +self: super: + (super.prefer-remote-fetch self super) +``` + +A full configuration example for that sets the overlay up for your own account, could look like this + +```ShellSession +$ mkdir ~/.config/nixpkgs/overlays/ +$ cat > ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix <<EOF + self: super: super.prefer-remote-fetch self super +EOF +``` |