nixos/doc/option-types: refactor, document number
s
This commit is contained in:
parent
77307fcff8
commit
5480f45f63
|
@ -4,7 +4,7 @@ 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.
|
||||
|
||||
## Basic Types {#sec-option-types-basic}
|
||||
## Basic types {#sec-option-types-basic}
|
||||
|
||||
Basic types are the simplest available types in the module system. Basic
|
||||
types include multiple string types that mainly differ in how definition
|
||||
|
@ -25,6 +25,11 @@ merging is handled.
|
|||
: A top-level store path. This can be an attribute set pointing
|
||||
to a store path, like a derivation or a flake input.
|
||||
|
||||
`types.enum` *`l`*
|
||||
|
||||
: One element of the list *`l`*, e.g. `types.enum [ "left" "right" ]`.
|
||||
Multiple definitions cannot be merged.
|
||||
|
||||
`types.anything`
|
||||
|
||||
: A type that accepts any value and recursively merges attribute sets
|
||||
|
@ -95,7 +100,7 @@ merging is handled.
|
|||
problems.
|
||||
:::
|
||||
|
||||
Integer-related types:
|
||||
### Numeric types {#sec-option-types-numeric}
|
||||
|
||||
`types.int`
|
||||
|
||||
|
@ -118,6 +123,10 @@ Integer-related types:
|
|||
from 0 to 2^n−1 respectively (e.g. `0`
|
||||
to `255` for 8 bits).
|
||||
|
||||
`types.ints.between` *`lowest highest`*
|
||||
|
||||
: An integer between *`lowest`* and *`highest`* (both inclusive).
|
||||
|
||||
`types.ints.positive`
|
||||
|
||||
: A positive integer (that is > 0).
|
||||
|
@ -127,12 +136,39 @@ Integer-related types:
|
|||
: A port number. This type is an alias to
|
||||
`types.ints.u16`.
|
||||
|
||||
String-related types:
|
||||
`types.float`
|
||||
|
||||
: A floating point number.
|
||||
|
||||
`types.number`
|
||||
|
||||
: Either a signed integer or a floating point number. No implicit conversion
|
||||
is done between the two types, and multiple equal definitions will only be
|
||||
merged if they have the same type.
|
||||
|
||||
`types.numbers.between` *`lowest highest`*
|
||||
|
||||
: An integer or floating point number between *`lowest`* and *`highest`* (both inclusive).
|
||||
|
||||
`types.numbers.nonnegative`
|
||||
|
||||
: A nonnegative integer or floating point number (that is >= 0).
|
||||
|
||||
`types.numbers.positive`
|
||||
|
||||
: A positive integer or floating point number (that is > 0).
|
||||
|
||||
### String types {#sec-option-types-string}
|
||||
|
||||
`types.str`
|
||||
|
||||
: A string. Multiple definitions cannot be merged.
|
||||
|
||||
`types.separatedString` *`sep`*
|
||||
|
||||
: A string. Multiple definitions are concatenated with *`sep`*, e.g.
|
||||
`types.separatedString "|"`.
|
||||
|
||||
`types.lines`
|
||||
|
||||
: A string. Multiple definitions are concatenated with a new line
|
||||
|
@ -144,7 +180,7 @@ String-related types:
|
|||
|
||||
`types.envVar`
|
||||
|
||||
: A string. Multiple definitions are concatenated with a collon `":"`.
|
||||
: A string. Multiple definitions are concatenated with a colon `":"`.
|
||||
|
||||
`types.strMatching`
|
||||
|
||||
|
@ -152,24 +188,9 @@ String-related types:
|
|||
definitions cannot be merged. The regular expression is processed
|
||||
using `builtins.match`.
|
||||
|
||||
## Value Types {#sec-option-types-value}
|
||||
## Submodule types {#sec-option-types-submodule}
|
||||
|
||||
Value types are types that take a value parameter.
|
||||
|
||||
`types.enum` *`l`*
|
||||
|
||||
: One element of the list *`l`*, e.g. `types.enum [ "left" "right" ]`.
|
||||
Multiple definitions cannot be merged.
|
||||
|
||||
`types.separatedString` *`sep`*
|
||||
|
||||
: A string with a custom separator *`sep`*, e.g.
|
||||
`types.separatedString "|"`.
|
||||
|
||||
`types.ints.between` *`lowest highest`*
|
||||
|
||||
: An integer between *`lowest`* and *`highest`* (both inclusive). Useful
|
||||
for creating types like `types.port`.
|
||||
Submodules are detailed in [Submodule](#section-option-types-submodule).
|
||||
|
||||
`types.submodule` *`o`*
|
||||
|
||||
|
@ -178,7 +199,6 @@ Value types are types that take a value parameter.
|
|||
value. Submodules are used in composed types to create modular
|
||||
options. This is equivalent to
|
||||
`types.submoduleWith { modules = toList o; shorthandOnlyDefinesConfig = true; }`.
|
||||
Submodules are detailed in [Submodule](#section-option-types-submodule).
|
||||
|
||||
`types.submoduleWith` { *`modules`*, *`specialArgs`* ? {}, *`shorthandOnlyDefinesConfig`* ? false }
|
||||
|
||||
|
@ -239,7 +259,7 @@ Value types are types that take a value parameter.
|
|||
more convenient and discoverable than expecting the module user to
|
||||
type-merge with the `attrsOf submodule` option.
|
||||
|
||||
## Composed Types {#sec-option-types-composed}
|
||||
## Composed types {#sec-option-types-composed}
|
||||
|
||||
Composed types are types that take a type as parameter. `listOf
|
||||
int` and `either int str` are examples of composed types.
|
||||
|
@ -496,7 +516,7 @@ Types are mainly characterized by their `check` and `merge` functions.
|
|||
of strings, and `defs` the list of defined values as a list. It is
|
||||
possible to override a type merge function for custom needs.
|
||||
|
||||
## Custom Types {#sec-option-types-custom}
|
||||
## Custom types {#sec-option-types-custom}
|
||||
|
||||
Custom types can be created with the `mkOptionType` function. As type
|
||||
creation includes some more complex topics such as submodule handling,
|
||||
|
|
|
@ -6,7 +6,7 @@
|
|||
in case of multiple value definitions.
|
||||
</para>
|
||||
<section xml:id="sec-option-types-basic">
|
||||
<title>Basic Types</title>
|
||||
<title>Basic types</title>
|
||||
<para>
|
||||
Basic types are the simplest available types in the module system.
|
||||
Basic types include multiple string types that mainly differ in
|
||||
|
@ -49,6 +49,20 @@
|
|||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.enum</literal>
|
||||
<emphasis><literal>l</literal></emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
One element of the list
|
||||
<emphasis><literal>l</literal></emphasis>, e.g.
|
||||
<literal>types.enum [ "left" "right" ]</literal>.
|
||||
Multiple definitions cannot be merged.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.anything</literal>
|
||||
|
@ -150,186 +164,232 @@
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>
|
||||
Integer-related types:
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.int</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A signed integer.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.ints.{s8, s16, s32}</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
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
|
||||
bits).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.ints.unsigned</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
An unsigned integer (that is >= 0).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.ints.{u8, u16, u32}</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
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).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.ints.positive</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A positive integer (that is > 0).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.port</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A port number. This type is an alias to
|
||||
<literal>types.ints.u16</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>
|
||||
String-related types:
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.str</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string. Multiple definitions cannot be merged.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.lines</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string. Multiple definitions are concatenated with a new
|
||||
line <literal>"\n"</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.commas</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string. Multiple definitions are concatenated with a comma
|
||||
<literal>","</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.envVar</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string. Multiple definitions are concatenated with a
|
||||
collon <literal>":"</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.strMatching</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string matching a specific regular expression. Multiple
|
||||
definitions cannot be merged. The regular expression is
|
||||
processed using <literal>builtins.match</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<section xml:id="sec-option-types-numeric">
|
||||
<title>Numeric types</title>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.int</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A signed integer.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.ints.{s8, s16, s32}</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
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
|
||||
bits).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.ints.unsigned</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
An unsigned integer (that is >= 0).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.ints.{u8, u16, u32}</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
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).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.ints.between</literal>
|
||||
<emphasis><literal>lowest highest</literal></emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
An integer between
|
||||
<emphasis><literal>lowest</literal></emphasis> and
|
||||
<emphasis><literal>highest</literal></emphasis> (both
|
||||
inclusive).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.ints.positive</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A positive integer (that is > 0).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.port</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A port number. This type is an alias to
|
||||
<literal>types.ints.u16</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.float</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A floating point number.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.number</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Either a signed integer or a floating point number. No
|
||||
implicit conversion is done between the two types, and
|
||||
multiple equal definitions will only be merged if they
|
||||
have the same type.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.numbers.between</literal>
|
||||
<emphasis><literal>lowest highest</literal></emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
An integer or floating point number between
|
||||
<emphasis><literal>lowest</literal></emphasis> and
|
||||
<emphasis><literal>highest</literal></emphasis> (both
|
||||
inclusive).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.numbers.nonnegative</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A nonnegative integer or floating point number (that is
|
||||
>= 0).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.numbers.positive</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A positive integer or floating point number (that is >
|
||||
0).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</section>
|
||||
<section xml:id="sec-option-types-string">
|
||||
<title>String types</title>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.str</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string. Multiple definitions cannot be merged.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.separatedString</literal>
|
||||
<emphasis><literal>sep</literal></emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string. Multiple definitions are concatenated with
|
||||
<emphasis><literal>sep</literal></emphasis>, e.g.
|
||||
<literal>types.separatedString "|"</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.lines</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string. Multiple definitions are concatenated with a new
|
||||
line <literal>"\n"</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.commas</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string. Multiple definitions are concatenated with a
|
||||
comma <literal>","</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.envVar</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string. Multiple definitions are concatenated with a
|
||||
colon <literal>":"</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.strMatching</literal>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string matching a specific regular expression. Multiple
|
||||
definitions cannot be merged. The regular expression is
|
||||
processed using <literal>builtins.match</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="sec-option-types-value">
|
||||
<title>Value Types</title>
|
||||
<section xml:id="sec-option-types-submodule">
|
||||
<title>Submodule types</title>
|
||||
<para>
|
||||
Value types are types that take a value parameter.
|
||||
Submodules are detailed in
|
||||
<link linkend="section-option-types-submodule">Submodule</link>.
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.enum</literal>
|
||||
<emphasis><literal>l</literal></emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
One element of the list
|
||||
<emphasis><literal>l</literal></emphasis>, e.g.
|
||||
<literal>types.enum [ "left" "right" ]</literal>.
|
||||
Multiple definitions cannot be merged.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.separatedString</literal>
|
||||
<emphasis><literal>sep</literal></emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A string with a custom separator
|
||||
<emphasis><literal>sep</literal></emphasis>, e.g.
|
||||
<literal>types.separatedString "|"</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.ints.between</literal>
|
||||
<emphasis><literal>lowest highest</literal></emphasis>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
An integer between
|
||||
<emphasis><literal>lowest</literal></emphasis> and
|
||||
<emphasis><literal>highest</literal></emphasis> (both
|
||||
inclusive). Useful for creating types like
|
||||
<literal>types.port</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<literal>types.submodule</literal>
|
||||
|
@ -345,8 +405,6 @@
|
|||
in composed types to create modular options. This is
|
||||
equivalent to
|
||||
<literal>types.submoduleWith { modules = toList o; shorthandOnlyDefinesConfig = true; }</literal>.
|
||||
Submodules are detailed in
|
||||
<link linkend="section-option-types-submodule">Submodule</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
@ -467,7 +525,7 @@
|
|||
</variablelist>
|
||||
</section>
|
||||
<section xml:id="sec-option-types-composed">
|
||||
<title>Composed Types</title>
|
||||
<title>Composed types</title>
|
||||
<para>
|
||||
Composed types are types that take a type as parameter.
|
||||
<literal>listOf int</literal> and
|
||||
|
@ -850,7 +908,7 @@ nixThings = mkOption {
|
|||
</variablelist>
|
||||
</section>
|
||||
<section xml:id="sec-option-types-custom">
|
||||
<title>Custom Types</title>
|
||||
<title>Custom types</title>
|
||||
<para>
|
||||
Custom types can be created with the
|
||||
<literal>mkOptionType</literal> function. As type creation
|
||||
|
|
Loading…
Reference in a new issue