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