diff options
Diffstat (limited to 'doc/functions/library/attrsets.xml')
-rw-r--r-- | doc/functions/library/attrsets.xml | 970 |
1 files changed, 970 insertions, 0 deletions
diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml new file mode 100644 index 000000000000..6f23e267bab2 --- /dev/null +++ b/doc/functions/library/attrsets.xml @@ -0,0 +1,970 @@ +<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</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> + </section> +</section> |