Home Explore Blog CI



nixpkgs

5th chunk of `nixos/doc/manual/development/option-types.section.md`
b9ca2f0f0cc1f066b8269f04bcbd53680c4937afca01ff780000000100000faa
          types.attrTag {
            bounce = mkOption {
              description = "Send back a packet explaining why it wasn't forwarded.";
              type = types.submodule {
                options.errorMessage = mkOption { … };
              };
            };
            forward = mkOption {
              description = "Forward the packet.";
              type = types.submodule {
                options.destination = mkOption { … };
              };
            };
            drop = types.mkOption {
              description = "Drop the packet without sending anything back.";
              type = types.submodule {};
            };
          });
      };
      config.toyRouter.rules = {
        http = {
          bounce = {
            errorMessage = "Unencrypted HTTP is banned. You must always use https://.";
          };
        };
        ssh = { drop = {}; };
      };
    }
    ```

## 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.

`types.listOf` *`t`*

:   A list of *`t`* type, e.g. `types.listOf
          int`. Multiple definitions are merged with list concatenation.

`types.attrsOf` *`t`*

:   An attribute set of where all the values are of *`t`* type. Multiple
    definitions result in the joined attribute set.

    ::: {.note}
    This type is *strict* in its values, which in turn means attributes
    cannot depend on other attributes. See `
           types.lazyAttrsOf` for a lazy version.
    :::

`types.lazyAttrsOf` *`t`*

:   An attribute set of where all the values are of *`t`* type. Multiple
    definitions result in the joined attribute set. This is the lazy
    version of `types.attrsOf
          `, allowing attributes to depend on each other.

    ::: {.warning}
    This version does not fully support conditional definitions! With an
    option `foo` of this type and a definition
    `foo.attr = lib.mkIf false 10`, evaluating `foo ? attr` will return
    `true` even though it should be false. Accessing the value will then
    throw an error. For types *`t`* that have an `emptyValue` defined,
    that value will be returned instead of throwing an error. So if the
    type of `foo.attr` was `lazyAttrsOf (nullOr int)`, `null` would be
    returned instead for the same `mkIf false` definition.
    :::

`types.attrsWith` { *`elemType`*, *`lazy`* ? false, *`placeholder`* ? "name" }

:   An attribute set of where all the values are of *`elemType`* type.

    **Parameters**

    `elemType` (Required)
    : Specifies the type of the values contained in the attribute set.

    `lazy`
    : Determines whether the attribute set is lazily evaluated. See: `types.lazyAttrsOf`

    `placeholder` (`String`, default: `name` )
    : Placeholder string in documentation for the attribute names.
      The default value `name` results in the placeholder `<name>`

    **Behavior**

    - `attrsWith { elemType = t; }` is equivalent to `attrsOf t`
    - `attrsWith { lazy = true; elemType = t; }` is equivalent to `lazyAttrsOf t`
    - `attrsWith { placeholder = "id"; elemType = t; }`

      Displays the option as `foo.<id>` in the manual.


`types.uniq` *`t`*

:   Ensures that type *`t`* cannot be merged. It is used to ensure option
    definitions are provided only once.

`types.unique` `{ message = m }` *`t`*

:   Ensures that type *`t`* cannot be merged. Prints the message *`m`*, after
    the line `The option <option path> is defined multiple times.` and before
    a list of definition locations.

`types.coercedTo` *`from f to`*

:   Type *`to`* or type *`from`* which will be coerced to type *`to`* using
    function *`f`* which takes an argument of type *`from`* and return a
    value of type *`to`*. Can be used to preserve backwards compatibility
    of an option if its type was changed.

## Submodule {#section-option-types-submodule}

`submodule` is a very powerful type that defines a set of sub-options

Title: Option Types: Composed Types, Unique Types, Coerced Types, and Submodules
Summary
This section details composed option types, including `types.listOf`, `types.attrsOf`, `types.lazyAttrsOf`, and `types.attrsWith`, which take a type as a parameter to define lists or attribute sets with specific value types. It also covers `types.uniq` and `types.unique` for ensuring options are defined only once and `types.coercedTo` for preserving backward compatibility. Finally, it introduces `submodule`, a type used to define a set of sub-options.