lib/types.nix

   1 # Definitions related to run-time type checking.  Used in particular
   2 # to type-check NixOS configurations.
   3 { lib }:
   4
   5 let
   6   inherit (lib)
   7     elem
   8     flip
   9     isAttrs
  10     isBool
  11     isDerivation
  12     isFloat
  13     isFunction
  14     isInt
  15     isList
  16     isString
  17     isStorePath
  18     toDerivation
  19     toList
  20     ;
  21   inherit (lib.lists)
  22     all
  23     concatLists
  24     count
  25     elemAt
  26     filter
  27     foldl'
  28     head
  29     imap1
  30     last
  31     length
  32     tail
  33     ;
  34   inherit (lib.attrsets)
  35     attrNames
  36     filterAttrs
  37     hasAttr
  38     mapAttrs
  39     optionalAttrs
  40     zipAttrsWith
  41     ;
  42   inherit (lib.options)
  43     getFiles
  44     getValues
  45     mergeDefaultOption
  46     mergeEqualOption
  47     mergeOneOption
  48     mergeUniqueOption
  49     showFiles
  50     showOption
  51     ;
  52   inherit (lib.strings)
  53     concatMapStringsSep
  54     concatStringsSep
  55     escapeNixString
  56     hasInfix
  57     isStringLike
  58     ;
  59   inherit (lib.trivial)
  60     boolToString
  61     ;
  62
  63   inherit (lib.modules)
  64     mergeDefinitions
  65     fixupOptionType
  66     mergeOptionDecls
  67     ;
  68   outer_types =
  69 rec {
  70   __attrsFailEvaluation = true;
  71   isType = type: x: (x._type or "") == type;
  72
  73   setType = typeName: value: value // {
  74     _type = typeName;
  75   };
  76
  77
  78   # Default type merging function
  79   # takes two type functors and return the merged type
  80   defaultTypeMerge = f: f':
  81     let wrapped = f.wrapped.typeMerge f'.wrapped.functor;
  82         payload = f.binOp f.payload f'.payload;
  83     in
  84     # cannot merge different types
  85     if f.name != f'.name
  86        then null
  87     # simple types
  88     else if    (f.wrapped == null && f'.wrapped == null)
  89             && (f.payload == null && f'.payload == null)
  90        then f.type
  91     # composed types
  92     else if (f.wrapped != null && f'.wrapped != null) && (wrapped != null)
  93        then f.type wrapped
  94     # value types
  95     else if (f.payload != null && f'.payload != null) && (payload != null)
  96        then f.type payload
  97     else null;
  98
  99   # Default type functor
 100   defaultFunctor = name: {
 101     inherit name;
 102     type    = types.${name} or null;
 103     wrapped = null;
 104     payload = null;
 105     binOp   = a: b: null;
 106   };
 107
 108   isOptionType = isType "option-type";
 109   mkOptionType =
 110     { # Human-readable representation of the type, should be equivalent to
 111       # the type function name.
 112       name
 113     , # Description of the type, defined recursively by embedding the wrapped type if any.
 114       description ? null
 115       # A hint for whether or not this description needs parentheses. Possible values:
 116       #  - "noun": a noun phrase
 117       #    Example description: "positive integer",
 118       #  - "conjunction": a phrase with a potentially ambiguous "or" connective
 119       #    Example description: "int or string"
 120       #  - "composite": a phrase with an "of" connective
 121       #    Example description: "list of string"
 122       #  - "nonRestrictiveClause": a noun followed by a comma and a clause
 123       #    Example description: "positive integer, meaning >0"
 124       # See the `optionDescriptionPhrase` function.
 125     , descriptionClass ? null
 126     , # DO NOT USE WITHOUT KNOWING WHAT YOU ARE DOING!
 127       # Function applied to each definition that must return false when a definition
 128       # does not match the type. It should not check more than the root of the value,
 129       # because checking nested values reduces laziness, leading to unnecessary
 130       # infinite recursions in the module system.
 131       # Further checks of nested values should be performed by throwing in
 132       # the merge function.
 133       # Strict and deep type checking can be performed by calling lib.deepSeq on
 134       # the merged value.
 135       #
 136       # See https://github.com/NixOS/nixpkgs/pull/6794 that introduced this change,
 137       # https://github.com/NixOS/nixpkgs/pull/173568 and
 138       # https://github.com/NixOS/nixpkgs/pull/168295 that attempted to revert this,
 139       # https://github.com/NixOS/nixpkgs/issues/191124 and
 140       # https://github.com/NixOS/nixos-search/issues/391 for what happens if you ignore
 141       # this disclaimer.
 142       check ? (x: true)
 143     , # Merge a list of definitions together into a single value.
 144       # This function is called with two arguments: the location of
 145       # the option in the configuration as a list of strings
 146       # (e.g. ["boot" "loader "grub" "enable"]), and a list of
 147       # definition values and locations (e.g. [ { file = "/foo.nix";
 148       # value = 1; } { file = "/bar.nix"; value = 2 } ]).
 149       merge ? mergeDefaultOption
 150     , # Whether this type has a value representing nothingness. If it does,
 151       # this should be a value of the form { value = <the nothing value>; }
 152       # If it doesn't, this should be {}
 153       # This may be used when a value is required for `mkIf false`. This allows the extra laziness in e.g. `lazyAttrsOf`.
 154       emptyValue ? {}
 155     , # Return a flat list of sub-options.  Used to generate
 156       # documentation.
 157       getSubOptions ? prefix: {}
 158     , # List of modules if any, or null if none.
 159       getSubModules ? null
 160     , # Function for building the same option type with a different list of
 161       # modules.
 162       substSubModules ? m: null
 163     , # Function that merge type declarations.
 164       # internal, takes a functor as argument and returns the merged type.
 165       # returning null means the type is not mergeable
 166       typeMerge ? defaultTypeMerge functor
 167     , # The type functor.
 168       # internal, representation of the type as an attribute set.
 169       #   name: name of the type
 170       #   type: type function.
 171       #   wrapped: the type wrapped in case of compound types.
 172       #   payload: values of the type, two payloads of the same type must be
 173       #            combinable with the binOp binary operation.
 174       #   binOp: binary operation that merge two payloads of the same type.
 175       functor ? defaultFunctor name
 176     , # The deprecation message to display when this type is used by an option
 177       # If null, the type isn't deprecated
 178       deprecationMessage ? null
 179     , # The types that occur in the definition of this type. This is used to
 180       # issue deprecation warnings recursively. Can also be used to reuse
 181       # nested types
 182       nestedTypes ? {}
 183     }:
 184     { _type = "option-type";
 185       inherit
 186         name check merge emptyValue getSubOptions getSubModules substSubModules
 187         typeMerge functor deprecationMessage nestedTypes descriptionClass;
 188       description = if description == null then name else description;
 189     };
 190
 191   # optionDescriptionPhrase :: (str -> bool) -> optionType -> str
 192   #
 193   # Helper function for producing unambiguous but readable natural language
 194   # descriptions of types.
 195   #
 196   # Parameters
 197   #
 198   #     optionDescriptionPhase unparenthesize optionType
 199   #
 200   # `unparenthesize`: A function from descriptionClass string to boolean.
 201   #   It must return true when the class of phrase will fit unambiguously into
 202   #   the description of the caller.
 203   #
 204   # `optionType`: The option type to parenthesize or not.
 205   #   The option whose description we're returning.
 206   #
 207   # Return value
 208   #
 209   # The description of the `optionType`, with parentheses if there may be an
 210   # ambiguity.
 211   optionDescriptionPhrase = unparenthesize: t:
 212     if unparenthesize (t.descriptionClass or null)
 213     then t.description
 214     else "(${t.description})";
 215
 216   # When adding new types don't forget to document them in
 217   # nixos/doc/manual/development/option-types.xml!
 218   types = rec {
 219
 220     raw = mkOptionType {
 221       name = "raw";
 222       description = "raw value";
 223       descriptionClass = "noun";
 224       check = value: true;
 225       merge = mergeOneOption;
 226     };
 227
 228     anything = mkOptionType {
 229       name = "anything";
 230       description = "anything";
 231       descriptionClass = "noun";
 232       check = value: true;
 233       merge = loc: defs:
 234         let
 235           getType = value:
 236             if isAttrs value && isStringLike value
 237             then "stringCoercibleSet"
 238             else builtins.typeOf value;
 239
 240           # Returns the common type of all definitions, throws an error if they
 241           # don't have the same type
 242           commonType = foldl' (type: def:
 243             if getType def.value == type
 244             then type
 245             else throw "The option `${showOption loc}' has conflicting option types in ${showFiles (getFiles defs)}"
 246           ) (getType (head defs).value) defs;
 247
 248           mergeFunction = {
 249             # Recursively merge attribute sets
 250             set = (attrsOf anything).merge;
 251             # Safe and deterministic behavior for lists is to only accept one definition
 252             # listOf only used to apply mkIf and co.
 253             list =
 254               if length defs > 1
 255               then throw "The option `${showOption loc}' has conflicting definitions, in ${showFiles (getFiles defs)}."
 256               else (listOf anything).merge;
 257             # This is the type of packages, only accept a single definition
 258             stringCoercibleSet = mergeOneOption;
 259             lambda = loc: defs: arg: anything.merge
 260               (loc ++ [ "<function body>" ])
 261               (map (def: {
 262                 file = def.file;
 263                 value = def.value arg;
 264               }) defs);
 265             # Otherwise fall back to only allowing all equal definitions
 266           }.${commonType} or mergeEqualOption;
 267         in mergeFunction loc defs;
 268     };
 269
 270     unspecified = mkOptionType {
 271       name = "unspecified";
 272       description = "unspecified value";
 273       descriptionClass = "noun";
 274     };
 275
 276     bool = mkOptionType {
 277       name = "bool";
 278       description = "boolean";
 279       descriptionClass = "noun";
 280       check = isBool;
 281       merge = mergeEqualOption;
 282     };
 283
 284     boolByOr = mkOptionType {
 285       name = "boolByOr";
 286       description = "boolean (merged using or)";
 287       descriptionClass = "noun";
 288       check = isBool;
 289       merge = loc: defs:
 290         foldl'
 291           (result: def:
 292             # Under the assumption that .check always runs before merge, we can assume that all defs.*.value
 293             # have been forced, and therefore we assume we don't introduce order-dependent strictness here
 294             result || def.value
 295           )
 296           false
 297           defs;
 298     };
 299
 300     int = mkOptionType {
 301       name = "int";
 302       description = "signed integer";
 303       descriptionClass = "noun";
 304       check = isInt;
 305       merge = mergeEqualOption;
 306     };
 307
 308     # Specialized subdomains of int
 309     ints =
 310       let
 311         betweenDesc = lowest: highest:
 312           "${toString lowest} and ${toString highest} (both inclusive)";
 313         between = lowest: highest:
 314           assert lib.assertMsg (lowest <= highest)
 315             "ints.between: lowest must be smaller than highest";
 316           addCheck int (x: x >= lowest && x <= highest) // {
 317             name = "intBetween";
 318             description = "integer between ${betweenDesc lowest highest}";
 319           };
 320         ign = lowest: highest: name: docStart:
 321           between lowest highest // {
 322             inherit name;
 323             description = docStart + "; between ${betweenDesc lowest highest}";
 324           };
 325         unsign = bit: range: ign 0 (range - 1)
 326           "unsignedInt${toString bit}" "${toString bit} bit unsigned integer";
 327         sign = bit: range: ign (0 - (range / 2)) (range / 2 - 1)
 328           "signedInt${toString bit}" "${toString bit} bit signed integer";
 329
 330       in {
 331         /* An int with a fixed range.
 332         *
 333         * Example:
 334         *   (ints.between 0 100).check (-1)
 335         *   => false
 336         *   (ints.between 0 100).check (101)
 337         *   => false
 338         *   (ints.between 0 0).check 0
 339         *   => true
 340         */
 341         inherit between;
 342
 343         unsigned = addCheck types.int (x: x >= 0) // {
 344           name = "unsignedInt";
 345           description = "unsigned integer, meaning >=0";
 346           descriptionClass = "nonRestrictiveClause";
 347         };
 348         positive = addCheck types.int (x: x > 0) // {
 349           name = "positiveInt";
 350           description = "positive integer, meaning >0";
 351           descriptionClass = "nonRestrictiveClause";
 352         };
 353         u8 = unsign 8 256;
 354         u16 = unsign 16 65536;
 355         # the biggest int Nix accepts is 2^63 - 1 (9223372036854775808)
 356         # the smallest int Nix accepts is -2^63 (-9223372036854775807)
 357         u32 = unsign 32 4294967296;
 358         # u64 = unsign 64 18446744073709551616;
 359
 360         s8 = sign 8 256;
 361         s16 = sign 16 65536;
 362         s32 = sign 32 4294967296;
 363       };
 364
 365     # Alias of u16 for a port number
 366     port = ints.u16;
 367
 368     float = mkOptionType {
 369       name = "float";
 370       description = "floating point number";
 371       descriptionClass = "noun";
 372       check = isFloat;
 373       merge = mergeEqualOption;
 374     };
 375
 376     number = either int float;
 377
 378     numbers = let
 379       betweenDesc = lowest: highest:
 380         "${builtins.toJSON lowest} and ${builtins.toJSON highest} (both inclusive)";
 381     in {
 382       between = lowest: highest:
 383         assert lib.assertMsg (lowest <= highest)
 384           "numbers.between: lowest must be smaller than highest";
 385         addCheck number (x: x >= lowest && x <= highest) // {
 386           name = "numberBetween";
 387           description = "integer or floating point number between ${betweenDesc lowest highest}";
 388         };
 389
 390       nonnegative = addCheck number (x: x >= 0) // {
 391         name = "numberNonnegative";
 392         description = "nonnegative integer or floating point number, meaning >=0";
 393         descriptionClass = "nonRestrictiveClause";
 394       };
 395       positive = addCheck number (x: x > 0) // {
 396         name = "numberPositive";
 397         description = "positive integer or floating point number, meaning >0";
 398         descriptionClass = "nonRestrictiveClause";
 399       };
 400     };
 401
 402     str = mkOptionType {
 403       name = "str";
 404       description = "string";
 405       descriptionClass = "noun";
 406       check = isString;
 407       merge = mergeEqualOption;
 408     };
 409
 410     nonEmptyStr = mkOptionType {
 411       name = "nonEmptyStr";
 412       description = "non-empty string";
 413       descriptionClass = "noun";
 414       check = x: str.check x && builtins.match "[ \t\n]*" x == null;
 415       inherit (str) merge;
 416     };
 417
 418     # Allow a newline character at the end and trim it in the merge function.
 419     singleLineStr =
 420       let
 421         inherit (strMatching "[^\n\r]*\n?") check merge;
 422       in
 423       mkOptionType {
 424         name = "singleLineStr";
 425         description = "(optionally newline-terminated) single-line string";
 426         descriptionClass = "noun";
 427         inherit check;
 428         merge = loc: defs:
 429           lib.removeSuffix "\n" (merge loc defs);
 430       };
 431
 432     strMatching = pattern: mkOptionType {
 433       name = "strMatching ${escapeNixString pattern}";
 434       description = "string matching the pattern ${pattern}";
 435       descriptionClass = "noun";
 436       check = x: str.check x && builtins.match pattern x != null;
 437       inherit (str) merge;
 438     };
 439
 440     # Merge multiple definitions by concatenating them (with the given
 441     # separator between the values).
 442     separatedString = sep: mkOptionType rec {
 443       name = "separatedString";
 444       description = if sep == ""
 445         then "Concatenated string" # for types.string.
 446         else "strings concatenated with ${builtins.toJSON sep}"
 447       ;
 448       descriptionClass = "noun";
 449       check = isString;
 450       merge = loc: defs: concatStringsSep sep (getValues defs);
 451       functor = (defaultFunctor name) // {
 452         payload = sep;
 453         binOp = sepLhs: sepRhs:
 454           if sepLhs == sepRhs then sepLhs
 455           else null;
 456       };
 457     };
 458
 459     lines = separatedString "\n";
 460     commas = separatedString ",";
 461     envVar = separatedString ":";
 462
 463     # Deprecated; should not be used because it quietly concatenates
 464     # strings, which is usually not what you want.
 465     # We use a lib.warn because `deprecationMessage` doesn't trigger in nested types such as `attrsOf string`
 466     string = lib.warn
 467       "The type `types.string` is deprecated. See https://github.com/NixOS/nixpkgs/pull/66346 for better alternative types."
 468       (separatedString "" // {
 469         name = "string";
 470       });
 471
 472     passwdEntry = entryType: addCheck entryType (str: !(hasInfix ":" str || hasInfix "\n" str)) // {
 473       name = "passwdEntry ${entryType.name}";
 474       description = "${optionDescriptionPhrase (class: class == "noun") entryType}, not containing newlines or colons";
 475       descriptionClass = "nonRestrictiveClause";
 476     };
 477
 478     attrs = mkOptionType {
 479       name = "attrs";
 480       description = "attribute set";
 481       check = isAttrs;
 482       merge = loc: foldl' (res: def: res // def.value) {};
 483       emptyValue = { value = {}; };
 484     };
 485
 486     # A package is a top-level store path (/nix/store/hash-name). This includes:
 487     # - derivations
 488     # - more generally, attribute sets with an `outPath` or `__toString` attribute
 489     #   pointing to a store path, e.g. flake inputs
 490     # - strings with context, e.g. "${pkgs.foo}" or (toString pkgs.foo)
 491     # - hardcoded store path literals (/nix/store/hash-foo) or strings without context
 492     #   ("/nix/store/hash-foo"). These get a context added to them using builtins.storePath.
 493     # If you don't need a *top-level* store path, consider using pathInStore instead.
 494     package = mkOptionType {
 495       name = "package";
 496       descriptionClass = "noun";
 497       check = x: isDerivation x || isStorePath x;
 498       merge = loc: defs:
 499         let res = mergeOneOption loc defs;
 500         in if builtins.isPath res || (builtins.isString res && ! builtins.hasContext res)
 501           then toDerivation res
 502           else res;
 503     };
 504
 505     shellPackage = package // {
 506       check = x: isDerivation x && hasAttr "shellPath" x;
 507     };
 508
 509     pkgs = addCheck
 510       (unique { message = "A Nixpkgs pkgs set can not be merged with another pkgs set."; } attrs // {
 511         name = "pkgs";
 512         descriptionClass = "noun";
 513         description = "Nixpkgs package set";
 514       })
 515       (x: (x._type or null) == "pkgs");
 516
 517     path = mkOptionType {
 518       name = "path";
 519       descriptionClass = "noun";
 520       check = x: isStringLike x && builtins.substring 0 1 (toString x) == "/";
 521       merge = mergeEqualOption;
 522     };
 523
 524     pathInStore = mkOptionType {
 525       name = "pathInStore";
 526       description = "path in the Nix store";
 527       descriptionClass = "noun";
 528       check = x: isStringLike x && builtins.match "${builtins.storeDir}/[^.].*" (toString x) != null;
 529       merge = mergeEqualOption;
 530     };
 531
 532     listOf = elemType: mkOptionType rec {
 533       name = "listOf";
 534       description = "list of ${optionDescriptionPhrase (class: class == "noun" || class == "composite") elemType}";
 535       descriptionClass = "composite";
 536       check = isList;
 537       merge = loc: defs:
 538         map (x: x.value) (filter (x: x ? value) (concatLists (imap1 (n: def:
 539           imap1 (m: def':
 540             (mergeDefinitions
 541               (loc ++ ["[definition ${toString n}-entry ${toString m}]"])
 542               elemType
 543               [{ inherit (def) file; value = def'; }]
 544             ).optionalValue
 545           ) def.value
 546         ) defs)));
 547       emptyValue = { value = []; };
 548       getSubOptions = prefix: elemType.getSubOptions (prefix ++ ["*"]);
 549       getSubModules = elemType.getSubModules;
 550       substSubModules = m: listOf (elemType.substSubModules m);
 551       functor = (defaultFunctor name) // { wrapped = elemType; };
 552       nestedTypes.elemType = elemType;
 553     };
 554
 555     nonEmptyListOf = elemType:
 556       let list = addCheck (types.listOf elemType) (l: l != []);
 557       in list // {
 558         description = "non-empty ${optionDescriptionPhrase (class: class == "noun") list}";
 559         emptyValue = { }; # no .value attr, meaning unset
 560         substSubModules = m: nonEmptyListOf (elemType.substSubModules m);
 561       };
 562
 563     attrsOf = elemType: mkOptionType rec {
 564       name = "attrsOf";
 565       description = "attribute set of ${optionDescriptionPhrase (class: class == "noun" || class == "composite") elemType}";
 566       descriptionClass = "composite";
 567       check = isAttrs;
 568       merge = loc: defs:
 569         mapAttrs (n: v: v.value) (filterAttrs (n: v: v ? value) (zipAttrsWith (name: defs:
 570             (mergeDefinitions (loc ++ [name]) elemType defs).optionalValue
 571           )
 572           # Push down position info.
 573           (map (def: mapAttrs (n: v: { inherit (def) file; value = v; }) def.value) defs)));
 574       emptyValue = { value = {}; };
 575       getSubOptions = prefix: elemType.getSubOptions (prefix ++ ["<name>"]);
 576       getSubModules = elemType.getSubModules;
 577       substSubModules = m: attrsOf (elemType.substSubModules m);
 578       functor = (defaultFunctor name) // { wrapped = elemType; };
 579       nestedTypes.elemType = elemType;
 580     };
 581
 582     # A version of attrsOf that's lazy in its values at the expense of
 583     # conditional definitions not working properly. E.g. defining a value with
 584     # `foo.attr = mkIf false 10`, then `foo ? attr == true`, whereas with
 585     # attrsOf it would correctly be `false`. Accessing `foo.attr` would throw an
 586     # error that it's not defined. Use only if conditional definitions don't make sense.
 587     lazyAttrsOf = elemType: mkOptionType rec {
 588       name = "lazyAttrsOf";
 589       description = "lazy attribute set of ${optionDescriptionPhrase (class: class == "noun" || class == "composite") elemType}";
 590       descriptionClass = "composite";
 591       check = isAttrs;
 592       merge = loc: defs:
 593         zipAttrsWith (name: defs:
 594           let merged = mergeDefinitions (loc ++ [name]) elemType defs;
 595           # mergedValue will trigger an appropriate error when accessed
 596           in merged.optionalValue.value or elemType.emptyValue.value or merged.mergedValue
 597         )
 598         # Push down position info.
 599         (map (def: mapAttrs (n: v: { inherit (def) file; value = v; }) def.value) defs);
 600       emptyValue = { value = {}; };
 601       getSubOptions = prefix: elemType.getSubOptions (prefix ++ ["<name>"]);
 602       getSubModules = elemType.getSubModules;
 603       substSubModules = m: lazyAttrsOf (elemType.substSubModules m);
 604       functor = (defaultFunctor name) // { wrapped = elemType; };
 605       nestedTypes.elemType = elemType;
 606     };
 607
 608     # TODO: deprecate this in the future:
 609     loaOf = elemType: types.attrsOf elemType // {
 610       name = "loaOf";
 611       deprecationMessage = "Mixing lists with attribute values is no longer"
 612         + " possible; please use `types.attrsOf` instead. See"
 613         + " https://github.com/NixOS/nixpkgs/issues/1800 for the motivation.";
 614       nestedTypes.elemType = elemType;
 615     };
 616
 617     uniq = unique { message = ""; };
 618
 619     unique = { message }: type: mkOptionType rec {
 620       name = "unique";
 621       inherit (type) description descriptionClass check;
 622       merge = mergeUniqueOption { inherit message; inherit (type) merge; };
 623       emptyValue = type.emptyValue;
 624       getSubOptions = type.getSubOptions;
 625       getSubModules = type.getSubModules;
 626       substSubModules = m: uniq (type.substSubModules m);
 627       functor = (defaultFunctor name) // { wrapped = type; };
 628       nestedTypes.elemType = type;
 629     };
 630
 631     # Null or value of ...
 632     nullOr = elemType: mkOptionType rec {
 633       name = "nullOr";
 634       description = "null or ${optionDescriptionPhrase (class: class == "noun" || class == "conjunction") elemType}";
 635       descriptionClass = "conjunction";
 636       check = x: x == null || elemType.check x;
 637       merge = loc: defs:
 638         let nrNulls = count (def: def.value == null) defs; in
 639         if nrNulls == length defs then null
 640         else if nrNulls != 0 then
 641           throw "The option `${showOption loc}` is defined both null and not null, in ${showFiles (getFiles defs)}."
 642         else elemType.merge loc defs;
 643       emptyValue = { value = null; };
 644       getSubOptions = elemType.getSubOptions;
 645       getSubModules = elemType.getSubModules;
 646       substSubModules = m: nullOr (elemType.substSubModules m);
 647       functor = (defaultFunctor name) // { wrapped = elemType; };
 648       nestedTypes.elemType = elemType;
 649     };
 650
 651     functionTo = elemType: mkOptionType {
 652       name = "functionTo";
 653       description = "function that evaluates to a(n) ${optionDescriptionPhrase (class: class == "noun" || class == "composite") elemType}";
 654       descriptionClass = "composite";
 655       check = isFunction;
 656       merge = loc: defs:
 657         fnArgs: (mergeDefinitions (loc ++ [ "<function body>" ]) elemType (map (fn: { inherit (fn) file; value = fn.value fnArgs; }) defs)).mergedValue;
 658       getSubOptions = prefix: elemType.getSubOptions (prefix ++ [ "<function body>" ]);
 659       getSubModules = elemType.getSubModules;
 660       substSubModules = m: functionTo (elemType.substSubModules m);
 661       functor = (defaultFunctor "functionTo") // { wrapped = elemType; };
 662       nestedTypes.elemType = elemType;
 663     };
 664
 665     # A submodule (like typed attribute set). See NixOS manual.
 666     submodule = modules: submoduleWith {
 667       shorthandOnlyDefinesConfig = true;
 668       modules = toList modules;
 669     };
 670
 671     # A module to be imported in some other part of the configuration.
 672     deferredModule = deferredModuleWith { };
 673
 674     # A module to be imported in some other part of the configuration.
 675     # `staticModules`' options will be added to the documentation, unlike
 676     # options declared via `config`.
 677     deferredModuleWith = attrs@{ staticModules ? [] }: mkOptionType {
 678       name = "deferredModule";
 679       description = "module";
 680       descriptionClass = "noun";
 681       check = x: isAttrs x || isFunction x || path.check x;
 682       merge = loc: defs: {
 683         imports = staticModules ++ map (def: lib.setDefaultModuleLocation "${def.file}, via option ${showOption loc}" def.value) defs;
 684       };
 685       inherit (submoduleWith { modules = staticModules; })
 686         getSubOptions
 687         getSubModules;
 688       substSubModules = m: deferredModuleWith (attrs // {
 689         staticModules = m;
 690       });
 691       functor = defaultFunctor "deferredModuleWith" // {
 692         type = types.deferredModuleWith;
 693         payload = {
 694           inherit staticModules;
 695         };
 696         binOp = lhs: rhs: {
 697           staticModules = lhs.staticModules ++ rhs.staticModules;
 698         };
 699       };
 700     };
 701
 702     # The type of a type!
 703     optionType = mkOptionType {
 704       name = "optionType";
 705       description = "optionType";
 706       descriptionClass = "noun";
 707       check = value: value._type or null == "option-type";
 708       merge = loc: defs:
 709         if length defs == 1
 710         then (head defs).value
 711         else let
 712           # Prepares the type definitions for mergeOptionDecls, which
 713           # annotates submodules types with file locations
 714           optionModules = map ({ value, file }:
 715             {
 716               _file = file;
 717               # There's no way to merge types directly from the module system,
 718               # but we can cheat a bit by just declaring an option with the type
 719               options = lib.mkOption {
 720                 type = value;
 721               };
 722             }
 723           ) defs;
 724           # Merges all the types into a single one, including submodule merging.
 725           # This also propagates file information to all submodules
 726           mergedOption = fixupOptionType loc (mergeOptionDecls loc optionModules);
 727         in mergedOption.type;
 728     };
 729
 730     submoduleWith =
 731       { modules
 732       , specialArgs ? {}
 733       , shorthandOnlyDefinesConfig ? false
 734       , description ? null
 735       , class ? null
 736       }@attrs:
 737       let
 738         inherit (lib.modules) evalModules;
 739
 740         allModules = defs: map ({ value, file }:
 741           if isAttrs value && shorthandOnlyDefinesConfig
 742           then { _file = file; config = value; }
 743           else { _file = file; imports = [ value ]; }
 744         ) defs;
 745
 746         base = evalModules {
 747           inherit class specialArgs;
 748           modules = [{
 749             # This is a work-around for the fact that some sub-modules,
 750             # such as the one included in an attribute set, expects an "args"
 751             # attribute to be given to the sub-module. As the option
 752             # evaluation does not have any specific attribute name yet, we
 753             # provide a default for the documentation and the freeform type.
 754             #
 755             # This is necessary as some option declaration might use the
 756             # "name" attribute given as argument of the submodule and use it
 757             # as the default of option declarations.
 758             #
 759             # We use lookalike unicode single angle quotation marks because
 760             # of the docbook transformation the options receive. In all uses
 761             # &gt; and &lt; wouldn't be encoded correctly so the encoded values
 762             # would be used, and use of `<` and `>` would break the XML document.
 763             # It shouldn't cause an issue since this is cosmetic for the manual.
 764             _module.args.name = lib.mkOptionDefault "‹name›";
 765           }] ++ modules;
 766         };
 767
 768         freeformType = base._module.freeformType;
 769
 770         name = "submodule";
 771
 772       in
 773       mkOptionType {
 774         inherit name;
 775         description =
 776           if description != null then description
 777           else freeformType.description or name;
 778         check = x: isAttrs x || isFunction x || path.check x;
 779         merge = loc: defs:
 780           (base.extendModules {
 781             modules = [ { _module.args.name = last loc; } ] ++ allModules defs;
 782             prefix = loc;
 783           }).config;
 784         emptyValue = { value = {}; };
 785         getSubOptions = prefix: (base.extendModules
 786           { inherit prefix; }).options // optionalAttrs (freeformType != null) {
 787             # Expose the sub options of the freeform type. Note that the option
 788             # discovery doesn't care about the attribute name used here, so this
 789             # is just to avoid conflicts with potential options from the submodule
 790             _freeformOptions = freeformType.getSubOptions prefix;
 791           };
 792         getSubModules = modules;
 793         substSubModules = m: submoduleWith (attrs // {
 794           modules = m;
 795         });
 796         nestedTypes = lib.optionalAttrs (freeformType != null) {
 797           freeformType = freeformType;
 798         };
 799         functor = defaultFunctor name // {
 800           type = types.submoduleWith;
 801           payload = {
 802             inherit modules class specialArgs shorthandOnlyDefinesConfig description;
 803           };
 804           binOp = lhs: rhs: {
 805             class =
 806               # `or null` was added for backwards compatibility only. `class` is
 807               # always set in the current version of the module system.
 808               if lhs.class or null == null then rhs.class or null
 809               else if rhs.class or null == null then lhs.class or null
 810               else if lhs.class or null == rhs.class then lhs.class or null
 811               else throw "A submoduleWith option is declared multiple times with conflicting class values \"${toString lhs.class}\" and \"${toString rhs.class}\".";
 812             modules = lhs.modules ++ rhs.modules;
 813             specialArgs =
 814               let intersecting = builtins.intersectAttrs lhs.specialArgs rhs.specialArgs;
 815               in if intersecting == {}
 816               then lhs.specialArgs // rhs.specialArgs
 817               else throw "A submoduleWith option is declared multiple times with the same specialArgs \"${toString (attrNames intersecting)}\"";
 818             shorthandOnlyDefinesConfig =
 819               if lhs.shorthandOnlyDefinesConfig == null
 820               then rhs.shorthandOnlyDefinesConfig
 821               else if rhs.shorthandOnlyDefinesConfig == null
 822               then lhs.shorthandOnlyDefinesConfig
 823               else if lhs.shorthandOnlyDefinesConfig == rhs.shorthandOnlyDefinesConfig
 824               then lhs.shorthandOnlyDefinesConfig
 825               else throw "A submoduleWith option is declared multiple times with conflicting shorthandOnlyDefinesConfig values";
 826             description =
 827               if lhs.description == null
 828               then rhs.description
 829               else if rhs.description == null
 830               then lhs.description
 831               else if lhs.description == rhs.description
 832               then lhs.description
 833               else throw "A submoduleWith option is declared multiple times with conflicting descriptions";
 834           };
 835         };
 836       };
 837
 838     # A value from a set of allowed ones.
 839     enum = values:
 840       let
 841         inherit (lib.lists) unique;
 842         show = v:
 843                if builtins.isString v then ''"${v}"''
 844           else if builtins.isInt v then builtins.toString v
 845           else if builtins.isBool v then boolToString v
 846           else ''<${builtins.typeOf v}>'';
 847       in
 848       mkOptionType rec {
 849         name = "enum";
 850         description =
 851           # Length 0 or 1 enums may occur in a design pattern with type merging
 852           # where an "interface" module declares an empty enum and other modules
 853           # provide implementations, each extending the enum with their own
 854           # identifier.
 855           if values == [] then
 856             "impossible (empty enum)"
 857           else if builtins.length values == 1 then
 858             "value ${show (builtins.head values)} (singular enum)"
 859           else
 860             "one of ${concatMapStringsSep ", " show values}";
 861         descriptionClass =
 862           if builtins.length values < 2
 863           then "noun"
 864           else "conjunction";
 865         check = flip elem values;
 866         merge = mergeEqualOption;
 867         functor = (defaultFunctor name) // { payload = values; binOp = a: b: unique (a ++ b); };
 868       };
 869
 870     # Either value of type `t1` or `t2`.
 871     either = t1: t2: mkOptionType rec {
 872       name = "either";
 873       description =
 874         if t1.descriptionClass or null == "nonRestrictiveClause"
 875         then
 876           # Plain, but add comma
 877           "${t1.description}, or ${optionDescriptionPhrase (class: class == "noun" || class == "conjunction") t2}"
 878         else
 879           "${optionDescriptionPhrase (class: class == "noun" || class == "conjunction") t1} or ${optionDescriptionPhrase (class: class == "noun" || class == "conjunction" || class == "composite") t2}";
 880       descriptionClass = "conjunction";
 881       check = x: t1.check x || t2.check x;
 882       merge = loc: defs:
 883         let
 884           defList = map (d: d.value) defs;
 885         in
 886           if   all (x: t1.check x) defList
 887                then t1.merge loc defs
 888           else if all (x: t2.check x) defList
 889                then t2.merge loc defs
 890           else mergeOneOption loc defs;
 891       typeMerge = f':
 892         let mt1 = t1.typeMerge (elemAt f'.wrapped 0).functor;
 893             mt2 = t2.typeMerge (elemAt f'.wrapped 1).functor;
 894         in
 895            if (name == f'.name) && (mt1 != null) && (mt2 != null)
 896            then functor.type mt1 mt2
 897            else null;
 898       functor = (defaultFunctor name) // { wrapped = [ t1 t2 ]; };
 899       nestedTypes.left = t1;
 900       nestedTypes.right = t2;
 901     };
 902
 903     # Any of the types in the given list
 904     oneOf = ts:
 905       let
 906         head' = if ts == [] then throw "types.oneOf needs to get at least one type in its argument" else head ts;
 907         tail' = tail ts;
 908       in foldl' either head' tail';
 909
 910     # Either value of type `coercedType` or `finalType`, the former is
 911     # converted to `finalType` using `coerceFunc`.
 912     coercedTo = coercedType: coerceFunc: finalType:
 913       assert lib.assertMsg (coercedType.getSubModules == null)
 914         "coercedTo: coercedType must not have submodules (it’s a ${
 915           coercedType.description})";
 916       mkOptionType rec {
 917         name = "coercedTo";
 918         description = "${optionDescriptionPhrase (class: class == "noun") finalType} or ${optionDescriptionPhrase (class: class == "noun") coercedType} convertible to it";
 919         check = x: (coercedType.check x && finalType.check (coerceFunc x)) || finalType.check x;
 920         merge = loc: defs:
 921           let
 922             coerceVal = val:
 923               if coercedType.check val then coerceFunc val
 924               else val;
 925           in finalType.merge loc (map (def: def // { value = coerceVal def.value; }) defs);
 926         emptyValue = finalType.emptyValue;
 927         getSubOptions = finalType.getSubOptions;
 928         getSubModules = finalType.getSubModules;
 929         substSubModules = m: coercedTo coercedType coerceFunc (finalType.substSubModules m);
 930         typeMerge = t1: t2: null;
 931         functor = (defaultFunctor name) // { wrapped = finalType; };
 932         nestedTypes.coercedType = coercedType;
 933         nestedTypes.finalType = finalType;
 934       };
 935
 936     # Augment the given type with an additional type check function.
 937     addCheck = elemType: check: elemType // { check = x: elemType.check x && check x; };
 938
 939   };
 940 };
 941
 942 in outer_types // outer_types.types