···
1
+
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-option-types">
2
+
<title>Options Types</title>
4
+
Option types are a way to put constraints on the values a module
5
+
option can take. Types are also responsible of how values are merged
6
+
in case of multiple value definitions.
8
+
<section xml:id="sec-option-types-basic">
9
+
<title>Basic Types</title>
11
+
Basic types are the simplest available types in the module system.
12
+
Basic types include multiple string types that mainly differ in
13
+
how definition merging is handled.
18
+
<literal>types.bool</literal>
22
+
A boolean, its values can be <literal>true</literal> or
23
+
<literal>false</literal>.
29
+
<literal>types.path</literal>
33
+
A filesystem path, defined as anything that when coerced to
34
+
a string starts with a slash. Even if derivations can be
35
+
considered as path, the more specific
36
+
<literal>types.package</literal> should be preferred.
42
+
<literal>types.package</literal>
46
+
A derivation or a store path.
52
+
<literal>types.anything</literal>
56
+
A type that accepts any value and recursively merges
57
+
attribute sets together. This type is recommended when the
58
+
option type is unknown.
60
+
<anchor xml:id="ex-types-anything" />
62
+
<emphasis role="strong">Example:
63
+
<literal>types.anything</literal> Example</emphasis>
66
+
Two definitions of this type like
68
+
<programlisting language="bash">
70
+
str = lib.mkDefault "foo";
71
+
pkg.hello = pkgs.hello;
75
+
<programlisting language="bash">
77
+
str = lib.mkIf true "bar";
79
+
fun.fun = lib.mkForce (x: x + 2);
85
+
<programlisting language="bash">
87
+
str = "bar";
89
+
pkg.hello = pkgs.hello;
97
+
<literal>types.attrs</literal>
101
+
A free-form attribute set.
105
+
This type will be deprecated in the future because it
106
+
doesn't recurse into attribute sets, silently drops
107
+
earlier attribute definitions, and doesn't discharge
108
+
<literal>lib.mkDefault</literal>,
109
+
<literal>lib.mkIf</literal> and co. For allowing arbitrary
110
+
attribute sets, prefer
111
+
<literal>types.attrsOf types.anything</literal> instead
112
+
which doesn't have these problems.
119
+
Integer-related types:
124
+
<literal>types.int</literal>
134
+
<literal>types.ints.{s8, s16, s32}</literal>
138
+
Signed integers with a fixed length (8, 16 or 32 bits). They
139
+
go from −2^n/2 to 2^n/2−1 respectively (e.g.
140
+
<literal>−128</literal> to <literal>127</literal> for 8
147
+
<literal>types.ints.unsigned</literal>
151
+
An unsigned integer (that is >= 0).
157
+
<literal>types.ints.{u8, u16, u32}</literal>
161
+
Unsigned integers with a fixed length (8, 16 or 32 bits).
162
+
They go from 0 to 2^n−1 respectively (e.g.
163
+
<literal>0</literal> to <literal>255</literal> for 8 bits).
169
+
<literal>types.ints.positive</literal>
173
+
A positive integer (that is > 0).
179
+
<literal>types.port</literal>
183
+
A port number. This type is an alias to
184
+
<literal>types.ints.u16</literal>.
190
+
String-related types:
195
+
<literal>types.str</literal>
199
+
A string. Multiple definitions cannot be merged.
205
+
<literal>types.lines</literal>
209
+
A string. Multiple definitions are concatenated with a new
210
+
line <literal>"\n"</literal>.
216
+
<literal>types.commas</literal>
220
+
A string. Multiple definitions are concatenated with a comma
221
+
<literal>","</literal>.
227
+
<literal>types.envVar</literal>
231
+
A string. Multiple definitions are concatenated with a
232
+
collon <literal>":"</literal>.
238
+
<literal>types.strMatching</literal>
242
+
A string matching a specific regular expression. Multiple
243
+
definitions cannot be merged. The regular expression is
244
+
processed using <literal>builtins.match</literal>.
250
+
<section xml:id="sec-option-types-value">
251
+
<title>Value Types</title>
253
+
Value types are types that take a value parameter.
258
+
<literal>types.enum</literal>
259
+
<emphasis><literal>l</literal></emphasis>
263
+
One element of the list
264
+
<emphasis><literal>l</literal></emphasis>, e.g.
265
+
<literal>types.enum [ "left" "right" ]</literal>.
266
+
Multiple definitions cannot be merged.
272
+
<literal>types.separatedString</literal>
273
+
<emphasis><literal>sep</literal></emphasis>
277
+
A string with a custom separator
278
+
<emphasis><literal>sep</literal></emphasis>, e.g.
279
+
<literal>types.separatedString "|"</literal>.
285
+
<literal>types.ints.between</literal>
286
+
<emphasis><literal>lowest highest</literal></emphasis>
291
+
<emphasis><literal>lowest</literal></emphasis> and
292
+
<emphasis><literal>highest</literal></emphasis> (both
293
+
inclusive). Useful for creating types like
294
+
<literal>types.port</literal>.
300
+
<literal>types.submodule</literal>
301
+
<emphasis><literal>o</literal></emphasis>
305
+
A set of sub options
306
+
<emphasis><literal>o</literal></emphasis>.
307
+
<emphasis><literal>o</literal></emphasis> can be an
308
+
attribute set, a function returning an attribute set, or a
309
+
path to a file containing such a value. Submodules are used
310
+
in composed types to create modular options. This is
312
+
<literal>types.submoduleWith { modules = toList o; shorthandOnlyDefinesConfig = true; }</literal>.
313
+
Submodules are detailed in
314
+
<link linkend="section-option-types-submodule">Submodule</link>.
320
+
<literal>types.submoduleWith</literal> {
321
+
<emphasis><literal>modules</literal></emphasis>,
322
+
<emphasis><literal>specialArgs</literal></emphasis> ? {},
323
+
<emphasis><literal>shorthandOnlyDefinesConfig</literal></emphasis>
328
+
Like <literal>types.submodule</literal>, but more flexible
329
+
and with better defaults. It has parameters
334
+
<emphasis><literal>modules</literal></emphasis> A list
335
+
of modules to use by default for this submodule type.
336
+
This gets combined with all option definitions to build
337
+
the final list of modules that will be included.
341
+
Only options defined with this argument are included
342
+
in rendered documentation.
348
+
<emphasis><literal>specialArgs</literal></emphasis> An
349
+
attribute set of extra arguments to be passed to the
350
+
module functions. The option
351
+
<literal>_module.args</literal> should be used instead
352
+
for most arguments since it allows overriding.
353
+
<emphasis><literal>specialArgs</literal></emphasis>
354
+
should only be used for arguments that can't go through
355
+
the module fixed-point, because of infinite recursion or
356
+
other problems. An example is overriding the
357
+
<literal>lib</literal> argument, because
358
+
<literal>lib</literal> itself is used to define
359
+
<literal>_module.args</literal>, which makes using
360
+
<literal>_module.args</literal> to define it impossible.
365
+
<emphasis><literal>shorthandOnlyDefinesConfig</literal></emphasis>
366
+
Whether definitions of this type should default to the
367
+
<literal>config</literal> section of a module (see
368
+
<link linkend="ex-module-syntax">Example: Structure of
369
+
NixOS Modules</link>) if it is an attribute set.
370
+
Enabling this only has a benefit when the submodule
371
+
defines an option named <literal>config</literal> or
372
+
<literal>options</literal>. In such a case it would
373
+
allow the option to be set with
374
+
<literal>the-submodule.config = "value"</literal>
375
+
instead of requiring
376
+
<literal>the-submodule.config.config = "value"</literal>.
377
+
This is because only when modules
378
+
<emphasis>don't</emphasis> set the
379
+
<literal>config</literal> or <literal>options</literal>
380
+
keys, all keys are interpreted as option definitions in
381
+
the <literal>config</literal> section. Enabling this
382
+
option implicitly puts all attributes in the
383
+
<literal>config</literal> section.
386
+
With this option enabled, defining a
387
+
non-<literal>config</literal> section requires using a
389
+
<literal>the-submodule = { ... }: { options = { ... }; }</literal>.
397
+
<section xml:id="sec-option-types-composed">
398
+
<title>Composed Types</title>
400
+
Composed types are types that take a type as parameter.
401
+
<literal>listOf int</literal> and
402
+
<literal>either int str</literal> are examples of composed types.
407
+
<literal>types.listOf</literal>
408
+
<emphasis><literal>t</literal></emphasis>
412
+
A list of <emphasis><literal>t</literal></emphasis> type,
413
+
e.g. <literal>types.listOf int</literal>. Multiple
414
+
definitions are merged with list concatenation.
420
+
<literal>types.attrsOf</literal>
421
+
<emphasis><literal>t</literal></emphasis>
425
+
An attribute set of where all the values are of
426
+
<emphasis><literal>t</literal></emphasis> type. Multiple
427
+
definitions result in the joined attribute set.
431
+
This type is <emphasis>strict</emphasis> in its values,
432
+
which in turn means attributes cannot depend on other
433
+
attributes. See <literal> types.lazyAttrsOf</literal> for
441
+
<literal>types.lazyAttrsOf</literal>
442
+
<emphasis><literal>t</literal></emphasis>
446
+
An attribute set of where all the values are of
447
+
<emphasis><literal>t</literal></emphasis> type. Multiple
448
+
definitions result in the joined attribute set. This is the
449
+
lazy version of <literal>types.attrsOf </literal>, allowing
450
+
attributes to depend on each other.
454
+
This version does not fully support conditional
455
+
definitions! With an option <literal>foo</literal> of this
456
+
type and a definition
457
+
<literal>foo.attr = lib.mkIf false 10</literal>,
458
+
evaluating <literal>foo ? attr</literal> will return
459
+
<literal>true</literal> even though it should be false.
460
+
Accessing the value will then throw an error. For types
461
+
<emphasis><literal>t</literal></emphasis> that have an
462
+
<literal>emptyValue</literal> defined, that value will be
463
+
returned instead of throwing an error. So if the type of
464
+
<literal>foo.attr</literal> was
465
+
<literal>lazyAttrsOf (nullOr int)</literal>,
466
+
<literal>null</literal> would be returned instead for the
467
+
same <literal>mkIf false</literal> definition.
474
+
<literal>types.nullOr</literal>
475
+
<emphasis><literal>t</literal></emphasis>
479
+
<literal>null</literal> or type
480
+
<emphasis><literal>t</literal></emphasis>. Multiple
481
+
definitions are merged according to type
482
+
<emphasis><literal>t</literal></emphasis>.
488
+
<literal>types.uniq</literal>
489
+
<emphasis><literal>t</literal></emphasis>
493
+
Ensures that type <emphasis><literal>t</literal></emphasis>
494
+
cannot be merged. It is used to ensure option definitions
495
+
are declared only once.
501
+
<literal>types.either</literal>
502
+
<emphasis><literal>t1 t2</literal></emphasis>
506
+
Type <emphasis><literal>t1</literal></emphasis> or type
507
+
<emphasis><literal>t2</literal></emphasis>, e.g.
508
+
<literal>with types; either int str</literal>. Multiple
509
+
definitions cannot be merged.
515
+
<literal>types.oneOf</literal> [
516
+
<emphasis><literal>t1 t2</literal></emphasis> ... ]
520
+
Type <emphasis><literal>t1</literal></emphasis> or type
521
+
<emphasis><literal>t2</literal></emphasis> and so forth,
522
+
e.g. <literal>with types; oneOf [ int str bool ]</literal>.
523
+
Multiple definitions cannot be merged.
529
+
<literal>types.coercedTo</literal>
530
+
<emphasis><literal>from f to</literal></emphasis>
534
+
Type <emphasis><literal>to</literal></emphasis> or type
535
+
<emphasis><literal>from</literal></emphasis> which will be
536
+
coerced to type <emphasis><literal>to</literal></emphasis>
537
+
using function <emphasis><literal>f</literal></emphasis>
538
+
which takes an argument of type
539
+
<emphasis><literal>from</literal></emphasis> and return a
540
+
value of type <emphasis><literal>to</literal></emphasis>.
541
+
Can be used to preserve backwards compatibility of an option
542
+
if its type was changed.
548
+
<section xml:id="section-option-types-submodule">
549
+
<title>Submodule</title>
551
+
<literal>submodule</literal> is a very powerful type that defines
552
+
a set of sub-options that are handled like a separate module.
555
+
It takes a parameter <emphasis><literal>o</literal></emphasis>,
556
+
that should be a set, or a function returning a set with an
557
+
<literal>options</literal> key defining the sub-options. Submodule
558
+
option definitions are type-checked accordingly to the
559
+
<literal>options</literal> declarations. Of course, you can nest
560
+
submodule option definitons for even higher modularity.
563
+
The option set can be defined directly
564
+
(<link linkend="ex-submodule-direct">Example: Directly defined
565
+
submodule</link>) or as reference
566
+
(<link linkend="ex-submodule-reference">Example: Submodule defined
567
+
as a reference</link>).
569
+
<anchor xml:id="ex-submodule-direct" />
571
+
<emphasis role="strong">Example: Directly defined
572
+
submodule</emphasis>
574
+
<programlisting language="bash">
575
+
options.mod = mkOption {
576
+
description = "submodule example";
577
+
type = with types; submodule {
589
+
<anchor xml:id="ex-submodule-reference" />
591
+
<emphasis role="strong">Example: Submodule defined as a
592
+
reference</emphasis>
594
+
<programlisting language="bash">
607
+
options.mod = mkOption {
608
+
description = "submodule example";
609
+
type = with types; submodule modOptions;
613
+
The <literal>submodule</literal> type is especially interesting
614
+
when used with composed types like <literal>attrsOf</literal> or
615
+
<literal>listOf</literal>. When composed with
616
+
<literal>listOf</literal>
617
+
(<link linkend="ex-submodule-listof-declaration">Example:
618
+
Declaration of a list of submodules</link>),
619
+
<literal>submodule</literal> allows multiple definitions of the
620
+
submodule option set
621
+
(<link linkend="ex-submodule-listof-definition">Example:
622
+
Definition of a list of submodules</link>).
624
+
<anchor xml:id="ex-submodule-listof-declaration" />
626
+
<emphasis role="strong">Example: Declaration of a list of
627
+
submodules</emphasis>
629
+
<programlisting language="bash">
630
+
options.mod = mkOption {
631
+
description = "submodule example";
632
+
type = with types; listOf (submodule {
644
+
<anchor xml:id="ex-submodule-listof-definition" />
646
+
<emphasis role="strong">Example: Definition of a list of
647
+
submodules</emphasis>
649
+
<programlisting language="bash">
651
+
{ foo = 1; bar = "one"; }
652
+
{ foo = 2; bar = "two"; }
656
+
When composed with <literal>attrsOf</literal>
657
+
(<link linkend="ex-submodule-attrsof-declaration">Example:
658
+
Declaration of attribute sets of submodules</link>),
659
+
<literal>submodule</literal> allows multiple named definitions of
660
+
the submodule option set
661
+
(<link linkend="ex-submodule-attrsof-definition">Example:
662
+
Definition of attribute sets of submodules</link>).
664
+
<anchor xml:id="ex-submodule-attrsof-declaration" />
666
+
<emphasis role="strong">Example: Declaration of attribute sets of
667
+
submodules</emphasis>
669
+
<programlisting language="bash">
670
+
options.mod = mkOption {
671
+
description = "submodule example";
672
+
type = with types; attrsOf (submodule {
684
+
<anchor xml:id="ex-submodule-attrsof-definition" />
686
+
<emphasis role="strong">Example: Definition of attribute sets of
687
+
submodules</emphasis>
689
+
<programlisting language="bash">
690
+
config.mod.one = { foo = 1; bar = "one"; };
691
+
config.mod.two = { foo = 2; bar = "two"; };
694
+
<section xml:id="sec-option-types-extending">
695
+
<title>Extending types</title>
697
+
Types are mainly characterized by their <literal>check</literal>
698
+
and <literal>merge</literal> functions.
703
+
<literal>check</literal>
707
+
The function to type check the value. Takes a value as
708
+
parameter and return a boolean. It is possible to extend a
709
+
type check with the <literal>addCheck</literal> function
710
+
(<link linkend="ex-extending-type-check-1">Example: Adding a
711
+
type check</link>), or to fully override the check function
712
+
(<link linkend="ex-extending-type-check-2">Example:
713
+
Overriding a type check</link>).
715
+
<anchor xml:id="ex-extending-type-check-1" />
717
+
<emphasis role="strong">Example: Adding a type
720
+
<programlisting language="bash">
722
+
description = "An integer between 0 and 255.";
723
+
type = types.addCheck types.int (x: x >= 0 && x <= 255);
726
+
<anchor xml:id="ex-extending-type-check-2" />
728
+
<emphasis role="strong">Example: Overriding a type
731
+
<programlisting language="bash">
732
+
nixThings = mkOption {
733
+
description = "words that start with 'nix'";
734
+
type = types.str // {
735
+
check = (x: lib.hasPrefix "nix" x)
743
+
<literal>merge</literal>
747
+
Function to merge the options values when multiple values
748
+
are set. The function takes two parameters,
749
+
<literal>loc</literal> the option path as a list of strings,
750
+
and <literal>defs</literal> the list of defined values as a
751
+
list. It is possible to override a type merge function for
758
+
<section xml:id="sec-option-types-custom">
759
+
<title>Custom Types</title>
761
+
Custom types can be created with the
762
+
<literal>mkOptionType</literal> function. As type creation
763
+
includes some more complex topics such as submodule handling, it
764
+
is recommended to get familiar with <literal>types.nix</literal>
765
+
code before creating a new type.
768
+
The only required parameter is <literal>name</literal>.
773
+
<literal>name</literal>
777
+
A string representation of the type function name.
783
+
<literal>definition</literal>
787
+
Description of the type used in documentation. Give
788
+
information of the type and any of its arguments.
794
+
<literal>check</literal>
798
+
A function to type check the definition value. Takes the
799
+
definition value as a parameter and returns a boolean
800
+
indicating the type check result, <literal>true</literal>
801
+
for success and <literal>false</literal> for failure.
807
+
<literal>merge</literal>
811
+
A function to merge multiple definitions values. Takes two
817
+
<emphasis><literal>loc</literal></emphasis>
821
+
The option path as a list of strings, e.g.
822
+
<literal>["boot" "loader "grub" "enable"]</literal>.
828
+
<emphasis><literal>defs</literal></emphasis>
832
+
The list of sets of defined <literal>value</literal>
833
+
and <literal>file</literal> where the value was
835
+
<literal>[ { file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 } ]</literal>.
836
+
The <literal>merge</literal> function should return
837
+
the merged value or throw an error in case the values
838
+
are impossible or not meant to be merged.
847
+
<literal>getSubOptions</literal>
851
+
For composed types that can take a submodule as type
852
+
parameter, this function generate sub-options documentation.
853
+
It takes the current option prefix as a list and return the
854
+
set of sub-options. Usually defined in a recursive manner by
855
+
adding a term to the prefix, e.g.
856
+
<literal>prefix: elemType.getSubOptions (prefix ++ ["prefix"])</literal>
858
+
<emphasis><literal>"prefix"</literal></emphasis>
859
+
is the newly added prefix.
865
+
<literal>getSubModules</literal>
869
+
For composed types that can take a submodule as type
870
+
parameter, this function should return the type parameters
871
+
submodules. If the type parameter is called
872
+
<literal>elemType</literal>, the function should just
873
+
recursively look into submodules by returning
874
+
<literal>elemType.getSubModules;</literal>.
880
+
<literal>substSubModules</literal>
884
+
For composed types that can take a submodule as type
885
+
parameter, this function can be used to substitute the
886
+
parameter of a submodule type. It takes a module as
887
+
parameter and return the type with the submodule options
888
+
substituted. It is usually defined as a type function call
889
+
with a recursive call to <literal>substSubModules</literal>,
890
+
e.g for a type <literal>composedType</literal> that take an
891
+
<literal>elemtype</literal> type parameter, this function
892
+
should be defined as
893
+
<literal>m: composedType (elemType.substSubModules m)</literal>.
899
+
<literal>typeMerge</literal>
903
+
A function to merge multiple type declarations. Takes the
904
+
type to merge <literal>functor</literal> as parameter. A
905
+
<literal>null</literal> return value means that type cannot
911
+
<emphasis><literal>f</literal></emphasis>
915
+
The type to merge <literal>functor</literal>.
921
+
Note: There is a generic <literal>defaultTypeMerge</literal>
922
+
that work with most of value and composed types.
928
+
<literal>functor</literal>
932
+
An attribute set representing the type. It is used for type
933
+
operations and has the following keys:
938
+
<literal>type</literal>
948
+
<literal>wrapped</literal>
952
+
Holds the type parameter for composed types.
958
+
<literal>payload</literal>
962
+
Holds the value parameter for value types. The types
963
+
that have a <literal>payload</literal> are the
964
+
<literal>enum</literal>,
965
+
<literal>separatedString</literal> and
966
+
<literal>submodule</literal> types.
972
+
<literal>binOp</literal>
976
+
A binary operation that can merge the payloads of two
977
+
same types. Defined as a function that take two
978
+
payloads as parameters and return the payloads merged.
pyrox.dev