nixpkgs/pkgs/lib/options.nix

263 lines
8.3 KiB
Nix
Raw Normal View History

# 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)
};
mapSubOptions = f: opt:
if opt ? options then
opt // {
options = map f (toList opt.options);
}
else
opt;
# 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;
};
functionsFromType = opt:
if decl ? type && decl.type ? merge then
opt
// optionalAttrs (decl.type ? merge) { inherit (decl.type) merge; }
// optionalAttrs (decl.type ? check) { inherit (decl.type) check; }
else
opt;
addDeclaration = opt: opt // decl;
ensureMergeInputType = opt:
if opt ? check then
opt // {
merge = list:
if all opt.check list then
opt.merge list
else
throw "One of the definitions has a bad type.";
}
else opt;
ensureDefaultType = opt:
if opt ? check && opt ? default then
opt // {
default =
if opt.check opt.default then
opt.default
else
throw "The default value has a bad type.";
}
else opt;
handleOptionSets = opt:
if opt ? type && opt.type.hasOptions then
let
optionConfig = opts: config:
map (f: lib.applyIfFunction f config)
(opt.options ++ toList opts);
in
opt // {
merge = list:
opt.type.iter
(path: opts:
(lib.fix
(fixableMergeFun (recurseInto path) (optionConfig opts))
).config
)
opt.name
(opt.merge list);
options =
let path = opt.type.docPath opt.name; in
(lib.fix
(fixableMergeFun (recurseInto path) (optionConfig []))
).options;
}
else
opt;
in
foldl (opt: f: f opt) init [
# default settings
functionsFromType
# user settings
addDeclaration
# override settings
ensureMergeInputType
ensureDefaultType
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.";
declarations = map (x: toString x.source) opt.declarations;
definitions = map (x: toString x.source) opt.definitions;
}
// (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;
}