nixpkgs/doc/functions/library/attrsets.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&apos;</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>