diff options
author | Naïm Favier <n@monade.li> | 2022-07-25 11:19:06 +0200 |
---|---|---|
committer | Naïm Favier <n@monade.li> | 2022-07-25 11:19:06 +0200 |
commit | 5480f45f63f75d9340d5d48602f47d04d3625a2f (patch) | |
tree | 07948fb2b07f8b4fa7be1ecf55f74b753f18330b /nixos | |
parent | 77307fcff86d3e56285b006b3e9204c6b45d90f0 (diff) | |
download | nixlib-5480f45f63f75d9340d5d48602f47d04d3625a2f.tar nixlib-5480f45f63f75d9340d5d48602f47d04d3625a2f.tar.gz nixlib-5480f45f63f75d9340d5d48602f47d04d3625a2f.tar.bz2 nixlib-5480f45f63f75d9340d5d48602f47d04d3625a2f.tar.lz nixlib-5480f45f63f75d9340d5d48602f47d04d3625a2f.tar.xz nixlib-5480f45f63f75d9340d5d48602f47d04d3625a2f.tar.zst nixlib-5480f45f63f75d9340d5d48602f47d04d3625a2f.zip |
nixos/doc/option-types: refactor, document `number`s
Diffstat (limited to 'nixos')
-rw-r--r-- | nixos/doc/manual/development/option-types.section.md | 68 | ||||
-rw-r--r-- | nixos/doc/manual/from_md/development/option-types.section.xml | 420 |
2 files changed, 283 insertions, 205 deletions
diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md index 9b35e6630144..7864b62605c2 100644 --- a/nixos/doc/manual/development/option-types.section.md +++ b/nixos/doc/manual/development/option-types.section.md @@ -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} - -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`* +## Submodule types {#sec-option-types-submodule} -: 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, diff --git a/nixos/doc/manual/from_md/development/option-types.section.xml b/nixos/doc/manual/from_md/development/option-types.section.xml index 929d5302ed41..e207b97a46f8 100644 --- a/nixos/doc/manual/from_md/development/option-types.section.xml +++ b/nixos/doc/manual/from_md/development/option-types.section.xml @@ -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 @@ -51,6 +51,20 @@ </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> </term> <listitem> @@ -150,188 +164,234 @@ </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> <emphasis><literal>o</literal></emphasis> </term> @@ -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 |