# Nixpkgs/NixOS option handling. let lib = import ./default.nix; in with { inherit (builtins) head tail; }; with import ./trivial.nix; with import ./lists.nix; with import ./misc.nix; with import ./attrsets.nix; with import ./properties.nix; rec { inherit (lib) typeOf; isOption = attrs: (typeOf attrs) == "option"; mkOption = attrs: attrs // { _type = "option"; # name (this is the name of the attributem it is automatically generated by the traversal) # default (value used when no definition exists) # example (documentation) # description (documentation) # type (option type, provide a default merge function and ensure type correctness) # merge (function used to merge definitions into one definition: [ /type/ ] -> /type/) # apply (convert the option value to ease the manipulation of the option result) # options (set of sub-options declarations & definitions) }; # Make the option declaration more user-friendly by adding default # settings and some verifications based on the declaration content (like # type correctness). addOptionMakeUp = {name, recurseInto}: decl: let init = { inherit name; merge = mergeDefaultOption; apply = lib.id; }; mergeFromType = opt: if decl ? type && decl.type ? merge then opt // { merge = decl.type.merge; } else opt; addDeclaration = opt: opt // decl; ensureMergeInputType = opt: if decl ? type then opt // { merge = list: if all decl.type.check list then opt.merge list else throw "One of the definitions has a bad type."; } else opt; ensureDefaultType = opt: if decl ? type && decl ? default then opt // { default = if decl.type.check decl.default then decl.default else throw "The default value has a bad type."; } else opt; convertOptionsToModules = opt: if opt ? options then opt // { options = map (decl: let module = lib.applyIfFunction decl {}; in if lib.isModule module then decl else arg: { options = lib.applyIfFunction decl arg; } ) opt.options; } else opt; handleOptionSets = opt: if decl ? type && decl.type.hasOptions then let optionConfig = opts: config: map (f: lib.applyIfFunction f config) (opt.options ++ toList opts); in opt // { merge = list: decl.type.iter (path: opts: (lib.fix (fixableMergeFun (recurseInto path) (optionConfig opts)) ).config ) opt.name (opt.merge list); options = let path = decl.type.docPath opt.name; in (lib.fix (fixableMergeFun (recurseInto path) (optionConfig [])) ).options; } else opt; in foldl (opt: f: f opt) init [ # default settings mergeFromType # user settings addDeclaration # override settings ensureMergeInputType ensureDefaultType convertOptionsToModules handleOptionSets ]; # Merge a list of options containning different field. This is useful to # separate the merge & apply fields from the interface. mergeOptionDecls = opts: if opts == [] then {} else if tail opts == [] then let opt = head opts; in if opt ? options then opt // { options = toList opt.options; } else opt else fold (opt1: opt2: lib.addErrorContext "opt1 = ${lib.showVal opt1}\nopt2 = ${lib.showVal opt2}" ( # You cannot merge if two options have the same field. assert opt1 ? default -> ! opt2 ? default; assert opt1 ? example -> ! opt2 ? example; assert opt1 ? description -> ! opt2 ? description; assert opt1 ? merge -> ! opt2 ? merge; assert opt1 ? apply -> ! opt2 ? apply; assert opt1 ? type -> ! opt2 ? type; if opt1 ? options || opt2 ? options then opt1 // opt2 // { options = (toList (attrByPath ["options"] [] opt1)) ++ (toList (attrByPath ["options"] [] opt2)); } else opt1 // opt2 )) {} opts; # !!! This function will be removed because this can be done with the # multiple option declarations. addDefaultOptionValues = defs: opts: opts // builtins.listToAttrs (map (defName: { name = defName; value = let defValue = builtins.getAttr defName defs; optValue = builtins.getAttr defName opts; in if typeOf defValue == "option" then # `defValue' is an option. if hasAttr defName opts then builtins.getAttr defName opts else defValue.default else # `defValue' is an attribute set containing options. # So recurse. if hasAttr defName opts && isAttrs optValue then addDefaultOptionValues defValue optValue else addDefaultOptionValues defValue {}; } ) (attrNames defs)); mergeDefaultOption = list: if list != [] && tail list == [] then head list else if all builtins.isFunction list then x: mergeDefaultOption (map (f: f x) list) else if all isList list then concatLists list else if all isAttrs list then fold lib.mergeAttrs {} list else if all (x: true == x || false == x) list then fold lib.or false list else if all (x: x == toString x) list then lib.concatStrings list else throw "Cannot merge values."; mergeTypedOption = typeName: predicate: merge: list: if all predicate list then merge list else throw "Expect a ${typeName}."; mergeEnableOption = mergeTypedOption "boolean" (x: true == x || false == x) (fold lib.or false); mergeListOption = mergeTypedOption "list" isList concatLists; mergeStringOption = mergeTypedOption "string" (x: if builtins ? isString then builtins.isString x else x + "") lib.concatStrings; mergeOneOption = list: if list == [] then abort "This case should never happen." else if tail list != [] then throw "Multiple definitions. Only one is allowed for this option." else head list; fixableMergeFun = merge: f: config: merge ( # generate the list of option sets. f config ); fixableMergeModules = merge: initModules: {...}@args: config: fixableMergeFun merge (config: lib.moduleClosure initModules (args // { inherit config; }) ) config; fixableDefinitionsOf = initModules: {...}@args: fixableMergeModules (modules: (lib.moduleMerge "" modules).config) initModules args; fixableDeclarationsOf = initModules: {...}@args: fixableMergeModules (modules: (lib.moduleMerge "" modules).options) initModules args; definitionsOf = initModules: {...}@args: (lib.fix (module: fixableMergeModules (lib.moduleMerge "") initModules args module.config )).config; declarationsOf = initModules: {...}@args: (lib.fix (module: fixableMergeModules (lib.moduleMerge "") initModules args module.config )).options; # Generate documentation template from the list of option declaration like # the set generated with filterOptionSets. optionAttrSetToDocList = ignore: newOptionAttrSetToDocList; newOptionAttrSetToDocList = attrs: let options = collect isOption attrs; in fold (opt: rest: let docOption = { inherit (opt) name; description = if opt ? description then opt.description else throw "Option ${opt.name}: No description."; } // (if opt ? example then {inherit(opt) example;} else {}) // (if opt ? default then {inherit(opt) default;} else {}); subOptions = if opt ? options then newOptionAttrSetToDocList opt.options else []; in [ docOption ] ++ subOptions ++ rest ) [] options; }