lib/options.nix

   1 # Nixpkgs/NixOS option handling.
   2 { lib }:
   3
   4 let
   5   inherit (lib)
   6     all
   7     collect
   8     concatLists
   9     concatMap
  10     elemAt
  11     filter
  12     foldl'
  13     head
  14     isAttrs
  15     isBool
  16     isDerivation
  17     isFunction
  18     isInt
  19     isList
  20     isString
  21     length
  22     mapAttrs
  23     optional
  24     optionals
  25     take
  26     ;
  27   inherit (lib.attrsets)
  28     optionalAttrs
  29     ;
  30   inherit (lib.strings)
  31     concatMapStrings
  32     concatStringsSep
  33     ;
  34   inherit (lib.types)
  35     mkOptionType
  36     ;
  37 in
  38 rec {
  39
  40   /* Returns true when the given argument is an option
  41
  42      Type: isOption :: a -> bool
  43
  44      Example:
  45        isOption 1             // => false
  46        isOption (mkOption {}) // => true
  47   */
  48   isOption = lib.isType "option";
  49
  50   /* Creates an Option attribute set. mkOption accepts an attribute set with the following keys:
  51
  52      All keys default to `null` when not given.
  53
  54      Example:
  55        mkOption { }  // => { _type = "option"; }
  56        mkOption { defaultText = "foo"; } // => { _type = "option"; defaultText = "foo"; }
  57   */
  58   mkOption =
  59     {
  60     # Default value used when no definition is given in the configuration.
  61     default ? null,
  62     # Textual representation of the default, for the manual.
  63     defaultText ? null,
  64     # Example value used in the manual.
  65     example ? null,
  66     # String describing the option.
  67     description ? null,
  68     # Related packages used in the manual (see `genRelatedPackages` in ../nixos/lib/make-options-doc/default.nix).
  69     relatedPackages ? null,
  70     # Option type, providing type-checking and value merging.
  71     type ? null,
  72     # Function that converts the option value to something else.
  73     apply ? null,
  74     # Whether the option is for NixOS developers only.
  75     internal ? null,
  76     # Whether the option shows up in the manual.
  77     visible ? null,
  78     # Whether the option can be set only once
  79     readOnly ? null,
  80     # Deprecated, used by types.optionSet.
  81     options ? null
  82     } @ attrs:
  83     attrs // { _type = "option"; };
  84
  85   /* Creates an Option attribute set for a boolean value option i.e an
  86      option to be toggled on or off:
  87
  88      Example:
  89        mkEnableOption "foo"
  90        => { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }
  91   */
  92   mkEnableOption =
  93     # Name for the created option
  94     name: mkOption {
  95     default = false;
  96     example = true;
  97     description = "Whether to enable ${name}.";
  98     type = lib.types.bool;
  99   };
 100
 101   /* This option accepts anything, but it does not produce any result.
 102
 103      This is useful for sharing a module across different module sets
 104      without having to implement similar features as long as the
 105      values of the options are not accessed. */
 106   mkSinkUndeclaredOptions = attrs: mkOption ({
 107     internal = true;
 108     visible = false;
 109     default = false;
 110     description = "Sink for option definitions.";
 111     type = mkOptionType {
 112       name = "sink";
 113       check = x: true;
 114       merge = loc: defs: false;
 115     };
 116     apply = x: throw "Option value is not readable because the option is not declared.";
 117   } // attrs);
 118
 119   mergeDefaultOption = loc: defs:
 120     let list = getValues defs; in
 121     if length list == 1 then head list
 122     else if all isFunction list then x: mergeDefaultOption loc (map (f: f x) list)
 123     else if all isList list then concatLists list
 124     else if all isAttrs list then foldl' lib.mergeAttrs {} list
 125     else if all isBool list then foldl' lib.or false list
 126     else if all isString list then lib.concatStrings list
 127     else if all isInt list && all (x: x == head list) list then head list
 128     else throw "Cannot merge definitions of `${showOption loc}'. Definition values:${showDefs defs}";
 129
 130   mergeOneOption = loc: defs:
 131     if defs == [] then abort "This case should never happen."
 132     else if length defs != 1 then
 133       throw "The unique option `${showOption loc}' is defined multiple times. Definition values:${showDefs defs}"
 134     else (head defs).value;
 135
 136   /* "Merge" option definitions by checking that they all have the same value. */
 137   mergeEqualOption = loc: defs:
 138     if defs == [] then abort "This case should never happen."
 139     # Return early if we only have one element
 140     # This also makes it work for functions, because the foldl' below would try
 141     # to compare the first element with itself, which is false for functions
 142     else if length defs == 1 then (head defs).value
 143     else (foldl' (first: def:
 144       if def.value != first.value then
 145         throw "The option `${showOption loc}' has conflicting definition values:${showDefs [ first def ]}"
 146       else
 147         first) (head defs) defs).value;
 148
 149   /* Extracts values of all "value" keys of the given list.
 150
 151      Type: getValues :: [ { value :: a } ] -> [a]
 152
 153      Example:
 154        getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
 155        getValues [ ]                               // => [ ]
 156   */
 157   getValues = map (x: x.value);
 158
 159   /* Extracts values of all "file" keys of the given list
 160
 161      Type: getFiles :: [ { file :: a } ] -> [a]
 162
 163      Example:
 164        getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
 165        getFiles [ ]                                         // => [ ]
 166   */
 167   getFiles = map (x: x.file);
 168
 169   # Generate documentation template from the list of option declaration like
 170   # the set generated with filterOptionSets.
 171   optionAttrSetToDocList = optionAttrSetToDocList' [];
 172
 173   optionAttrSetToDocList' = prefix: options:
 174     concatMap (opt:
 175       let
 176         docOption = rec {
 177           loc = opt.loc;
 178           name = showOption opt.loc;
 179           description = opt.description or (lib.warn "Option `${name}' has no description." "This option has no description.");
 180           declarations = filter (x: x != unknownModule) opt.declarations;
 181           internal = opt.internal or false;
 182           visible = opt.visible or true;
 183           readOnly = opt.readOnly or false;
 184           type = opt.type.description or null;
 185         }
 186         // optionalAttrs (opt ? example) { example = scrubOptionValue opt.example; }
 187         // optionalAttrs (opt ? default) { default = scrubOptionValue opt.default; }
 188         // optionalAttrs (opt ? defaultText) { default = opt.defaultText; }
 189         // optionalAttrs (opt ? relatedPackages && opt.relatedPackages != null) { inherit (opt) relatedPackages; };
 190
 191         subOptions =
 192           let ss = opt.type.getSubOptions opt.loc;
 193           in if ss != {} then optionAttrSetToDocList' opt.loc ss else [];
 194       in
 195         [ docOption ] ++ optionals docOption.visible subOptions) (collect isOption options);
 196
 197
 198   /* This function recursively removes all derivation attributes from
 199      `x` except for the `name` attribute.
 200
 201      This is to make the generation of `options.xml` much more
 202      efficient: the XML representation of derivations is very large
 203      (on the order of megabytes) and is not actually used by the
 204      manual generator.
 205   */
 206   scrubOptionValue = x:
 207     if isDerivation x then
 208       { type = "derivation"; drvPath = x.name; outPath = x.name; name = x.name; }
 209     else if isList x then map scrubOptionValue x
 210     else if isAttrs x then mapAttrs (n: v: scrubOptionValue v) (removeAttrs x ["_args"])
 211     else x;
 212
 213
 214   /* For use in the `example` option attribute. It causes the given
 215      text to be included verbatim in documentation. This is necessary
 216      for example values that are not simple values, e.g., functions.
 217   */
 218   literalExample = text: { _type = "literalExample"; inherit text; };
 219
 220   # Helper functions.
 221
 222   /* Convert an option, described as a list of the option parts in to a
 223      safe, human readable version.
 224
 225      Example:
 226        (showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
 227        (showOption ["foo" "bar.baz" "tux"]) == "foo.bar.baz.tux"
 228
 229      Placeholders will not be quoted as they are not actual values:
 230        (showOption ["foo" "*" "bar"]) == "foo.*.bar"
 231        (showOption ["foo" "<name>" "bar"]) == "foo.<name>.bar"
 232
 233      Unlike attributes, options can also start with numbers:
 234        (showOption ["windowManager" "2bwm" "enable"]) == "windowManager.2bwm.enable"
 235   */
 236   showOption = parts: let
 237     escapeOptionPart = part:
 238       let
 239         escaped = lib.strings.escapeNixString part;
 240       in if escaped == "\"${part}\""
 241          then part
 242          else escaped;
 243     in (concatStringsSep ".") (map escapeOptionPart parts);
 244   showFiles = files: concatStringsSep " and " (map (f: "`${f}'") files);
 245
 246   showDefs = defs: concatMapStrings (def:
 247     let
 248       # Pretty print the value for display, if successful
 249       prettyEval = builtins.tryEval (lib.generators.toPretty {} def.value);
 250       # Split it into its lines
 251       lines = filter (v: ! isList v) (builtins.split "\n" prettyEval.value);
 252       # Only display the first 5 lines, and indent them for better visibility
 253       value = concatStringsSep "\n    " (take 5 lines ++ optional (length lines > 5) "...");
 254       result =
 255         # Don't print any value if evaluating the value strictly fails
 256         if ! prettyEval.success then ""
 257         # Put it on a new line if it consists of multiple
 258         else if length lines > 1 then ":\n    " + value
 259         else ": " + value;
 260     in "\n- In `${def.file}'${result}"
 261   ) defs;
 262
 263   unknownModule = "<unknown-file>";
 264
 265 }