<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 [](#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>zipAttrsWith :: [ 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 [](#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>