···
+
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-option-types">
+
<title>Options Types</title>
+
Option types are a way to put constraints on the values a module
+
option can take. Types are also responsible of how values are merged
+
in case of multiple value definitions.
+
<section xml:id="sec-option-types-basic">
+
<title>Basic Types</title>
+
Basic types are the simplest available types in the module system.
+
Basic types include multiple string types that mainly differ in
+
how definition merging is handled.
+
<literal>types.bool</literal>
+
A boolean, its values can be <literal>true</literal> or
+
<literal>false</literal>.
+
<literal>types.path</literal>
+
A filesystem path, defined as anything that when coerced to
+
a string starts with a slash. Even if derivations can be
+
considered as path, the more specific
+
<literal>types.package</literal> should be preferred.
+
<literal>types.package</literal>
+
A derivation or a store path.
+
<literal>types.anything</literal>
+
A type that accepts any value and recursively merges
+
attribute sets together. This type is recommended when the
+
option type is unknown.
+
<anchor xml:id="ex-types-anything" />
+
<emphasis role="strong">Example:
+
<literal>types.anything</literal> Example</emphasis>
+
Two definitions of this type like
+
<programlisting language="bash">
+
str = lib.mkDefault "foo";
+
pkg.hello = pkgs.hello;
+
<programlisting language="bash">
+
str = lib.mkIf true "bar";
+
fun.fun = lib.mkForce (x: x + 2);
+
<programlisting language="bash">
+
pkg.hello = pkgs.hello;
+
<literal>types.attrs</literal>
+
A free-form attribute set.
+
This type will be deprecated in the future because it
+
doesn't recurse into attribute sets, silently drops
+
earlier attribute definitions, and doesn't discharge
+
<literal>lib.mkDefault</literal>,
+
<literal>lib.mkIf</literal> and co. For allowing arbitrary
+
<literal>types.attrsOf types.anything</literal> instead
+
which doesn't have these problems.
+
<literal>types.int</literal>
+
<literal>types.ints.{s8, s16, s32}</literal>
+
Signed integers with a fixed length (8, 16 or 32 bits). They
+
go from −2^n/2 to 2^n/2−1 respectively (e.g.
+
<literal>−128</literal> to <literal>127</literal> for 8
+
<literal>types.ints.unsigned</literal>
+
An unsigned integer (that is >= 0).
+
<literal>types.ints.{u8, u16, u32}</literal>
+
Unsigned integers with a fixed length (8, 16 or 32 bits).
+
They go from 0 to 2^n−1 respectively (e.g.
+
<literal>0</literal> to <literal>255</literal> for 8 bits).
+
<literal>types.ints.positive</literal>
+
A positive integer (that is > 0).
+
<literal>types.port</literal>
+
A port number. This type is an alias to
+
<literal>types.ints.u16</literal>.
+
<literal>types.str</literal>
+
A string. Multiple definitions cannot be merged.
+
<literal>types.lines</literal>
+
A string. Multiple definitions are concatenated with a new
+
line <literal>"\n"</literal>.
+
<literal>types.commas</literal>
+
A string. Multiple definitions are concatenated with a comma
+
<literal>","</literal>.
+
<literal>types.envVar</literal>
+
A string. Multiple definitions are concatenated with a
+
collon <literal>":"</literal>.
+
<literal>types.strMatching</literal>
+
A string matching a specific regular expression. Multiple
+
definitions cannot be merged. The regular expression is
+
processed using <literal>builtins.match</literal>.
+
<section xml:id="sec-option-types-value">
+
<title>Value Types</title>
+
Value types are types that take a value parameter.
+
<literal>types.enum</literal>
+
<emphasis><literal>l</literal></emphasis>
+
One element of the list
+
<emphasis><literal>l</literal></emphasis>, e.g.
+
<literal>types.enum [ "left" "right" ]</literal>.
+
Multiple definitions cannot be merged.
+
<literal>types.separatedString</literal>
+
<emphasis><literal>sep</literal></emphasis>
+
A string with a custom separator
+
<emphasis><literal>sep</literal></emphasis>, e.g.
+
<literal>types.separatedString "|"</literal>.
+
<literal>types.ints.between</literal>
+
<emphasis><literal>lowest highest</literal></emphasis>
+
<emphasis><literal>lowest</literal></emphasis> and
+
<emphasis><literal>highest</literal></emphasis> (both
+
inclusive). Useful for creating types like
+
<literal>types.port</literal>.
+
<literal>types.submodule</literal>
+
<emphasis><literal>o</literal></emphasis>
+
<emphasis><literal>o</literal></emphasis>.
+
<emphasis><literal>o</literal></emphasis> can be an
+
attribute set, a function returning an attribute set, or a
+
path to a file containing such a value. Submodules are used
+
in composed types to create modular options. This is
+
<literal>types.submoduleWith { modules = toList o; shorthandOnlyDefinesConfig = true; }</literal>.
+
Submodules are detailed in
+
<link linkend="section-option-types-submodule">Submodule</link>.
+
<literal>types.submoduleWith</literal> {
+
<emphasis><literal>modules</literal></emphasis>,
+
<emphasis><literal>specialArgs</literal></emphasis> ? {},
+
<emphasis><literal>shorthandOnlyDefinesConfig</literal></emphasis>
+
Like <literal>types.submodule</literal>, but more flexible
+
and with better defaults. It has parameters
+
<emphasis><literal>modules</literal></emphasis> A list
+
of modules to use by default for this submodule type.
+
This gets combined with all option definitions to build
+
the final list of modules that will be included.
+
Only options defined with this argument are included
+
in rendered documentation.
+
<emphasis><literal>specialArgs</literal></emphasis> An
+
attribute set of extra arguments to be passed to the
+
module functions. The option
+
<literal>_module.args</literal> should be used instead
+
for most arguments since it allows overriding.
+
<emphasis><literal>specialArgs</literal></emphasis>
+
should only be used for arguments that can't go through
+
the module fixed-point, because of infinite recursion or
+
other problems. An example is overriding the
+
<literal>lib</literal> argument, because
+
<literal>lib</literal> itself is used to define
+
<literal>_module.args</literal>, which makes using
+
<literal>_module.args</literal> to define it impossible.
+
<emphasis><literal>shorthandOnlyDefinesConfig</literal></emphasis>
+
Whether definitions of this type should default to the
+
<literal>config</literal> section of a module (see
+
<link linkend="ex-module-syntax">Example: Structure of
+
NixOS Modules</link>) if it is an attribute set.
+
Enabling this only has a benefit when the submodule
+
defines an option named <literal>config</literal> or
+
<literal>options</literal>. In such a case it would
+
allow the option to be set with
+
<literal>the-submodule.config = "value"</literal>
+
<literal>the-submodule.config.config = "value"</literal>.
+
This is because only when modules
+
<emphasis>don't</emphasis> set the
+
<literal>config</literal> or <literal>options</literal>
+
keys, all keys are interpreted as option definitions in
+
the <literal>config</literal> section. Enabling this
+
option implicitly puts all attributes in the
+
<literal>config</literal> section.
+
With this option enabled, defining a
+
non-<literal>config</literal> section requires using a
+
<literal>the-submodule = { ... }: { options = { ... }; }</literal>.
+
<section xml:id="sec-option-types-composed">
+
<title>Composed Types</title>
+
Composed types are types that take a type as parameter.
+
<literal>listOf int</literal> and
+
<literal>either int str</literal> are examples of composed types.
+
<literal>types.listOf</literal>
+
<emphasis><literal>t</literal></emphasis>
+
A list of <emphasis><literal>t</literal></emphasis> type,
+
e.g. <literal>types.listOf int</literal>. Multiple
+
definitions are merged with list concatenation.
+
<literal>types.attrsOf</literal>
+
<emphasis><literal>t</literal></emphasis>
+
An attribute set of where all the values are of
+
<emphasis><literal>t</literal></emphasis> type. Multiple
+
definitions result in the joined attribute set.
+
This type is <emphasis>strict</emphasis> in its values,
+
which in turn means attributes cannot depend on other
+
attributes. See <literal> types.lazyAttrsOf</literal> for
+
<literal>types.lazyAttrsOf</literal>
+
<emphasis><literal>t</literal></emphasis>
+
An attribute set of where all the values are of
+
<emphasis><literal>t</literal></emphasis> type. Multiple
+
definitions result in the joined attribute set. This is the
+
lazy version of <literal>types.attrsOf </literal>, allowing
+
attributes to depend on each other.
+
This version does not fully support conditional
+
definitions! With an option <literal>foo</literal> of this
+
<literal>foo.attr = lib.mkIf false 10</literal>,
+
evaluating <literal>foo ? attr</literal> will return
+
<literal>true</literal> even though it should be false.
+
Accessing the value will then throw an error. For types
+
<emphasis><literal>t</literal></emphasis> that have an
+
<literal>emptyValue</literal> defined, that value will be
+
returned instead of throwing an error. So if the type of
+
<literal>foo.attr</literal> was
+
<literal>lazyAttrsOf (nullOr int)</literal>,
+
<literal>null</literal> would be returned instead for the
+
same <literal>mkIf false</literal> definition.
+
<literal>types.nullOr</literal>
+
<emphasis><literal>t</literal></emphasis>
+
<literal>null</literal> or type
+
<emphasis><literal>t</literal></emphasis>. Multiple
+
definitions are merged according to type
+
<emphasis><literal>t</literal></emphasis>.
+
<literal>types.uniq</literal>
+
<emphasis><literal>t</literal></emphasis>
+
Ensures that type <emphasis><literal>t</literal></emphasis>
+
cannot be merged. It is used to ensure option definitions
+
are declared only once.
+
<literal>types.either</literal>
+
<emphasis><literal>t1 t2</literal></emphasis>
+
Type <emphasis><literal>t1</literal></emphasis> or type
+
<emphasis><literal>t2</literal></emphasis>, e.g.
+
<literal>with types; either int str</literal>. Multiple
+
definitions cannot be merged.
+
<literal>types.oneOf</literal> [
+
<emphasis><literal>t1 t2</literal></emphasis> ... ]
+
Type <emphasis><literal>t1</literal></emphasis> or type
+
<emphasis><literal>t2</literal></emphasis> and so forth,
+
e.g. <literal>with types; oneOf [ int str bool ]</literal>.
+
Multiple definitions cannot be merged.
+
<literal>types.coercedTo</literal>
+
<emphasis><literal>from f to</literal></emphasis>
+
Type <emphasis><literal>to</literal></emphasis> or type
+
<emphasis><literal>from</literal></emphasis> which will be
+
coerced to type <emphasis><literal>to</literal></emphasis>
+
using function <emphasis><literal>f</literal></emphasis>
+
which takes an argument of type
+
<emphasis><literal>from</literal></emphasis> and return a
+
value of type <emphasis><literal>to</literal></emphasis>.
+
Can be used to preserve backwards compatibility of an option
+
if its type was changed.
+
<section xml:id="section-option-types-submodule">
+
<title>Submodule</title>
+
<literal>submodule</literal> is a very powerful type that defines
+
a set of sub-options that are handled like a separate module.
+
It takes a parameter <emphasis><literal>o</literal></emphasis>,
+
that should be a set, or a function returning a set with an
+
<literal>options</literal> key defining the sub-options. Submodule
+
option definitions are type-checked accordingly to the
+
<literal>options</literal> declarations. Of course, you can nest
+
submodule option definitons for even higher modularity.
+
The option set can be defined directly
+
(<link linkend="ex-submodule-direct">Example: Directly defined
+
submodule</link>) or as reference
+
(<link linkend="ex-submodule-reference">Example: Submodule defined
+
as a reference</link>).
+
<anchor xml:id="ex-submodule-direct" />
+
<emphasis role="strong">Example: Directly defined
+
<programlisting language="bash">
+
options.mod = mkOption {
+
description = "submodule example";
+
type = with types; submodule {
+
<anchor xml:id="ex-submodule-reference" />
+
<emphasis role="strong">Example: Submodule defined as a
+
<programlisting language="bash">
+
options.mod = mkOption {
+
description = "submodule example";
+
type = with types; submodule modOptions;
+
The <literal>submodule</literal> type is especially interesting
+
when used with composed types like <literal>attrsOf</literal> or
+
<literal>listOf</literal>. When composed with
+
<literal>listOf</literal>
+
(<link linkend="ex-submodule-listof-declaration">Example:
+
Declaration of a list of submodules</link>),
+
<literal>submodule</literal> allows multiple definitions of the
+
(<link linkend="ex-submodule-listof-definition">Example:
+
Definition of a list of submodules</link>).
+
<anchor xml:id="ex-submodule-listof-declaration" />
+
<emphasis role="strong">Example: Declaration of a list of
+
<programlisting language="bash">
+
options.mod = mkOption {
+
description = "submodule example";
+
type = with types; listOf (submodule {
+
<anchor xml:id="ex-submodule-listof-definition" />
+
<emphasis role="strong">Example: Definition of a list of
+
<programlisting language="bash">
+
{ foo = 1; bar = "one"; }
+
{ foo = 2; bar = "two"; }
+
When composed with <literal>attrsOf</literal>
+
(<link linkend="ex-submodule-attrsof-declaration">Example:
+
Declaration of attribute sets of submodules</link>),
+
<literal>submodule</literal> allows multiple named definitions of
+
the submodule option set
+
(<link linkend="ex-submodule-attrsof-definition">Example:
+
Definition of attribute sets of submodules</link>).
+
<anchor xml:id="ex-submodule-attrsof-declaration" />
+
<emphasis role="strong">Example: Declaration of attribute sets of
+
<programlisting language="bash">
+
options.mod = mkOption {
+
description = "submodule example";
+
type = with types; attrsOf (submodule {
+
<anchor xml:id="ex-submodule-attrsof-definition" />
+
<emphasis role="strong">Example: Definition of attribute sets of
+
<programlisting language="bash">
+
config.mod.one = { foo = 1; bar = "one"; };
+
config.mod.two = { foo = 2; bar = "two"; };
+
<section xml:id="sec-option-types-extending">
+
<title>Extending types</title>
+
Types are mainly characterized by their <literal>check</literal>
+
and <literal>merge</literal> functions.
+
<literal>check</literal>
+
The function to type check the value. Takes a value as
+
parameter and return a boolean. It is possible to extend a
+
type check with the <literal>addCheck</literal> function
+
(<link linkend="ex-extending-type-check-1">Example: Adding a
+
type check</link>), or to fully override the check function
+
(<link linkend="ex-extending-type-check-2">Example:
+
Overriding a type check</link>).
+
<anchor xml:id="ex-extending-type-check-1" />
+
<emphasis role="strong">Example: Adding a type
+
<programlisting language="bash">
+
description = "An integer between 0 and 255.";
+
type = types.addCheck types.int (x: x >= 0 && x <= 255);
+
<anchor xml:id="ex-extending-type-check-2" />
+
<emphasis role="strong">Example: Overriding a type
+
<programlisting language="bash">
+
description = "words that start with 'nix'";
+
check = (x: lib.hasPrefix "nix" x)
+
<literal>merge</literal>
+
Function to merge the options values when multiple values
+
are set. The function takes two parameters,
+
<literal>loc</literal> the option path as a list of strings,
+
and <literal>defs</literal> the list of defined values as a
+
list. It is possible to override a type merge function for
+
<section xml:id="sec-option-types-custom">
+
<title>Custom Types</title>
+
Custom types can be created with the
+
<literal>mkOptionType</literal> function. As type creation
+
includes some more complex topics such as submodule handling, it
+
is recommended to get familiar with <literal>types.nix</literal>
+
code before creating a new type.
+
The only required parameter is <literal>name</literal>.
+
<literal>name</literal>
+
A string representation of the type function name.
+
<literal>definition</literal>
+
Description of the type used in documentation. Give
+
information of the type and any of its arguments.
+
<literal>check</literal>
+
A function to type check the definition value. Takes the
+
definition value as a parameter and returns a boolean
+
indicating the type check result, <literal>true</literal>
+
for success and <literal>false</literal> for failure.
+
<literal>merge</literal>
+
A function to merge multiple definitions values. Takes two
+
<emphasis><literal>loc</literal></emphasis>
+
The option path as a list of strings, e.g.
+
<literal>["boot" "loader "grub" "enable"]</literal>.
+
<emphasis><literal>defs</literal></emphasis>
+
The list of sets of defined <literal>value</literal>
+
and <literal>file</literal> where the value was
+
<literal>[ { file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 } ]</literal>.
+
The <literal>merge</literal> function should return
+
the merged value or throw an error in case the values
+
are impossible or not meant to be merged.
+
<literal>getSubOptions</literal>
+
For composed types that can take a submodule as type
+
parameter, this function generate sub-options documentation.
+
It takes the current option prefix as a list and return the
+
set of sub-options. Usually defined in a recursive manner by
+
adding a term to the prefix, e.g.
+
<literal>prefix: elemType.getSubOptions (prefix ++ ["prefix"])</literal>
+
<emphasis><literal>"prefix"</literal></emphasis>
+
is the newly added prefix.
+
<literal>getSubModules</literal>
+
For composed types that can take a submodule as type
+
parameter, this function should return the type parameters
+
submodules. If the type parameter is called
+
<literal>elemType</literal>, the function should just
+
recursively look into submodules by returning
+
<literal>elemType.getSubModules;</literal>.
+
<literal>substSubModules</literal>
+
For composed types that can take a submodule as type
+
parameter, this function can be used to substitute the
+
parameter of a submodule type. It takes a module as
+
parameter and return the type with the submodule options
+
substituted. It is usually defined as a type function call
+
with a recursive call to <literal>substSubModules</literal>,
+
e.g for a type <literal>composedType</literal> that take an
+
<literal>elemtype</literal> type parameter, this function
+
<literal>m: composedType (elemType.substSubModules m)</literal>.
+
<literal>typeMerge</literal>
+
A function to merge multiple type declarations. Takes the
+
type to merge <literal>functor</literal> as parameter. A
+
<literal>null</literal> return value means that type cannot
+
<emphasis><literal>f</literal></emphasis>
+
The type to merge <literal>functor</literal>.
+
Note: There is a generic <literal>defaultTypeMerge</literal>
+
that work with most of value and composed types.
+
<literal>functor</literal>
+
An attribute set representing the type. It is used for type
+
operations and has the following keys:
+
<literal>type</literal>
+
<literal>wrapped</literal>
+
Holds the type parameter for composed types.
+
<literal>payload</literal>
+
Holds the value parameter for value types. The types
+
that have a <literal>payload</literal> are the
+
<literal>enum</literal>,
+
<literal>separatedString</literal> and
+
<literal>submodule</literal> types.
+
<literal>binOp</literal>
+
A binary operation that can merge the payloads of two
+
same types. Defined as a function that take two
+
payloads as parameters and return the payloads merged.
pyrox.dev