1754 lines
45 KiB
XML
1754 lines
45 KiB
XML
<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>
|
|
|
|
<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 <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>
|