pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 xml:id="sec-functions-library-attrset">
5 <title>Attribute-Set Functions</title>
6
7 <section xml:id="function-library-lib.attrsets.attrByPath">
8 <title><function>lib.attrset.attrByPath</function></title>
9
10 <subtitle><literal>attrByPath :: [String] -> Any -> AttrSet -> Any</literal>
11 </subtitle>
12
13 <xi:include href="./locations.xml" xpointer="lib.attrsets.attrByPath" />
14
15 <para>
16 Return an attribute from within nested attribute sets.
17 </para>
18
19 <variablelist>
20 <varlistentry>
21 <term>
22 <varname>attrPath</varname>
23 </term>
24 <listitem>
25 <para>
26 A list of strings representing the path through the nested attribute set <varname>set</varname>.
27 </para>
28 </listitem>
29 </varlistentry>
30 <varlistentry>
31 <term>
32 <varname>default</varname>
33 </term>
34 <listitem>
35 <para>
36 Default value if <varname>attrPath</varname> does not resolve to an existing value.
37 </para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term>
42 <varname>set</varname>
43 </term>
44 <listitem>
45 <para>
46 The nested attributeset to select values from.
47 </para>
48 </listitem>
49 </varlistentry>
50 </variablelist>
51
52 <example xml:id="function-library-lib.attrset.attrByPath-example-value-exists">
53 <title>Extracting a value from a nested attribute set</title>
54<programlisting><![CDATA[
55let set = { a = { b = 3; }; };
56in lib.attrsets.attrByPath [ "a" "b" ] 0 set
57=> 3
58]]></programlisting>
59 </example>
60
61 <example xml:id="function-library-lib.attrset.attrByPath-example-default-value">
62 <title>No value at the path, instead using the default</title>
63<programlisting><![CDATA[
64lib.attrsets.attrByPath [ "a" "b" ] 0 {}
65=> 0
66]]></programlisting>
67 </example>
68 </section>
69
70 <section xml:id="function-library-lib.attrsets.hasAttrByPath">
71 <title><function>lib.attrsets.hasAttrByPath</function></title>
72
73 <subtitle><literal>hasAttrByPath :: [String] -> AttrSet -> Bool</literal>
74 </subtitle>
75
76 <xi:include href="./locations.xml" xpointer="lib.attrsets.hasAttrByPath" />
77
78 <para>
79 Determine if an attribute exists within a nested attribute set.
80 </para>
81
82 <variablelist>
83 <varlistentry>
84 <term>
85 <varname>attrPath</varname>
86 </term>
87 <listitem>
88 <para>
89 A list of strings representing the path through the nested attribute set <varname>set</varname>.
90 </para>
91 </listitem>
92 </varlistentry>
93 <varlistentry>
94 <term>
95 <varname>set</varname>
96 </term>
97 <listitem>
98 <para>
99 The nested attributeset to check.
100 </para>
101 </listitem>
102 </varlistentry>
103 </variablelist>
104
105 <example xml:id="function-library-lib.attrsets.hasAttrByPath-example">
106 <title>A nested value does exist inside a set</title>
107<programlisting><![CDATA[
108lib.attrsets.hasAttrByPath
109 [ "a" "b" "c" "d" ]
110 { a = { b = { c = { d = 123; }; }; }; }
111=> true
112]]></programlisting>
113 </example>
114 </section>
115
116 <section xml:id="function-library-lib.attrsets.setAttrByPath">
117 <title><function>lib.attrsets.setAttrByPath</function></title>
118
119 <subtitle><literal>setAttrByPath :: [String] -> Any -> AttrSet</literal>
120 </subtitle>
121
122 <xi:include href="./locations.xml" xpointer="lib.attrsets.setAttrByPath" />
123
124 <para>
125 Create a new attribute set with <varname>value</varname> set at the nested attribute location specified in <varname>attrPath</varname>.
126 </para>
127
128 <variablelist>
129 <varlistentry>
130 <term>
131 <varname>attrPath</varname>
132 </term>
133 <listitem>
134 <para>
135 A list of strings representing the path through the nested attribute set.
136 </para>
137 </listitem>
138 </varlistentry>
139 <varlistentry>
140 <term>
141 <varname>value</varname>
142 </term>
143 <listitem>
144 <para>
145 The value to set at the location described by <varname>attrPath</varname>.
146 </para>
147 </listitem>
148 </varlistentry>
149 </variablelist>
150
151 <example xml:id="function-library-lib.attrsets.setAttrByPath-example">
152 <title>Creating a new nested attribute set</title>
153<programlisting><![CDATA[
154lib.attrsets.setAttrByPath [ "a" "b" ] 3
155=> { a = { b = 3; }; }
156]]></programlisting>
157 </example>
158 </section>
159
160 <section xml:id="function-library-lib.attrsets.getAttrFromPath">
161 <title><function>lib.attrsets.getAttrFromPath</function></title>
162
163 <subtitle><literal>getAttrFromPath :: [String] -> AttrSet -> Value</literal>
164 </subtitle>
165
166 <xi:include href="./locations.xml" xpointer="lib.attrsets.getAttrFromPath" />
167
168 <para>
169 Like <xref linkend="function-library-lib.attrsets.attrByPath" /> except without a default, and it will throw if the value doesn't exist.
170 </para>
171
172 <variablelist>
173 <varlistentry>
174 <term>
175 <varname>attrPath</varname>
176 </term>
177 <listitem>
178 <para>
179 A list of strings representing the path through the nested attribute set <varname>set</varname>.
180 </para>
181 </listitem>
182 </varlistentry>
183 <varlistentry>
184 <term>
185 <varname>set</varname>
186 </term>
187 <listitem>
188 <para>
189 The nested attribute set to find the value in.
190 </para>
191 </listitem>
192 </varlistentry>
193 </variablelist>
194
195 <example xml:id="function-library-lib.attrsets.getAttrPath-example-success">
196 <title>Succesfully getting a value from an attribute set</title>
197<programlisting><![CDATA[
198lib.attrsets.getAttrFromPath [ "a" "b" ] { a = { b = 3; }; }
199=> 3
200]]></programlisting>
201 </example>
202
203 <example xml:id="function-library-lib.attrsets.getAttrPath-example-throw">
204 <title>Throwing after failing to get a value from an attribute set</title>
205<programlisting><![CDATA[
206lib.attrsets.getAttrFromPath [ "x" "y" ] { }
207=> error: cannot find attribute `x.y'
208]]></programlisting>
209 </example>
210 </section>
211
212 <section xml:id="function-library-lib.attrsets.attrVals">
213 <title><function>lib.attrsets.attrVals</function></title>
214
215 <subtitle><literal>attrVals :: [String] -> AttrSet -> [Any]</literal>
216 </subtitle>
217
218 <xi:include href="./locations.xml" xpointer="lib.attrsets.attrVals" />
219
220 <para>
221 Return the specified attributes from a set. All values must exist.
222 </para>
223
224 <variablelist>
225 <varlistentry>
226 <term>
227 <varname>nameList</varname>
228 </term>
229 <listitem>
230 <para>
231 The list of attributes to fetch from <varname>set</varname>. Each attribute name must exist on the attrbitue set.
232 </para>
233 </listitem>
234 </varlistentry>
235 <varlistentry>
236 <term>
237 <varname>set</varname>
238 </term>
239 <listitem>
240 <para>
241 The set to get attribute values from.
242 </para>
243 </listitem>
244 </varlistentry>
245 </variablelist>
246
247 <example xml:id="function-library-lib.attrsets.attrVals-example-success">
248 <title>Getting several values from an attribute set</title>
249<programlisting><![CDATA[
250lib.attrsets.attrVals [ "a" "b" "c" ] { a = 1; b = 2; c = 3; }
251=> [ 1 2 3 ]
252]]></programlisting>
253 </example>
254
255 <example xml:id="function-library-lib.attrsets.attrVals-failure">
256 <title>Getting missing values from an attribute set</title>
257<programlisting><![CDATA[
258lib.attrsets.attrVals [ "d" ] { }
259error: attribute 'd' missing
260]]></programlisting>
261 </example>
262 </section>
263
264 <section xml:id="function-library-lib.attrsets.attrValues">
265 <title><function>lib.attrsets.attrValues</function></title>
266
267 <subtitle><literal>attrValues :: AttrSet -> [Any]</literal>
268 </subtitle>
269
270 <xi:include href="./locations.xml" xpointer="lib.attrsets.attrValues" />
271
272 <para>
273 Get all the attribute values from an attribute set.
274 </para>
275
276 <para>
277 Provides a backwards-compatible interface of <function>builtins.attrValues</function> for Nix version older than 1.8.
278 </para>
279
280 <variablelist>
281 <varlistentry>
282 <term>
283 <varname>attrs</varname>
284 </term>
285 <listitem>
286 <para>
287 The attribute set.
288 </para>
289 </listitem>
290 </varlistentry>
291 </variablelist>
292
293 <example xml:id="function-library-lib.attrsets.attrValues-example">
294 <title></title>
295<programlisting><![CDATA[
296lib.attrsets.attrValues { a = 1; b = 2; c = 3; }
297=> [ 1 2 3 ]
298]]></programlisting>
299 </example>
300 </section>
301
302 <section xml:id="function-library-lib.attrsets.catAttrs">
303 <title><function>lib.attrsets.catAttrs</function></title>
304
305 <subtitle><literal>catAttrs :: String -> [AttrSet] -> [Any]</literal>
306 </subtitle>
307
308 <xi:include href="./locations.xml" xpointer="lib.attrsets.catAttrs" />
309
310 <para>
311 Collect each attribute named `attr' from the list of attribute sets, <varname>sets</varname>. Sets that don't contain the named attribute are ignored.
312 </para>
313
314 <para>
315 Provides a backwards-compatible interface of <function>builtins.catAttrs</function> for Nix version older than 1.9.
316 </para>
317
318 <variablelist>
319 <varlistentry>
320 <term>
321 <varname>attr</varname>
322 </term>
323 <listitem>
324 <para>
325 Attribute name to select from each attribute set in <varname>sets</varname>.
326 </para>
327 </listitem>
328 </varlistentry>
329 <varlistentry>
330 <term>
331 <varname>sets</varname>
332 </term>
333 <listitem>
334 <para>
335 The list of attribute sets to select <varname>attr</varname> from.
336 </para>
337 </listitem>
338 </varlistentry>
339 </variablelist>
340
341 <example xml:id="function-library-lib.attrsets.catAttrs-example">
342 <title>Collect an attribute from a list of attribute sets.</title>
343 <para>
344 Attribute sets which don't have the attribute are ignored.
345 </para>
346<programlisting><![CDATA[
347catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
348=> [ 1 2 ]
349 ]]></programlisting>
350 </example>
351 </section>
352
353 <section xml:id="function-library-lib.attrsets.filterAttrs">
354 <title><function>lib.attrsets.filterAttrs</function></title>
355
356 <subtitle><literal>filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal>
357 </subtitle>
358
359 <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrs" />
360
361 <para>
362 Filter an attribute set by removing all attributes for which the given predicate return false.
363 </para>
364
365 <variablelist>
366 <varlistentry>
367 <term>
368 <varname>pred</varname>
369 </term>
370 <listitem>
371 <para>
372 <literal>String -> Any -> Bool</literal>
373 </para>
374 <para>
375 Predicate which returns true to include an attribute, or returns false to exclude it.
376 </para>
377 <variablelist>
378 <varlistentry>
379 <term>
380 <varname>name</varname>
381 </term>
382 <listitem>
383 <para>
384 The attribute's name
385 </para>
386 </listitem>
387 </varlistentry>
388 <varlistentry>
389 <term>
390 <varname>value</varname>
391 </term>
392 <listitem>
393 <para>
394 The attribute's value
395 </para>
396 </listitem>
397 </varlistentry>
398 </variablelist>
399 <para>
400 Returns <literal>true</literal> to include the attribute, <literal>false</literal> to exclude the attribute.
401 </para>
402 </listitem>
403 </varlistentry>
404 <varlistentry>
405 <term>
406 <varname>set</varname>
407 </term>
408 <listitem>
409 <para>
410 The attribute set to filter
411 </para>
412 </listitem>
413 </varlistentry>
414 </variablelist>
415
416 <example xml:id="function-library-lib.attrsets.filterAttrs-example">
417 <title>Filtering an attributeset</title>
418<programlisting><![CDATA[
419filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; }
420=> { foo = 1; }
421]]></programlisting>
422 </example>
423 </section>
424
425 <section xml:id="function-library-lib.attrsets.filterAttrsRecursive">
426 <title><function>lib.attrsets.filterAttrsRecursive</function></title>
427
428 <subtitle><literal>filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal>
429 </subtitle>
430
431 <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrsRecursive" />
432
433 <para>
434 Filter an attribute set recursively by removing all attributes for which the given predicate return false.
435 </para>
436
437 <variablelist>
438 <varlistentry>
439 <term>
440 <varname>pred</varname>
441 </term>
442 <listitem>
443 <para>
444 <literal>String -> Any -> Bool</literal>
445 </para>
446 <para>
447 Predicate which returns true to include an attribute, or returns false to exclude it.
448 </para>
449 <variablelist>
450 <varlistentry>
451 <term>
452 <varname>name</varname>
453 </term>
454 <listitem>
455 <para>
456 The attribute's name
457 </para>
458 </listitem>
459 </varlistentry>
460 <varlistentry>
461 <term>
462 <varname>value</varname>
463 </term>
464 <listitem>
465 <para>
466 The attribute's value
467 </para>
468 </listitem>
469 </varlistentry>
470 </variablelist>
471 <para>
472 Returns <literal>true</literal> to include the attribute, <literal>false</literal> to exclude the attribute.
473 </para>
474 </listitem>
475 </varlistentry>
476 <varlistentry>
477 <term>
478 <varname>set</varname>
479 </term>
480 <listitem>
481 <para>
482 The attribute set to filter
483 </para>
484 </listitem>
485 </varlistentry>
486 </variablelist>
487
488 <example xml:id="function-library-lib.attrsets.filterAttrsRecursive-example">
489 <title>Recursively filtering an attribute set</title>
490<programlisting><![CDATA[
491lib.attrsets.filterAttrsRecursive
492 (n: v: v != null)
493 {
494 levelA = {
495 example = "hi";
496 levelB = {
497 hello = "there";
498 this-one-is-present = {
499 this-is-excluded = null;
500 };
501 };
502 this-one-is-also-excluded = null;
503 };
504 also-excluded = null;
505 }
506=> {
507 levelA = {
508 example = "hi";
509 levelB = {
510 hello = "there";
511 this-one-is-present = { };
512 };
513 };
514 }
515 ]]></programlisting>
516 </example>
517 </section>
518
519 <section xml:id="function-library-lib.attrsets.foldAttrs">
520 <title><function>lib.attrsets.foldAttrs</function></title>
521
522 <subtitle><literal>foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any</literal>
523 </subtitle>
524
525 <xi:include href="./locations.xml" xpointer="lib.attrsets.foldAttrs" />
526
527 <para>
528 Apply fold function to values grouped by key.
529 </para>
530
531 <variablelist>
532 <varlistentry>
533 <term>
534 <varname>op</varname>
535 </term>
536 <listitem>
537 <para>
538 <literal>Any -> Any -> Any</literal>
539 </para>
540 <para>
541 Given a value <varname>val</varname> and a collector <varname>col</varname>, combine the two.
542 </para>
543 <variablelist>
544 <varlistentry>
545 <term>
546 <varname>val</varname>
547 </term>
548 <listitem>
549 <para>
550 An attribute's value
551 </para>
552 </listitem>
553 </varlistentry>
554 <varlistentry>
555 <term>
556 <varname>col</varname>
557 </term>
558 <listitem>
559<!-- TODO: make this not bad, use more fold-ey terms -->
560 <para>
561 The result of previous <function>op</function> calls with other values and <function>nul</function>.
562 </para>
563 </listitem>
564 </varlistentry>
565 </variablelist>
566 </listitem>
567 </varlistentry>
568 <varlistentry>
569 <term>
570 <varname>nul</varname>
571 </term>
572 <listitem>
573 <para>
574 The null-value, the starting value.
575 </para>
576 </listitem>
577 </varlistentry>
578 <varlistentry>
579 <term>
580 <varname>list_of_attrs</varname>
581 </term>
582 <listitem>
583 <para>
584 A list of attribute sets to fold together by key.
585 </para>
586 </listitem>
587 </varlistentry>
588 </variablelist>
589
590 <example xml:id="function-library-lib.attrsets.foldAttrs-example">
591 <title>Combining an attribute of lists in to one attribute set</title>
592<programlisting><![CDATA[
593lib.attrsets.foldAttrs
594 (n: a: [n] ++ a) []
595 [
596 { a = 2; b = 7; }
597 { a = 3; }
598 { b = 6; }
599 ]
600=> { a = [ 2 3 ]; b = [ 7 6 ]; }
601]]></programlisting>
602 </example>
603 </section>
604
605 <section xml:id="function-library-lib.attrsets.collect">
606 <title><function>lib.attrsets.collect</function></title>
607
608 <subtitle><literal>collect :: (Any -> Bool) -> AttrSet -> [Any]</literal>
609 </subtitle>
610
611 <xi:include href="./locations.xml" xpointer="lib.attrsets.collect" />
612
613 <para>
614 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>.
615 </para>
616
617 <variablelist>
618 <varlistentry>
619 <term>
620 <varname>pred</varname>
621 </term>
622 <listitem>
623 <para>
624 <literal>Any -> Bool</literal>
625 </para>
626 <para>
627 Given an attribute's value, determine if recursion should stop.
628 </para>
629 <variablelist>
630 <varlistentry>
631 <term>
632 <varname>value</varname>
633 </term>
634 <listitem>
635 <para>
636 The attribute set value.
637 </para>
638 </listitem>
639 </varlistentry>
640 </variablelist>
641 </listitem>
642 </varlistentry>
643 <varlistentry>
644 <term>
645 <varname>attrs</varname>
646 </term>
647 <listitem>
648 <para>
649 The attribute set to recursively collect.
650 </para>
651 </listitem>
652 </varlistentry>
653 </variablelist>
654
655 <example xml:id="function-library-lib.attrsets.collect-example-lists">
656 <title>Collecting all lists from an attribute set</title>
657<programlisting><![CDATA[
658lib.attrsets.collect isList { a = { b = ["b"]; }; c = [1]; }
659=> [["b"] [1]]
660]]></programlisting>
661 </example>
662
663 <example xml:id="function-library-lib.attrsets.collect-example-outpath">
664 <title>Collecting all attribute-sets which contain the <literal>outPath</literal> attribute name.</title>
665<programlisting><![CDATA[
666collect (x: x ? outPath)
667 { a = { outPath = "a/"; }; b = { outPath = "b/"; }; }
668=> [{ outPath = "a/"; } { outPath = "b/"; }]
669]]></programlisting>
670 </example>
671 </section>
672
673 <section xml:id="function-library-lib.attrsets.nameValuePair">
674 <title><function>lib.attrsets.nameValuePair</function></title>
675
676 <subtitle><literal>nameValuePair :: String -> Any -> AttrSet</literal>
677 </subtitle>
678
679 <xi:include href="./locations.xml" xpointer="lib.attrsets.nameValuePair" />
680
681 <para>
682 Utility function that creates a <literal>{name, value}</literal> pair as expected by <function>builtins.listToAttrs</function>.
683 </para>
684
685 <variablelist>
686 <varlistentry>
687 <term>
688 <varname>name</varname>
689 </term>
690 <listitem>
691 <para>
692 The attribute name.
693 </para>
694 </listitem>
695 </varlistentry>
696 <varlistentry>
697 <term>
698 <varname>value</varname>
699 </term>
700 <listitem>
701 <para>
702 The attribute value.
703 </para>
704 </listitem>
705 </varlistentry>
706 </variablelist>
707
708 <example xml:id="function-library-lib.attrsets.nameValuePair-example">
709 <title>Creating a name value pair</title>
710<programlisting><![CDATA[
711nameValuePair "some" 6
712=> { name = "some"; value = 6; }
713]]></programlisting>
714 </example>
715 </section>
716
717 <section xml:id="function-library-lib.attrsets.mapAttrs">
718 <title><function>lib.attrsets.mapAttrs</function></title>
719
720 <subtitle><literal></literal>
721 </subtitle>
722
723 <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs" />
724
725 <para>
726 Apply a function to each element in an attribute set, creating a new attribute set.
727 </para>
728
729 <para>
730 Provides a backwards-compatible interface of <function>builtins.mapAttrs</function> for Nix version older than 2.1.
731 </para>
732
733 <variablelist>
734 <varlistentry>
735 <term>
736 <varname>fn</varname>
737 </term>
738 <listitem>
739 <para>
740 <literal>String -> Any -> Any</literal>
741 </para>
742 <para>
743 Given an attribute's name and value, return a new value.
744 </para>
745 <variablelist>
746 <varlistentry>
747 <term>
748 <varname>name</varname>
749 </term>
750 <listitem>
751 <para>
752 The name of the attribute.
753 </para>
754 </listitem>
755 </varlistentry>
756 <varlistentry>
757 <term>
758 <varname>value</varname>
759 </term>
760 <listitem>
761 <para>
762 The attribute's value.
763 </para>
764 </listitem>
765 </varlistentry>
766 </variablelist>
767 </listitem>
768 </varlistentry>
769 </variablelist>
770
771 <example xml:id="function-library-lib.attrsets.mapAttrs-example">
772 <title>Modifying each value of an attribute set</title>
773<programlisting><![CDATA[
774lib.attrsets.mapAttrs
775 (name: value: name + "-" + value)
776 { x = "foo"; y = "bar"; }
777=> { x = "x-foo"; y = "y-bar"; }
778]]></programlisting>
779 </example>
780 </section>
781
782 <section xml:id="function-library-lib.attrsets.mapAttrs-prime">
783 <title><function>lib.attrsets.mapAttrs'</function></title>
784
785 <subtitle><literal>mapAttrs' :: (String -> Any -> { name = String; value = Any }) -> AttrSet -> AttrSet</literal>
786 </subtitle>
787
788 <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs-prime" />
789
790 <para>
791 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>.
792 </para>
793
794 <variablelist>
795 <varlistentry>
796 <term>
797 <varname>fn</varname>
798 </term>
799 <listitem>
800 <para>
801 <literal>String -> Any -> { name = String; value = Any }</literal>
802 </para>
803 <para>
804 Given an attribute's name and value, return a new <link
805 linkend="function-library-lib.attrsets.nameValuePair">name value pair</link>.
806 </para>
807 <variablelist>
808 <varlistentry>
809 <term>
810 <varname>name</varname>
811 </term>
812 <listitem>
813 <para>
814 The name of the attribute.
815 </para>
816 </listitem>
817 </varlistentry>
818 <varlistentry>
819 <term>
820 <varname>value</varname>
821 </term>
822 <listitem>
823 <para>
824 The attribute's value.
825 </para>
826 </listitem>
827 </varlistentry>
828 </variablelist>
829 </listitem>
830 </varlistentry>
831 <varlistentry>
832 <term>
833 <varname>set</varname>
834 </term>
835 <listitem>
836 <para>
837 The attribute set to map over.
838 </para>
839 </listitem>
840 </varlistentry>
841 </variablelist>
842
843 <example xml:id="function-library-lib.attrsets.mapAttrs-prime-example">
844 <title>Change the name and value of each attribute of an attribute set</title>
845<programlisting><![CDATA[
846lib.attrsets.mapAttrs' (name: value: lib.attrsets.nameValuePair ("foo_" + name) ("bar-" + value))
847 { x = "a"; y = "b"; }
848=> { foo_x = "bar-a"; foo_y = "bar-b"; }
849
850 ]]></programlisting>
851 </example>
852 </section>
853
854 <section xml:id="function-library-lib.attrsets.mapAttrsToList">
855 <title><function>lib.attrsets.mapAttrsToList</function></title>
856
857 <subtitle><literal>mapAttrsToList :: (String -> Any -> Any) ->
858 AttrSet -> [Any]</literal>
859 </subtitle>
860
861 <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsToList" />
862
863 <para>
864 Call <varname>fn</varname> for each attribute in the given <varname>set</varname> and return the result in a list.
865 </para>
866
867 <variablelist>
868 <varlistentry>
869 <term>
870 <varname>fn</varname>
871 </term>
872 <listitem>
873 <para>
874 <literal>String -> Any -> Any</literal>
875 </para>
876 <para>
877 Given an attribute's name and value, return a new value.
878 </para>
879 <variablelist>
880 <varlistentry>
881 <term>
882 <varname>name</varname>
883 </term>
884 <listitem>
885 <para>
886 The name of the attribute.
887 </para>
888 </listitem>
889 </varlistentry>
890 <varlistentry>
891 <term>
892 <varname>value</varname>
893 </term>
894 <listitem>
895 <para>
896 The attribute's value.
897 </para>
898 </listitem>
899 </varlistentry>
900 </variablelist>
901 </listitem>
902 </varlistentry>
903 <varlistentry>
904 <term>
905 <varname>set</varname>
906 </term>
907 <listitem>
908 <para>
909 The attribute set to map over.
910 </para>
911 </listitem>
912 </varlistentry>
913 </variablelist>
914
915 <example xml:id="function-library-lib.attrsets.mapAttrsToList-example">
916 <title>Combine attribute values and names in to a list</title>
917<programlisting><![CDATA[
918lib.attrsets.mapAttrsToList (name: value: "${name}=${value}")
919 { x = "a"; y = "b"; }
920=> [ "x=a" "y=b" ]
921]]></programlisting>
922 </example>
923 </section>
924
925 <section xml:id="function-library-lib.attrsets.mapAttrsRecursive">
926 <title><function>lib.attrsets.mapAttrsRecursive</function></title>
927
928 <subtitle><literal>mapAttrsRecursive :: ([String] > Any -> Any) -> AttrSet -> AttrSet</literal>
929 </subtitle>
930
931 <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsRecursive" />
932
933 <para>
934 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.
935 </para>
936
937 <variablelist>
938 <varlistentry>
939 <term>
940 <varname>f</varname>
941 </term>
942 <listitem>
943 <para>
944 <literal>[ String ] -> Any -> Any</literal>
945 </para>
946 <para>
947 Given a list of attribute names and value, return a new value.
948 </para>
949 <variablelist>
950 <varlistentry>
951 <term>
952 <varname>name_path</varname>
953 </term>
954 <listitem>
955 <para>
956 The list of attribute names to this value.
957 </para>
958 <para>
959 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>.
960 </para>
961 </listitem>
962 </varlistentry>
963 <varlistentry>
964 <term>
965 <varname>value</varname>
966 </term>
967 <listitem>
968 <para>
969 The attribute's value.
970 </para>
971 </listitem>
972 </varlistentry>
973 </variablelist>
974 </listitem>
975 </varlistentry>
976 <varlistentry>
977 <term>
978 <varname>set</varname>
979 </term>
980 <listitem>
981 <para>
982 The attribute set to recursively map over.
983 </para>
984 </listitem>
985 </varlistentry>
986 </variablelist>
987
988 <example xml:id="function-library-lib.attrsets.mapAttrsRecursive-example">
989 <title>A contrived example of using <function>lib.attrsets.mapAttrsRecursive</function></title>
990<programlisting><![CDATA[
991mapAttrsRecursive
992 (path: value: concatStringsSep "-" (path ++ [value]))
993 {
994 n = {
995 a = "A";
996 m = {
997 b = "B";
998 c = "C";
999 };
1000 };
1001 d = "D";
1002 }
1003=> {
1004 n = {
1005 a = "n-a-A";
1006 m = {
1007 b = "n-m-b-B";
1008 c = "n-m-c-C";
1009 };
1010 };
1011 d = "d-D";
1012 }
1013 ]]></programlisting>
1014 </example>
1015 </section>
1016
1017 <section xml:id="function-library-lib.attrsets.mapAttrsRecursiveCond">
1018 <title><function>lib.attrsets.mapAttrsRecursiveCond</function></title>
1019
1020 <subtitle><literal>mapAttrsRecursiveCond :: (AttrSet -> Bool) -> ([ String ] -> Any -> Any) -> AttrSet -> AttrSet</literal>
1021 </subtitle>
1022
1023 <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsRecursiveCond" />
1024
1025 <para>
1026 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.
1027 </para>
1028
1029 <variablelist>
1030 <varlistentry>
1031 <term>
1032 <varname>cond</varname>
1033 </term>
1034 <listitem>
1035 <para>
1036 <literal>(AttrSet -> Bool)</literal>
1037 </para>
1038 <para>
1039 Determine if <function>mapAttrsRecursive</function> should recurse deeper in to the attribute set.
1040 </para>
1041 <variablelist>
1042 <varlistentry>
1043 <term>
1044 <varname>attributeset</varname>
1045 </term>
1046 <listitem>
1047 <para>
1048 An attribute set.
1049 </para>
1050 </listitem>
1051 </varlistentry>
1052 </variablelist>
1053 </listitem>
1054 </varlistentry>
1055 <varlistentry>
1056 <term>
1057 <varname>f</varname>
1058 </term>
1059 <listitem>
1060 <para>
1061 <literal>[ String ] -> Any -> Any</literal>
1062 </para>
1063 <para>
1064 Given a list of attribute names and value, return a new value.
1065 </para>
1066 <variablelist>
1067 <varlistentry>
1068 <term>
1069 <varname>name_path</varname>
1070 </term>
1071 <listitem>
1072 <para>
1073 The list of attribute names to this value.
1074 </para>
1075 <para>
1076 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>.
1077 </para>
1078 </listitem>
1079 </varlistentry>
1080 <varlistentry>
1081 <term>
1082 <varname>value</varname>
1083 </term>
1084 <listitem>
1085 <para>
1086 The attribute's value.
1087 </para>
1088 </listitem>
1089 </varlistentry>
1090 </variablelist>
1091 </listitem>
1092 </varlistentry>
1093 <varlistentry>
1094 <term>
1095 <varname>set</varname>
1096 </term>
1097 <listitem>
1098 <para>
1099 The attribute set to recursively map over.
1100 </para>
1101 </listitem>
1102 </varlistentry>
1103 </variablelist>
1104
1105 <example xml:id="function-library-lib.attrsets.mapAttrsRecursiveCond-example">
1106 <title>Only convert attribute values to JSON if the containing attribute set is marked for recursion</title>
1107<programlisting><![CDATA[
1108lib.attrsets.mapAttrsRecursiveCond
1109 ({ recurse ? false, ... }: recurse)
1110 (name: value: builtins.toJSON value)
1111 {
1112 dorecur = {
1113 recurse = true;
1114 hello = "there";
1115 };
1116 dontrecur = {
1117 converted-to- = "json";
1118 };
1119 }
1120=> {
1121 dorecur = {
1122 hello = "\"there\"";
1123 recurse = "true";
1124 };
1125 dontrecur = "{\"converted-to\":\"json\"}";
1126 }
1127 ]]></programlisting>
1128 </example>
1129 </section>
1130
1131 <section xml:id="function-library-lib.attrsets.genAttrs">
1132 <title><function>lib.attrsets.genAttrs</function></title>
1133
1134 <subtitle><literal>genAttrs :: [ String ] -> (String -> Any) -> AttrSet</literal>
1135 </subtitle>
1136
1137 <xi:include href="./locations.xml" xpointer="lib.attrsets.genAttrs" />
1138
1139 <para>
1140 Generate an attribute set by mapping a function over a list of attribute names.
1141 </para>
1142
1143 <variablelist>
1144 <varlistentry>
1145 <term>
1146 <varname>names</varname>
1147 </term>
1148 <listitem>
1149 <para>
1150 Names of values in the resulting attribute set.
1151 </para>
1152 </listitem>
1153 </varlistentry>
1154 <varlistentry>
1155 <term>
1156 <varname>f</varname>
1157 </term>
1158 <listitem>
1159 <para>
1160 <literal>String -> Any</literal>
1161 </para>
1162 <para>
1163 Takes the name of the attribute and return the attribute's value.
1164 </para>
1165 <variablelist>
1166 <varlistentry>
1167 <term>
1168 <varname>name</varname>
1169 </term>
1170 <listitem>
1171 <para>
1172 The name of the attribute to generate a value for.
1173 </para>
1174 </listitem>
1175 </varlistentry>
1176 </variablelist>
1177 </listitem>
1178 </varlistentry>
1179 </variablelist>
1180
1181 <example xml:id="function-library-lib.attrsets.genAttrs-example">
1182 <title>Generate an attrset based on names only</title>
1183<programlisting><![CDATA[
1184lib.attrsets.genAttrs [ "foo" "bar" ] (name: "x_${name}")
1185=> { foo = "x_foo"; bar = "x_bar"; }
1186 ]]></programlisting>
1187 </example>
1188 </section>
1189
1190 <section xml:id="function-library-lib.attrsets.isDerivation">
1191 <title><function>lib.attrsets.isDerivation</function></title>
1192
1193 <subtitle><literal>isDerivation :: Any -> Bool</literal>
1194 </subtitle>
1195
1196 <xi:include href="./locations.xml" xpointer="lib.attrsets.isDerivation" />
1197
1198 <para>
1199 Check whether the argument is a derivation. Any set with <code>{ type = "derivation"; }</code> counts as a derivation.
1200 </para>
1201
1202 <variablelist>
1203 <varlistentry>
1204 <term>
1205 <varname>value</varname>
1206 </term>
1207 <listitem>
1208 <para>
1209 The value which is possibly a derivation.
1210 </para>
1211 </listitem>
1212 </varlistentry>
1213 </variablelist>
1214
1215 <example xml:id="function-library-lib.attrsets.isDerivation-example-true">
1216 <title>A package is a derivation</title>
1217<programlisting><![CDATA[
1218lib.attrsets.isDerivation (import <nixpkgs> {}).ruby
1219=> true
1220 ]]></programlisting>
1221 </example>
1222
1223 <example xml:id="function-library-lib.attrsets.isDerivation-example-false">
1224 <title>Anything else is not a derivation</title>
1225<programlisting><![CDATA[
1226lib.attrsets.isDerivation "foobar"
1227=> false
1228 ]]></programlisting>
1229 </example>
1230 </section>
1231
1232 <section xml:id="function-library-lib.attrsets.toDerivation">
1233 <title><function>lib.attrsets.toDerivation</function></title>
1234
1235 <subtitle><literal>toDerivation :: Path -> Derivation</literal>
1236 </subtitle>
1237
1238 <xi:include href="./locations.xml" xpointer="lib.attrsets.toDerivation" />
1239
1240 <para>
1241 Converts a store path to a fake derivation.
1242 </para>
1243
1244 <variablelist>
1245 <varlistentry>
1246 <term>
1247 <varname>path</varname>
1248 </term>
1249 <listitem>
1250 <para>
1251 A store path to convert to a derivation.
1252 </para>
1253 </listitem>
1254 </varlistentry>
1255 </variablelist>
1256 </section>
1257
1258 <section xml:id="function-library-lib.attrsets.optionalAttrs">
1259 <title><function>lib.attrsets.optionalAttrs</function></title>
1260
1261 <subtitle><literal>optionalAttrs :: Bool -> AttrSet</literal>
1262 </subtitle>
1263
1264 <xi:include href="./locations.xml" xpointer="lib.attrsets.optionalAttrs" />
1265
1266 <para>
1267 Conditionally return an attribute set or an empty attribute set.
1268 </para>
1269
1270 <variablelist>
1271 <varlistentry>
1272 <term>
1273 <varname>cond</varname>
1274 </term>
1275 <listitem>
1276 <para>
1277 Condition under which the <varname>as</varname> attribute set is returned.
1278 </para>
1279 </listitem>
1280 </varlistentry>
1281 <varlistentry>
1282 <term>
1283 <varname>as</varname>
1284 </term>
1285 <listitem>
1286 <para>
1287 The attribute set to return if <varname>cond</varname> is true.
1288 </para>
1289 </listitem>
1290 </varlistentry>
1291 </variablelist>
1292
1293 <example xml:id="function-library-lib.attrsets.optionalAttrs-example-true">
1294 <title>Return the provided attribute set when <varname>cond</varname> is true</title>
1295<programlisting><![CDATA[
1296lib.attrsets.optionalAttrs true { my = "set"; }
1297=> { my = "set"; }
1298 ]]></programlisting>
1299 </example>
1300
1301 <example xml:id="function-library-lib.attrsets.optionalAttrs-example-false">
1302 <title>Return an empty attribute set when <varname>cond</varname> is false</title>
1303<programlisting><![CDATA[
1304lib.attrsets.optionalAttrs false { my = "set"; }
1305=> { }
1306 ]]></programlisting>
1307 </example>
1308 </section>
1309
1310 <section xml:id="function-library-lib.attrsets.zipAttrsWithNames">
1311 <title><function>lib.attrsets.zipAttrsWithNames</function></title>
1312
1313 <subtitle><literal>zipAttrsWithNames :: [ String ] -> (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet</literal>
1314 </subtitle>
1315
1316 <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrsWithNames" />
1317
1318 <para>
1319 Merge sets of attributes and use the function <varname>f</varname> to merge attribute values where the attribute name is in <varname>names</varname>.
1320 </para>
1321
1322 <variablelist>
1323 <varlistentry>
1324 <term>
1325 <varname>names</varname>
1326 </term>
1327 <listitem>
1328 <para>
1329 A list of attribute names to zip.
1330 </para>
1331 </listitem>
1332 </varlistentry>
1333 <varlistentry>
1334 <term>
1335 <varname>f</varname>
1336 </term>
1337 <listitem>
1338 <para>
1339 <literal>(String -> [ Any ] -> Any</literal>
1340 </para>
1341 <para>
1342 Accepts an attribute name, all the values, and returns a combined value.
1343 </para>
1344 <variablelist>
1345 <varlistentry>
1346 <term>
1347 <varname>name</varname>
1348 </term>
1349 <listitem>
1350 <para>
1351 The name of the attribute each value came from.
1352 </para>
1353 </listitem>
1354 </varlistentry>
1355 <varlistentry>
1356 <term>
1357 <varname>vs</varname>
1358 </term>
1359 <listitem>
1360 <para>
1361 A list of values collected from the list of attribute sets.
1362 </para>
1363 </listitem>
1364 </varlistentry>
1365 </variablelist>
1366 </listitem>
1367 </varlistentry>
1368 <varlistentry>
1369 <term>
1370 <varname>sets</varname>
1371 </term>
1372 <listitem>
1373 <para>
1374 A list of attribute sets to zip together.
1375 </para>
1376 </listitem>
1377 </varlistentry>
1378 </variablelist>
1379
1380 <example xml:id="function-library-lib.attrsets.zipAttrsWithNames-example">
1381 <title>Summing a list of attribute sets of numbers</title>
1382<programlisting><![CDATA[
1383lib.attrsets.zipAttrsWithNames
1384 [ "a" "b" ]
1385 (name: vals: "${name} ${toString (builtins.foldl' (a: b: a + b) 0 vals)}")
1386 [
1387 { a = 1; b = 1; c = 1; }
1388 { a = 10; }
1389 { b = 100; }
1390 { c = 1000; }
1391 ]
1392=> { a = "a 11"; b = "b 101"; }
1393 ]]></programlisting>
1394 </example>
1395 </section>
1396
1397 <section xml:id="function-library-lib.attrsets.zipAttrsWith">
1398 <title><function>lib.attrsets.zipAttrsWith</function></title>
1399
1400 <subtitle><literal>zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet</literal>
1401 </subtitle>
1402
1403 <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrsWith" />
1404
1405 <para>
1406 Merge sets of attributes and use the function <varname>f</varname> to merge attribute values. Similar to <xref
1407 linkend="function-library-lib.attrsets.zipAttrsWithNames" /> where all key names are passed for <varname>names</varname>.
1408 </para>
1409
1410 <variablelist>
1411 <varlistentry>
1412 <term>
1413 <varname>f</varname>
1414 </term>
1415 <listitem>
1416 <para>
1417 <literal>(String -> [ Any ] -> Any</literal>
1418 </para>
1419 <para>
1420 Accepts an attribute name, all the values, and returns a combined value.
1421 </para>
1422 <variablelist>
1423 <varlistentry>
1424 <term>
1425 <varname>name</varname>
1426 </term>
1427 <listitem>
1428 <para>
1429 The name of the attribute each value came from.
1430 </para>
1431 </listitem>
1432 </varlistentry>
1433 <varlistentry>
1434 <term>
1435 <varname>vs</varname>
1436 </term>
1437 <listitem>
1438 <para>
1439 A list of values collected from the list of attribute sets.
1440 </para>
1441 </listitem>
1442 </varlistentry>
1443 </variablelist>
1444 </listitem>
1445 </varlistentry>
1446 <varlistentry>
1447 <term>
1448 <varname>sets</varname>
1449 </term>
1450 <listitem>
1451 <para>
1452 A list of attribute sets to zip together.
1453 </para>
1454 </listitem>
1455 </varlistentry>
1456 </variablelist>
1457
1458 <example xml:id="function-library-lib.attrsets.zipAttrsWith-example">
1459 <title>Summing a list of attribute sets of numbers</title>
1460<programlisting><![CDATA[
1461lib.attrsets.zipAttrsWith
1462 (name: vals: "${name} ${toString (builtins.foldl' (a: b: a + b) 0 vals)}")
1463 [
1464 { a = 1; b = 1; c = 1; }
1465 { a = 10; }
1466 { b = 100; }
1467 { c = 1000; }
1468 ]
1469=> { a = "a 11"; b = "b 101"; c = "c 1001"; }
1470 ]]></programlisting>
1471 </example>
1472 </section>
1473
1474 <section xml:id="function-library-lib.attrsets.zipAttrs">
1475 <title><function>lib.attrsets.zipAttrs</function></title>
1476
1477 <subtitle><literal>zipAttrsWith :: [ AttrSet ] -> AttrSet</literal>
1478 </subtitle>
1479
1480 <xi:include href="./locations.xml" xpointer="lib.attrsets.zipAttrs" />
1481
1482 <para>
1483 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.
1484 </para>
1485
1486 <variablelist>
1487 <varlistentry>
1488 <term>
1489 <varname>sets</varname>
1490 </term>
1491 <listitem>
1492 <para>
1493 A list of attribute sets to zip together.
1494 </para>
1495 </listitem>
1496 </varlistentry>
1497 </variablelist>
1498
1499 <example xml:id="function-library-lib.attrsets.zipAttrs-example">
1500 <title>Combining a list of attribute sets</title>
1501<programlisting><![CDATA[
1502lib.attrsets.zipAttrs
1503 [
1504 { a = 1; b = 1; c = 1; }
1505 { a = 10; }
1506 { b = 100; }
1507 { c = 1000; }
1508 ]
1509=> { a = [ 1 10 ]; b = [ 1 100 ]; c = [ 1 1000 ]; }
1510 ]]></programlisting>
1511 </example>
1512 </section>
1513
1514 <section xml:id="function-library-lib.attrsets.recursiveUpdateUntil">
1515 <title><function>lib.attrsets.recursiveUpdateUntil</function></title>
1516
1517 <subtitle><literal>recursiveUpdateUntil :: ( [ String ] -> AttrSet -> AttrSet -> Bool ) -> AttrSet -> AttrSet -> AttrSet</literal>
1518 </subtitle>
1519
1520 <xi:include href="./locations.xml" xpointer="lib.attrsets.recursiveUpdateUntil" />
1521
1522 <para>
1523 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.
1524 </para>
1525
1526 <variablelist>
1527 <varlistentry>
1528 <term>
1529 <varname>pred</varname>
1530 </term>
1531 <listitem>
1532 <para>
1533 <literal>[ String ] -> AttrSet -> AttrSet -> Bool</literal>
1534 </para>
1535 <variablelist>
1536 <varlistentry>
1537 <term>
1538 <varname>path</varname>
1539 </term>
1540 <listitem>
1541 <para>
1542 The path to the values in the left and right hand sides.
1543 </para>
1544 </listitem>
1545 </varlistentry>
1546 <varlistentry>
1547 <term>
1548 <varname>l</varname>
1549 </term>
1550 <listitem>
1551 <para>
1552 The left hand side value.
1553 </para>
1554 </listitem>
1555 </varlistentry>
1556 <varlistentry>
1557 <term>
1558 <varname>r</varname>
1559 </term>
1560 <listitem>
1561 <para>
1562 The right hand side value.
1563 </para>
1564 </listitem>
1565 </varlistentry>
1566 </variablelist>
1567 </listitem>
1568 </varlistentry>
1569 <varlistentry>
1570 <term>
1571 <varname>lhs</varname>
1572 </term>
1573 <listitem>
1574 <para>
1575 The left hand attribute set of the merge.
1576 </para>
1577 </listitem>
1578 </varlistentry>
1579 <varlistentry>
1580 <term>
1581 <varname>rhs</varname>
1582 </term>
1583 <listitem>
1584 <para>
1585 The right hand attribute set of the merge.
1586 </para>
1587 </listitem>
1588 </varlistentry>
1589 </variablelist>
1590
1591 <example xml:id="function-library-lib.attrsets.recursiveUpdateUntil-example">
1592 <title>Recursively merging two attribute sets</title>
1593<programlisting><![CDATA[
1594lib.attrsets.recursiveUpdateUntil (path: l: r: path == ["foo"])
1595 {
1596 # first attribute set
1597 foo.bar = 1;
1598 foo.baz = 2;
1599 bar = 3;
1600 }
1601 {
1602 #second attribute set
1603 foo.bar = 1;
1604 foo.quz = 2;
1605 baz = 4;
1606 }
1607=> {
1608 foo.bar = 1; # 'foo.*' from the second set
1609 foo.quz = 2; #
1610 bar = 3; # 'bar' from the first set
1611 baz = 4; # 'baz' from the second set
1612}
1613 ]]></programlisting>
1614 </example>
1615 </section>
1616
1617 <section xml:id="function-library-lib.attrsets.recursiveUpdate">
1618 <title><function>lib.attrsets.recursiveUpdate</function></title>
1619
1620 <subtitle><literal>recursiveUpdate :: AttrSet -> AttrSet -> AttrSet</literal>
1621 </subtitle>
1622
1623 <xi:include href="./locations.xml" xpointer="lib.attrsets.recursiveUpdate" />
1624
1625 <para>
1626 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.
1627 </para>
1628
1629 <variablelist>
1630 <varlistentry>
1631 <term>
1632 <varname>lhs</varname>
1633 </term>
1634 <listitem>
1635 <para>
1636 The left hand attribute set of the merge.
1637 </para>
1638 </listitem>
1639 </varlistentry>
1640 <varlistentry>
1641 <term>
1642 <varname>rhs</varname>
1643 </term>
1644 <listitem>
1645 <para>
1646 The right hand attribute set of the merge.
1647 </para>
1648 </listitem>
1649 </varlistentry>
1650 </variablelist>
1651
1652 <example xml:id="function-library-lib.attrsets.recursiveUpdate-example">
1653 <title>Recursively merging two attribute sets</title>
1654<programlisting><![CDATA[
1655recursiveUpdate
1656 {
1657 boot.loader.grub.enable = true;
1658 boot.loader.grub.device = "/dev/hda";
1659 }
1660 {
1661 boot.loader.grub.device = "";
1662 }
1663=> {
1664 boot.loader.grub.enable = true;
1665 boot.loader.grub.device = "";
1666}
1667]]></programlisting>
1668 </example>
1669 </section>
1670
1671 <section xml:id="function-library-lib.attrsets.recurseIntoAttrs">
1672 <title><function>lib.attrsets.recurseIntoAttrs</function></title>
1673
1674 <subtitle><literal>recurseIntoAttrs :: AttrSet -> AttrSet</literal>
1675 </subtitle>
1676
1677 <xi:include href="./locations.xml" xpointer="lib.attrsets.recurseIntoAttrs" />
1678
1679 <para>
1680 Make various Nix tools consider the contents of the resulting attribute set when looking for what to build, find, etc.
1681 </para>
1682
1683 <para>
1684 This function only affects a single attribute set; it does not apply itself recursively for nested attribute sets.
1685 </para>
1686
1687 <variablelist>
1688 <varlistentry>
1689 <term>
1690 <varname>attrs</varname>
1691 </term>
1692 <listitem>
1693 <para>
1694 An attribute set to scan for derivations.
1695 </para>
1696 </listitem>
1697 </varlistentry>
1698 </variablelist>
1699
1700 <example xml:id="function-library-lib.attrsets.recurseIntoAttrs-example">
1701 <title>Making Nix look inside an attribute set</title>
1702<programlisting><![CDATA[
1703{ pkgs ? import <nixpkgs> {} }:
1704{
1705 myTools = pkgs.lib.recurseIntoAttrs {
1706 inherit (pkgs) hello figlet;
1707 };
1708}
1709]]></programlisting>
1710 </example>
1711 </section>
1712
1713 <section xml:id="function-library-lib.attrsets.cartesianProductOfSets">
1714 <title><function>lib.attrsets.cartesianProductOfSets</function></title>
1715
1716 <subtitle><literal>cartesianProductOfSets :: AttrSet -> [ AttrSet ]</literal>
1717 </subtitle>
1718
1719 <xi:include href="./locations.xml" xpointer="lib.attrsets.cartesianProductOfSets" />
1720
1721 <para>
1722 Return the cartesian product of attribute set value combinations.
1723 </para>
1724
1725 <variablelist>
1726 <varlistentry>
1727 <term>
1728 <varname>set</varname>
1729 </term>
1730 <listitem>
1731 <para>
1732 An attribute set with attributes that carry lists of values.
1733 </para>
1734 </listitem>
1735 </varlistentry>
1736 </variablelist>
1737
1738 <example xml:id="function-library-lib.attrsets.cartesianProductOfSets-example">
1739 <title>Creating the cartesian product of a list of attribute values</title>
1740<programlisting><![CDATA[
1741cartesianProductOfSets { a = [ 1 2 ]; b = [ 10 20 ]; }
1742=> [
1743 { a = 1; b = 10; }
1744 { a = 1; b = 20; }
1745 { a = 2; b = 10; }
1746 { a = 2; b = 20; }
1747 ]
1748]]></programlisting>
1749 </example>
1750 </section>
1751</section>