commit 4f1d724b82db61237b5d7c669841b5f596e08e7f · pyrox.dev/nixpkgs

+2 -1

lib/default.nix

···

       128
       128
        
             canCleanSource pathIsGitRepo;

     

       129
       129
        
           inherit (self.modules) evalModules setDefaultModuleLocation

     

       130
       130
        
             unifyModuleSyntax applyModuleArgsIfFunction mergeModules

     

       131
       131
       -
             mergeModules' mergeOptionDecls evalOptionValue mergeDefinitions

     

       131
       131
       +
             mergeModules' mergeOptionDecls mergeDefinitions

     

       132
       132
        
             pushDownProperties dischargeProperties filterOverrides

     

       133
       133
        
             sortProperties fixupOptionType mkIf mkAssert mkMerge mkOverride

     

       134
       134
        
             mkOptionDefault mkDefault mkImageMediaOverride mkForce mkVMOverride

     
···

       138
       138
        
             mkMergedOptionModule mkChangedOptionModule

     

       139
       139
        
             mkAliasOptionModule mkDerivedConfig doRename

     

       140
       140
        
             mkAliasOptionModuleMD;

     

       141
       141
       +
           evalOptionValue = lib.warn "External use of `lib.evalOptionValue` is deprecated. If your use case isn't covered by non-deprecated functions, we'd like to know more and perhaps support your use case well, instead of providing access to these low level functions. In this case please open an issue in https://github.com/nixos/nixpkgs/issues/." self.modules.evalOptionValue;

     

       141
       142
        
           inherit (self.options) isOption mkEnableOption mkSinkUndeclaredOptions

     

       142
       143
        
             mergeDefaultOption mergeOneOption mergeEqualOption mergeUniqueOption

     

       143
       144
        
             getValues getFiles

+1 -1

lib/modules.nix

···

       1378
       1378
        
             inherit

     

       1379
       1379
        
               applyModuleArgsIfFunction

     

       1380
       1380
        
               dischargeProperties

     

       1381
       1381
       -
               evalOptionValue

     

       1382
       1381
        
               mergeModules

     

       1383
       1382
        
               mergeModules'

     

       1384
       1383
        
               pushDownProperties

     
···

       1399
       1398
        
           defaultPriority

     

       1400
       1399
        
           doRename

     

       1401
       1400
        
           evalModules

     

       1401
       1401
       +
           evalOptionValue  # for use by lib.types

     

       1402
       1402
        
           filterOverrides

     

       1403
       1403
        
           filterOverrides'

     

       1404
       1404
        
           fixMergeModules

+12

lib/tests/modules.sh

···

       103
       103
        
       checkConfigError '.*This can happen if you e.g. declared your options in .types.submodule.' config.sub ./error-mkOption-in-submodule-config.nix

     

       104
       104
        
       checkConfigError '.*A definition for option .bad. is not of type .non-empty .list of .submodule...\.' config.bad ./error-nonEmptyListOf-submodule.nix

     

       105
       105
        
       

     

       106
       106
       +
       # types.attrTag

     

       107
       107
       +
       checkConfigOutput '^true$' config.okChecks ./types-attrTag.nix

     

       108
       108
       +
       checkConfigError 'A definition for option .intStrings\.syntaxError. is not of type .attribute-tagged union' config.intStrings.syntaxError ./types-attrTag.nix

     

       109
       109
       +
       checkConfigError 'A definition for option .intStrings\.syntaxError2. is not of type .attribute-tagged union' config.intStrings.syntaxError2 ./types-attrTag.nix

     

       110
       110
       +
       checkConfigError 'A definition for option .intStrings\.syntaxError3. is not of type .attribute-tagged union' config.intStrings.syntaxError3 ./types-attrTag.nix

     

       111
       111
       +
       checkConfigError 'A definition for option .intStrings\.syntaxError4. is not of type .attribute-tagged union' config.intStrings.syntaxError4 ./types-attrTag.nix

     

       112
       112
       +
       checkConfigError 'A definition for option .intStrings\.mergeError. is not of type .attribute-tagged union' config.intStrings.mergeError ./types-attrTag.nix

     

       113
       113
       +
       checkConfigError 'A definition for option .intStrings\.badTagError. is not of type .attribute-tagged union' config.intStrings.badTagError ./types-attrTag.nix

     

       114
       114
       +
       checkConfigError 'A definition for option .intStrings\.badTagTypeError\.left. is not of type .signed integer.' config.intStrings.badTagTypeError.left ./types-attrTag.nix

     

       115
       115
       +
       checkConfigError 'A definition for option .nested\.right\.left. is not of type .signed integer.' config.nested.right.left ./types-attrTag.nix

     

       116
       116
       +
       checkConfigError 'In attrTag, each tag value must be an option, but tag int was a bare type, not wrapped in mkOption.' config.opt.int ./types-attrTag-wrong-decl.nix

     

       117
       117
       +
       

     

       106
       118
        
       # types.pathInStore

     

       107
       119
        
       checkConfigOutput '".*/store/0lz9p8xhf89kb1c1kk6jxrzskaiygnlh-bash-5.2-p15.drv"' config.pathInStore.ok1 ./types.nix

     

       108
       120
        
       checkConfigOutput '".*/store/0fb3ykw9r5hpayd05sr0cizwadzq1d8q-bash-5.2-p15"' config.pathInStore.ok2 ./types.nix

+41

lib/tests/modules/docs.nix

···

       1
       1
       +
       /*

     

       2
       2
       +
         A basic documentation generating module.

     

       3
       3
       +
         Declares and defines a `docs` option, suitable for making assertions about

     

       4
       4
       +
         the extraction "phase" of documentation generation.

     

       5
       5
       +
        */

     

       6
       6
       +
       { lib, options, ... }:

     

       7
       7
       +
       

     

       8
       8
       +
       let

     

       9
       9
       +
         inherit (lib)

     

       10
       10
       +
           head

     

       11
       11
       +
           length

     

       12
       12
       +
           mkOption

     

       13
       13
       +
           types

     

       14
       14
       +
         ;

     

       15
       15
       +
       

     

       16
       16
       +
         traceListSeq = l: v: lib.foldl' (a: b: lib.traceSeq b a) v l;

     

       17
       17
       +
       

     

       18
       18
       +
       in

     

       19
       19
       +
       

     

       20
       20
       +
       {

     

       21
       21
       +
         options.docs = mkOption {

     

       22
       22
       +
           type = types.lazyAttrsOf types.raw;

     

       23
       23
       +
           description = ''

     

       24
       24
       +
             All options to be rendered, without any visibility filtering applied.

     

       25
       25
       +
           '';

     

       26
       26
       +
         };

     

       27
       27
       +
         config.docs =

     

       28
       28
       +
           lib.zipAttrsWith

     

       29
       29
       +
             (name: values:

     

       30
       30
       +
               if length values > 1 then

     

       31
       31
       +
                 traceListSeq values

     

       32
       32
       +
                 abort "Multiple options with the same name: ${name}"

     

       33
       33
       +
               else

     

       34
       34
       +
                 assert length values == 1;

     

       35
       35
       +
                 head values

     

       36
       36
       +
             )

     

       37
       37
       +
             (map

     

       38
       38
       +
               (opt: { ${opt.name} = opt; })

     

       39
       39
       +
               (lib.optionAttrSetToDocList options)

     

       40
       40
       +
             );

     

       41
       41
       +
       }

+14

lib/tests/modules/types-attrTag-wrong-decl.nix

···

       1
       1
       +
       { lib, ... }:

     

       2
       2
       +
       let

     

       3
       3
       +
         inherit (lib) types mkOption;

     

       4
       4
       +
       in

     

       5
       5
       +
       {

     

       6
       6
       +
         options = {

     

       7
       7
       +
           opt = mkOption {

     

       8
       8
       +
             type = types.attrTag {

     

       9
       9
       +
               int = types.int;

     

       10
       10
       +
             };

     

       11
       11
       +
             default = { int = 1; };

     

       12
       12
       +
           };

     

       13
       13
       +
         };

     

       14
       14
       +
       }

+135

lib/tests/modules/types-attrTag.nix

···

       1
       1
       +
       { lib, config, options, ... }:

     

       2
       2
       +
       let

     

       3
       3
       +
         inherit (lib) mkOption types;

     

       4
       4
       +
         forceDeep = x: builtins.deepSeq x x;

     

       5
       5
       +
         mergedSubOption = (options.merged.type.getSubOptions options.merged.loc).extensible."merged.<name>";

     

       6
       6
       +
       in

     

       7
       7
       +
       {

     

       8
       8
       +
         options = {

     

       9
       9
       +
           intStrings = mkOption {

     

       10
       10
       +
             type = types.attrsOf

     

       11
       11
       +
               (types.attrTag {

     

       12
       12
       +
                 left = mkOption {

     

       13
       13
       +
                   type = types.int;

     

       14
       14
       +
                 };

     

       15
       15
       +
                 right = mkOption {

     

       16
       16
       +
                   type = types.str;

     

       17
       17
       +
                 };

     

       18
       18
       +
               });

     

       19
       19
       +
           };

     

       20
       20
       +
           nested = mkOption {

     

       21
       21
       +
             type = types.attrTag {

     

       22
       22
       +
               left = mkOption {

     

       23
       23
       +
                 type = types.int;

     

       24
       24
       +
               };

     

       25
       25
       +
               right = mkOption {

     

       26
       26
       +
                 type = types.attrTag {

     

       27
       27
       +
                   left = mkOption {

     

       28
       28
       +
                     type = types.int;

     

       29
       29
       +
                   };

     

       30
       30
       +
                   right = mkOption {

     

       31
       31
       +
                     type = types.str;

     

       32
       32
       +
                   };

     

       33
       33
       +
                 };

     

       34
       34
       +
               };

     

       35
       35
       +
             };

     

       36
       36
       +
           };

     

       37
       37
       +
           merged = mkOption {

     

       38
       38
       +
             type = types.attrsOf (

     

       39
       39
       +
               types.attrTag {

     

       40
       40
       +
                 yay = mkOption {

     

       41
       41
       +
                   type = types.int;

     

       42
       42
       +
                 };

     

       43
       43
       +
                 extensible = mkOption {

     

       44
       44
       +
                   type = types.enum [ "foo" ];

     

       45
       45
       +
                 };

     

       46
       46
       +
               }

     

       47
       47
       +
             );

     

       48
       48
       +
           };

     

       49
       49
       +
           submodules = mkOption {

     

       50
       50
       +
             type = types.attrsOf (

     

       51
       51
       +
               types.attrTag {

     

       52
       52
       +
                 foo = mkOption {

     

       53
       53
       +
                   type = types.submodule {

     

       54
       54
       +
                     options = {

     

       55
       55
       +
                       bar = mkOption {

     

       56
       56
       +
                         type = types.int;

     

       57
       57
       +
                       };

     

       58
       58
       +
                     };

     

       59
       59
       +
                   };

     

       60
       60
       +
                 };

     

       61
       61
       +
                 qux = mkOption {

     

       62
       62
       +
                   type = types.str;

     

       63
       63
       +
                   description = "A qux for when you don't want a foo";

     

       64
       64
       +
                 };

     

       65
       65
       +
               }

     

       66
       66
       +
             );

     

       67
       67
       +
           };

     

       68
       68
       +
           okChecks = mkOption {};

     

       69
       69
       +
         };

     

       70
       70
       +
         imports = [

     

       71
       71
       +
           ./docs.nix

     

       72
       72
       +
           {

     

       73
       73
       +
             options.merged = mkOption {

     

       74
       74
       +
               type = types.attrsOf (

     

       75
       75
       +
                 types.attrTag {

     

       76
       76
       +
                   nay = mkOption {

     

       77
       77
       +
                     type = types.bool;

     

       78
       78
       +
                   };

     

       79
       79
       +
                   extensible = mkOption {

     

       80
       80
       +
                     type = types.enum [ "bar" ];

     

       81
       81
       +
                   };

     

       82
       82
       +
                 }

     

       83
       83
       +
               );

     

       84
       84
       +
             };

     

       85
       85
       +
           }

     

       86
       86
       +
         ];

     

       87
       87
       +
         config = {

     

       88
       88
       +
           intStrings.syntaxError = 1;

     

       89
       89
       +
           intStrings.syntaxError2 = {};

     

       90
       90
       +
           intStrings.syntaxError3 = { a = true; b = true; };

     

       91
       91
       +
           intStrings.syntaxError4 = lib.mkMerge [ { a = true; } { b = true; } ];

     

       92
       92
       +
           intStrings.mergeError = lib.mkMerge [ { int = throw "do not eval"; } { string = throw "do not eval"; } ];

     

       93
       93
       +
           intStrings.badTagError.rite = throw "do not eval";

     

       94
       94
       +
           intStrings.badTagTypeError.left = "bad";

     

       95
       95
       +
           intStrings.numberOne.left = 1;

     

       96
       96
       +
           intStrings.hello.right = "hello world";

     

       97
       97
       +
           nested.right.left = "not a number";

     

       98
       98
       +
           merged.negative.nay = false;

     

       99
       99
       +
           merged.positive.yay = 100;

     

       100
       100
       +
           merged.extensi-foo.extensible = "foo";

     

       101
       101
       +
           merged.extensi-bar.extensible = "bar";

     

       102
       102
       +
           okChecks = builtins.addErrorContext "while evaluating the assertions" (

     

       103
       103
       +
             assert config.intStrings.hello == { right = "hello world"; };

     

       104
       104
       +
             assert config.intStrings.numberOne == { left = 1; };

     

       105
       105
       +
             assert config.merged.negative == { nay = false; };

     

       106
       106
       +
             assert config.merged.positive == { yay = 100; };

     

       107
       107
       +
             assert config.merged.extensi-foo == { extensible = "foo"; };

     

       108
       108
       +
             assert config.merged.extensi-bar == { extensible = "bar"; };

     

       109
       109
       +
             assert config.docs."submodules.<name>.foo.bar".type == "signed integer";

     

       110
       110
       +
             assert config.docs."submodules.<name>.qux".type == "string";

     

       111
       111
       +
             assert config.docs."submodules.<name>.qux".declarations == [ __curPos.file ];

     

       112
       112
       +
             assert config.docs."submodules.<name>.qux".loc == [ "submodules" "<name>" "qux" ];

     

       113
       113
       +
             assert config.docs."submodules.<name>.qux".name == "submodules.<name>.qux";

     

       114
       114
       +
             assert config.docs."submodules.<name>.qux".description == "A qux for when you don't want a foo";

     

       115
       115
       +
             assert config.docs."submodules.<name>.qux".readOnly == false;

     

       116
       116
       +
             assert config.docs."submodules.<name>.qux".visible == true;

     

       117
       117
       +
             # Not available (yet?)

     

       118
       118
       +
             # assert config.docs."submodules.<name>.qux".declarationsWithPositions == [ ... ];

     

       119
       119
       +
             assert options.submodules.declarations == [ __curPos.file ];

     

       120
       120
       +
             assert lib.length options.submodules.declarationPositions == 1;

     

       121
       121
       +
             assert (lib.head options.submodules.declarationPositions).file == __curPos.file;

     

       122
       122
       +
             assert options.merged.declarations == [ __curPos.file __curPos.file ];

     

       123
       123
       +
             assert lib.length options.merged.declarationPositions == 2;

     

       124
       124
       +
             assert (lib.elemAt options.merged.declarationPositions 0).file == __curPos.file;

     

       125
       125
       +
             assert (lib.elemAt options.merged.declarationPositions 1).file == __curPos.file;

     

       126
       126
       +
             assert (lib.elemAt options.merged.declarationPositions 0).line != (lib.elemAt options.merged.declarationPositions 1).line;

     

       127
       127
       +
             assert mergedSubOption.declarations == [ __curPos.file __curPos.file ];

     

       128
       128
       +
             assert lib.length mergedSubOption.declarationPositions == 2;

     

       129
       129
       +
             assert (lib.elemAt mergedSubOption.declarationPositions 0).file == __curPos.file;

     

       130
       130
       +
             assert (lib.elemAt mergedSubOption.declarationPositions 1).file == __curPos.file;

     

       131
       131
       +
             assert (lib.elemAt mergedSubOption.declarationPositions 0).line != (lib.elemAt mergedSubOption.declarationPositions 1).line;

     

       132
       132
       +
             assert lib.length config.docs."merged.<name>.extensible".declarations == 2;

     

       133
       133
       +
             true);

     

       134
       134
       +
         };

     

       135
       135
       +
       }

+101 -1

lib/types.nix

···

       15
       15
        
           isList

     

       16
       16
        
           isString

     

       17
       17
        
           isStorePath

     

       18
       18
       +
           throwIf

     

       18
       19
        
           toDerivation

     

       19
       20
        
           toList

     

       20
       21
        
           ;

     
···

       65
       66
        
           fixupOptionType

     

       66
       67
        
           mergeOptionDecls

     

       67
       68
        
           ;

     

       69
       69
       +
       

     

       70
       70
       +
         inAttrPosSuffix = v: name:

     

       71
       71
       +
           let pos = builtins.unsafeGetAttrPos name v; in

     

       72
       72
       +
           if pos == null then "" else " at ${pos.file}:${toString pos.line}:${toString pos.column}";

     

       73
       73
       +
       

     

       68
       74
        
         outer_types =

     

       69
       75
        
       rec {

     

       70
       76
        
         __attrsFailEvaluation = true;

     
···

       152
       158
        
             # If it doesn't, this should be {}

     

       153
       159
        
             # This may be used when a value is required for `mkIf false`. This allows the extra laziness in e.g. `lazyAttrsOf`.

     

       154
       160
        
             emptyValue ? {}

     

       155
       155
       -
           , # Return a flat list of sub-options.  Used to generate

     

       161
       161
       +
           , # Return a flat attrset of sub-options.  Used to generate

     

       156
       162
        
             # documentation.

     

       157
       163
        
             getSubOptions ? prefix: {}

     

       158
       164
        
           , # List of modules if any, or null if none.

     
···

       622
       628
        
               + " https://github.com/NixOS/nixpkgs/issues/1800 for the motivation.";

     

       623
       629
        
             nestedTypes.elemType = elemType;

     

       624
       630
        
           };

     

       631
       631
       +
       

     

       632
       632
       +
           attrTag = tags:

     

       633
       633
       +
             let tags_ = tags; in

     

       634
       634
       +
             let

     

       635
       635
       +
               tags =

     

       636
       636
       +
                 mapAttrs

     

       637
       637
       +
                   (n: opt:

     

       638
       638
       +
                     builtins.addErrorContext "while checking that attrTag tag ${lib.strings.escapeNixIdentifier n} is an option with a type${inAttrPosSuffix tags_ n}" (

     

       639
       639
       +
                       throwIf (opt._type or null != "option")

     

       640
       640
       +
                         "In attrTag, each tag value must be an option, but tag ${lib.strings.escapeNixIdentifier n} ${

     

       641
       641
       +
                           if opt?_type then

     

       642
       642
       +
                             if opt._type == "option-type"

     

       643
       643
       +
                             then "was a bare type, not wrapped in mkOption."

     

       644
       644
       +
                             else "was of type ${lib.strings.escapeNixString opt._type}."

     

       645
       645
       +
                           else "was not."}"

     

       646
       646
       +
                       opt // {

     

       647
       647
       +
                         declarations = opt.declarations or (

     

       648
       648
       +
                           let pos = builtins.unsafeGetAttrPos n tags_;

     

       649
       649
       +
                           in if pos == null then [] else [ pos.file ]

     

       650
       650
       +
                         );

     

       651
       651
       +
                         declarationPositions = opt.declarationPositions or (

     

       652
       652
       +
                           let pos = builtins.unsafeGetAttrPos n tags_;

     

       653
       653
       +
                           in if pos == null then [] else [ pos ]

     

       654
       654
       +
                         );

     

       655
       655
       +
                       }

     

       656
       656
       +
                     ))

     

       657
       657
       +
                   tags_;

     

       658
       658
       +
               choicesStr = concatMapStringsSep ", " lib.strings.escapeNixIdentifier (attrNames tags);

     

       659
       659
       +
             in

     

       660
       660
       +
             mkOptionType {

     

       661
       661
       +
               name = "attrTag";

     

       662
       662
       +
               description = "attribute-tagged union";

     

       663
       663
       +
               descriptionClass = "noun";

     

       664
       664
       +
               getSubOptions = prefix:

     

       665
       665
       +
                 mapAttrs

     

       666
       666
       +
                   (tagName: tagOption: {

     

       667
       667
       +
                     "${lib.showOption prefix}" =

     

       668
       668
       +
                       tagOption // {

     

       669
       669
       +
                         loc = prefix ++ [ tagName ];

     

       670
       670
       +
                       };

     

       671
       671
       +
                   })

     

       672
       672
       +
                   tags;

     

       673
       673
       +
               check = v: isAttrs v && length (attrNames v) == 1 && tags?${head (attrNames v)};

     

       674
       674
       +
               merge = loc: defs:

     

       675
       675
       +
                 let

     

       676
       676
       +
                   choice = head (attrNames (head defs).value);

     

       677
       677
       +
                   checkedValueDefs = map

     

       678
       678
       +
                     (def:

     

       679
       679
       +
                       assert (length (attrNames def.value)) == 1;

     

       680
       680
       +
                       if (head (attrNames def.value)) != choice

     

       681
       681
       +
                       then throw "The option `${showOption loc}` is defined both as `${choice}` and `${head (attrNames def.value)}`, in ${showFiles (getFiles defs)}."

     

       682
       682
       +
                       else { inherit (def) file; value = def.value.${choice}; })

     

       683
       683
       +
                     defs;

     

       684
       684
       +
                 in

     

       685
       685
       +
                   if tags?${choice}

     

       686
       686
       +
                   then

     

       687
       687
       +
                     { ${choice} =

     

       688
       688
       +
                         (lib.modules.evalOptionValue

     

       689
       689
       +
                           (loc ++ [choice])

     

       690
       690
       +
                           tags.${choice}

     

       691
       691
       +
                           checkedValueDefs

     

       692
       692
       +
                         ).value;

     

       693
       693
       +
                     }

     

       694
       694
       +
                   else throw "The option `${showOption loc}` is defined as ${lib.strings.escapeNixIdentifier choice}, but ${lib.strings.escapeNixIdentifier choice} is not among the valid choices (${choicesStr}). Value ${choice} was defined in ${showFiles (getFiles defs)}.";

     

       695
       695
       +
               nestedTypes = tags;

     

       696
       696
       +
               functor = defaultFunctor "attrTag" // {

     

       697
       697
       +
                 type = { tags, ... }: types.attrTag tags;

     

       698
       698
       +
                 payload = { inherit tags; };

     

       699
       699
       +
                 binOp =

     

       700
       700
       +
                   let

     

       701
       701
       +
                     # Add metadata in the format that submodules work with

     

       702
       702
       +
                     wrapOptionDecl =

     

       703
       703
       +
                       option: { options = option; _file = "<attrTag {...}>"; pos = null; };

     

       704
       704
       +
                   in

     

       705
       705
       +
                   a: b: {

     

       706
       706
       +
                     tags = a.tags // b.tags //

     

       707
       707
       +
                       mapAttrs

     

       708
       708
       +
                         (tagName: bOpt:

     

       709
       709
       +
                           lib.mergeOptionDecls

     

       710
       710
       +
                             # FIXME: loc is not accurate; should include prefix

     

       711
       711
       +
                             #        Fortunately, it's only used for error messages, where a "relative" location is kinda ok.

     

       712
       712
       +
                             #        It is also returned though, but use of the attribute seems rare?

     

       713
       713
       +
                             [tagName]

     

       714
       714
       +
                             [ (wrapOptionDecl a.tags.${tagName}) (wrapOptionDecl bOpt) ]

     

       715
       715
       +
                           // {

     

       716
       716
       +
                             # mergeOptionDecls is not idempotent in these attrs:

     

       717
       717
       +
                             declarations = a.tags.${tagName}.declarations ++ bOpt.declarations;

     

       718
       718
       +
                             declarationPositions = a.tags.${tagName}.declarationPositions ++ bOpt.declarationPositions;

     

       719
       719
       +
                           }

     

       720
       720
       +
                         )

     

       721
       721
       +
                         (builtins.intersectAttrs a.tags b.tags);

     

       722
       722
       +
                 };

     

       723
       723
       +
               };

     

       724
       724
       +
             };

     

       625
       725
        
       

     

       626
       726
        
           uniq = unique { message = ""; };

     

       627
       727

+81 -16

nixos/doc/manual/development/option-types.section.md

···

       42
       42
        
       :   One element of the list *`l`*, e.g. `types.enum [ "left" "right" ]`.

     

       43
       43
        
           Multiple definitions cannot be merged.

     

       44
       44
        
       

     

       45
       45
       +
           If you want to pair these values with more information, possibly of

     

       46
       46
       +
           distinct types, consider using a [sum type](#sec-option-types-sums).

     

       47
       47
       +
       

     

       45
       48
        
       `types.anything`

     

       46
       49
        
       

     

       47
       50
        
       :   A type that accepts any value and recursively merges attribute sets

     
···

       279
       282
        
           more convenient and discoverable than expecting the module user to

     

       280
       283
        
           type-merge with the `attrsOf submodule` option.

     

       281
       284
        
       

     

       285
       285
       +
       ## Union types {#sec-option-types-unions}

     

       286
       286
       +
       

     

       287
       287
       +
       A union of types is a type such that a value is valid when it is valid for at least one of those types.

     

       288
       288
       +
       

     

       289
       289
       +
       If some values are instances of more than one of the types, it is not possible to distinguish which type they are meant to be instances of. If that's needed, consider using a [sum type](#sec-option-types-sums).

     

       290
       290
       +
       

     

       291
       291
       +
       `types.either` *`t1 t2`*

     

       292
       292
       +
       

     

       293
       293
       +
       :   Type *`t1`* or type *`t2`*, e.g. `with types; either int str`.

     

       294
       294
       +
           Multiple definitions cannot be merged.

     

       295
       295
       +
       

     

       296
       296
       +
       `types.oneOf` \[ *`t1 t2`* ... \]

     

       297
       297
       +
       

     

       298
       298
       +
       :   Type *`t1`* or type *`t2`* and so forth, e.g.

     

       299
       299
       +
           `with types; oneOf [ int str bool ]`. Multiple definitions cannot be

     

       300
       300
       +
           merged.

     

       301
       301
       +
       

     

       302
       302
       +
       `types.nullOr` *`t`*

     

       303
       303
       +
       

     

       304
       304
       +
       :   `null` or type *`t`*. Multiple definitions are merged according to

     

       305
       305
       +
           type *`t`*.

     

       306
       306
       +
       

     

       307
       307
       +
       

     

       308
       308
       +
       ## Sum types {#sec-option-types-sums}

     

       309
       309
       +
       

     

       310
       310
       +
       A sum type can be thought of, conceptually, as a *`types.enum`* where each valid item is paired with at least a type, through some value syntax.

     

       311
       311
       +
       Nix does not have a built-in syntax for this pairing of a label and a type or value, so sum types may be represented in multiple ways.

     

       312
       312
       +
       

     

       313
       313
       +
       If the you're interested in can be distinguished without a label, you may simplify your value syntax with a [union type](#sec-option-types-unions) instead.

     

       314
       314
       +
       

     

       315
       315
       +
       `types.attrTag` *`{ attr1 = option1; attr2 = option2; ... }`*

     

       316
       316
       +
       

     

       317
       317
       +
       :   An attribute set containing one attribute, whose name must be picked from

     

       318
       318
       +
           the attribute set (`attr1`, etc) and whose value consists of definitions that are valid for the corresponding option (`option1`, etc).

     

       319
       319
       +
       

     

       320
       320
       +
           This type appears in the documentation as _attribute-tagged union_.

     

       321
       321
       +
       

     

       322
       322
       +
           Example:

     

       323
       323
       +
       

     

       324
       324
       +
           ```nix

     

       325
       325
       +
           { lib, ... }:

     

       326
       326
       +
           let inherit (lib) type mkOption;

     

       327
       327
       +
           in {

     

       328
       328
       +
             options.toyRouter.rules = mkOption {

     

       329
       329
       +
               description = ''

     

       330
       330
       +
                 Rules for a fictional packet routing service.

     

       331
       331
       +
               '';

     

       332
       332
       +
               type = types.attrsOf (

     

       333
       333
       +
                 types.attrTag {

     

       334
       334
       +
                   bounce = mkOption {

     

       335
       335
       +
                     description = "Send back a packet explaining why it wasn't forwarded.";

     

       336
       336
       +
                     type = types.submodule {

     

       337
       337
       +
                       options.errorMessage = mkOption { … };

     

       338
       338
       +
                     };

     

       339
       339
       +
                   };

     

       340
       340
       +
                   forward = mkOption {

     

       341
       341
       +
                     description = "Forward the packet.";

     

       342
       342
       +
                     type = types.submodule {

     

       343
       343
       +
                       options.destination = mkOption { … };

     

       344
       344
       +
                     };

     

       345
       345
       +
                   };

     

       346
       346
       +
                   ignore = types.mkOption {

     

       347
       347
       +
                     description = "Drop the packet without sending anything back.";

     

       348
       348
       +
                     type = types.submodule {};

     

       349
       349
       +
                   };

     

       350
       350
       +
                 });

     

       351
       351
       +
             };

     

       352
       352
       +
             config.toyRouter.rules = {

     

       353
       353
       +
               http = {

     

       354
       354
       +
                 bounce = {

     

       355
       355
       +
                   errorMessage = "Unencrypted HTTP is banned. You must always use https://.";

     

       356
       356
       +
                 };

     

       357
       357
       +
               };

     

       358
       358
       +
               ssh = { drop = {}; };

     

       359
       359
       +
             };

     

       360
       360
       +
           }

     

       361
       361
       +
           ```

     

       362
       362
       +
       

     

       282
       363
        
       ## Composed types {#sec-option-types-composed}

     

       283
       364
        
       

     

       284
       365
        
       Composed types are types that take a type as parameter. `listOf

     
···

       318
       399
        
           returned instead for the same `mkIf false` definition.

     

       319
       400
        
           :::

     

       320
       401
        
       

     

       321
       321
       -
       `types.nullOr` *`t`*

     

       322
       322
       -
       

     

       323
       323
       -
       :   `null` or type *`t`*. Multiple definitions are merged according to

     

       324
       324
       -
           type *`t`*.

     

       325
       325
       -
       

     

       326
       402
        
       `types.uniq` *`t`*

     

       327
       403
        
       

     

       328
       404
        
       :   Ensures that type *`t`* cannot be merged. It is used to ensure option

     
···

       333
       409
        
       :   Ensures that type *`t`* cannot be merged. Prints the message *`m`*, after

     

       334
       410
        
           the line `The option <option path> is defined multiple times.` and before

     

       335
       411
        
           a list of definition locations.

     

       336
       336
       -
       

     

       337
       337
       -
       `types.either` *`t1 t2`*

     

       338
       338
       -
       

     

       339
       339
       -
       :   Type *`t1`* or type *`t2`*, e.g. `with types; either int str`.

     

       340
       340
       -
           Multiple definitions cannot be merged.

     

       341
       341
       -
       

     

       342
       342
       -
       `types.oneOf` \[ *`t1 t2`* ... \]

     

       343
       343
       -
       

     

       344
       344
       -
       :   Type *`t1`* or type *`t2`* and so forth, e.g.

     

       345
       345
       -
           `with types; oneOf [ int str bool ]`. Multiple definitions cannot be

     

       346
       346
       -
           merged.

     

       347
       412
        
       

     

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

     

       349
       414