mirror of
https://github.com/CHN-beta/nixpkgs.git
synced 2026-01-12 02:40:31 +08:00
nixpkgs: Start documenting library functions in XML
Covers assert functions and about half of the attrsets functions.
Some internal consistency around IDs could be improved.
(cherry picked from commit f835f77e02)
This commit is contained in:
Graham Christensen
@@ -69,7 +69,7 @@ highlightjs:
|
||||
cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/
|
||||
|
||||
|
||||
manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml
|
||||
manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml **/**/*.xml
|
||||
xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
|
||||
|
||||
.version:
|
||||
|
||||
@@ -7,6 +7,8 @@
|
||||
The nixpkgs repository has several utility functions to manipulate Nix
|
||||
expressions.
|
||||
</para>
|
||||
|
||||
<xi:include href="functions/library.xml" />
|
||||
<xi:include href="functions/overrides.xml" />
|
||||
<xi:include href="functions/generators.xml" />
|
||||
<xi:include href="functions/debug.xml" />
|
||||
|
||||
15
doc/functions/library.xml
Normal file
15
doc/functions/library.xml
Normal file
@@ -0,0 +1,15 @@
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xml:id="sec-functions-library">
|
||||
<title>Nixpkgs Library Functions</title>
|
||||
|
||||
<para>
|
||||
Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or
|
||||
through <code>import <nixpkgs/lib></code>.
|
||||
</para>
|
||||
|
||||
<xi:include href="./library/asserts.xml" />
|
||||
|
||||
<xi:include href="./library/attrsets.xml" />
|
||||
</section>
|
||||
113
doc/functions/library/asserts.xml
Normal file
113
doc/functions/library/asserts.xml
Normal file
@@ -0,0 +1,113 @@
|
||||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xml:id="sec-functions-library-asserts">
|
||||
<title>Assert functions</title>
|
||||
|
||||
<section xml:id="function-library-lib.asserts.assertMsg">
|
||||
<title><function>lib.asserts.assertMsg</function></title>
|
||||
|
||||
<subtitle><literal>assertMsg :: Bool -> String -> Bool</literal>
|
||||
</subtitle>
|
||||
|
||||
<para>
|
||||
Print a trace message if <literal>pred</literal> is false.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Intended to be used to augment asserts with helpful error messages.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>pred</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Condition under which the <varname>msg</varname> should
|
||||
<emphasis>not</emphasis> be printed.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>msg</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Message to print.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<example xml:id="function-library-lib.asserts.assertMsg-example-false">
|
||||
<title>Printing when the predicate is false</title>
|
||||
<programlisting><![CDATA[
|
||||
assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly"
|
||||
stderr> trace: foo is not bar, silly
|
||||
stderr> assert failed
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</section>
|
||||
|
||||
<section xml:id="function-library-lib.asserts.assertOneOf">
|
||||
<title><function>lib.asserts.assertOneOf</function></title>
|
||||
|
||||
<subtitle><literal>assertOneOf :: String -> String ->
|
||||
StringList -> Bool</literal>
|
||||
</subtitle>
|
||||
|
||||
<para>
|
||||
Specialized <function>asserts.assertMsg</function> for checking if
|
||||
<varname>val</varname> is one of the elements of <varname>xs</varname>.
|
||||
Useful for checking enums.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>name</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The name of the variable the user entered <varname>val</varname> into,
|
||||
for inclusion in the error message.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>val</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The value of what the user provided, to be compared against the values in
|
||||
<varname>xs</varname>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<varname>xs</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The list of valid values.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<example xml:id="function-library-lib.asserts.assertOneOf-example">
|
||||
<title>Ensuring a user provided a possible value</title>
|
||||
<programlisting><![CDATA[
|
||||
let sslLibrary = "bearssl";
|
||||
in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "bearssl" ];
|
||||
=> false
|
||||
stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</section>
|
||||
</section>
|
||||
938
doc/functions/library/attrsets.xml
Normal file
938
doc/functions/library/attrsets.xml
Normal file
@@ -0,0 +1,938 @@
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
|
||||
<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>
|
||||
Reference in New Issue
Block a user