nixpkgs/pkgs/lib/options.nix
Nicolas Pierron 5cd8eefb26 Allow to set priority which are below the default priority level.
This help to define default values which can be override without any extra syntax.

svn path=/nixpkgs/trunk/; revision=16304
2009-07-10 09:44:09 +00:00

747 lines
24 KiB
Nix

# 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;
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;
handleOptionSets = opt:
if decl ? type && decl.type.hasOptions then
let
optionConfig = opts: config:
map (f: applyIfFunction f config)
(decl.options ++ [opts]);
in
opt // {
merge = list:
decl.type.iter
(path: opts:
lib.fix (fixableMergeFun (recurseInto path) (optionConfig opts))
)
opt.name
(opt.merge list);
options = recurseInto (decl.type.docPath opt.name) decl.options;
}
else
opt;
in
foldl (opt: f: f opt) init [
# default settings
mergeFromType
# 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;
# Handle the traversal of option sets. All sets inside 'opts' are zipped
# and options declaration and definition are separated. If no option are
# declared at a specific depth, then the function recurse into the values.
# Other cases are handled by the optionHandler which contains two
# functions that are used to defined your goal.
# - export is a function which takes two arguments which are the option
# and the list of values.
# - notHandle is a function which takes the list of values are not handle
# by this function.
handleOptionSets = optionHandler@{export, notHandle, ...}: path: opts:
if all isAttrs opts then
lib.zip (attr: opts:
let
recurseInto = name: attrs:
handleOptionSets optionHandler name attrs;
# Compute the path to reach the attribute.
name = if path == "" then attr else path + "." + attr;
# Divide the definitions of the attribute "attr" between
# declaration (isOption) and definitions (!isOption).
test = partition (x: isOption (rmProperties x)) opts;
decls = map rmProperties test.right; defs = test.wrong;
# Make the option declaration more user-friendly by adding default
# settings and some verifications based on the declaration content
# (like type correctness).
opt = addOptionMakeUp
{ inherit name recurseInto; }
(mergeOptionDecls decls);
# Return the list of option sets.
optAttrs = map delayProperties defs;
# return the list of option values.
# Remove undefined values that are coming from evalIf.
optValues = evalProperties defs;
in
if decls == [] then recurseInto name optAttrs
else lib.addErrorContext "while evaluating the option ${name}:" (
export opt optValues
)
) opts
else lib.addErrorContext "while evaluating ${path}:" (notHandle opts);
# Merge option sets and produce a set of values which is the merging of
# all options declare and defined. If no values are defined for an
# option, then the default value is used otherwise it use the merge
# function of each option to get the result.
mergeOptionSets =
handleOptionSets {
export = opt: values:
opt.apply (
if values == [] then
if opt ? default then opt.default
else throw "Not defined."
else opt.merge values
);
notHandle = opts: throw "Used without option declaration.";
};
# Keep all option declarations.
filterOptionSets =
handleOptionSets {
export = opt: values: opt;
notHandle = opts: {};
};
# Unfortunately this can also be a string.
isPath = x: !(
builtins.isFunction x
|| builtins.isAttrs x
|| builtins.isInt x
|| builtins.isBool x
|| builtins.isList x
);
importIfPath = path:
if isPath path then
import path
else
path;
applyIfFunction = f: arg:
if builtins.isFunction f then
f arg
else
f;
moduleClosure = initModules: args:
let
moduleImport = m:
(applyIfFunction (importIfPath m) args) // {
# used by generic closure to avoid duplicated imports.
key = m;
};
removeKeys = list: map (m: removeAttrs m ["key"]) list;
getImports = m:
if m ? config || m ? options then
attrByPath ["imports"] [] m
else
toList (rmProperties (attrByPath ["require"] [] (delayProperties m)));
getImportedPaths = m: filter isPath (getImports m);
getImportedSets = m: filter (x: !isPath x) (getImports m);
inlineImportedSets = list:
lib.concatMap (m:[m] ++ map moduleImport (getImportedSets m)) list;
in
removeKeys (inlineImportedSets (lazyGenericClosure {
startSet = map moduleImport initModules;
operator = m: map moduleImport (getImportedPaths m);
}));
selectDeclsAndDefs = modules:
lib.concatMap (m:
if m ? config || m ? options then
attrByPath ["options"] [] m
++ attrByPath ["config"] [] m
else
[ m ]
) modules;
fixableMergeFun = merge: f: config:
merge (
# remove require because this is not an option.
map (m: removeAttrs m ["require"]) (
# Delay top-level properties like mkIf
map delayProperties (
# generate the list of option sets.
f config
)
)
);
fixableMergeModules = merge: initModules: {...}@args: config:
fixableMergeFun merge (config:
# filter the list of option sets.
selectDeclsAndDefs (
# generate the list of modules from a closure of imports/require
# attribtues.
moduleClosure initModules (args // { inherit config; })
)
) config;
fixableDefinitionsOf = initModules: {...}@args:
fixableMergeModules (mergeOptionSets "") initModules args;
fixableDeclarationsOf = initModules: {...}@args:
fixableMergeModules (filterOptionSets "") initModules args;
definitionsOf = initModules: {...}@args:
lib.fix (fixableDefinitionsOf initModules args);
declarationsOf = initModules: {...}@args:
lib.fix (fixableDeclarationsOf initModules args);
fixMergeModules = merge: initModules: {...}@args:
lib.fix (fixableMergeModules merge initModules args);
# old interface.
fixOptionSetsFun = merge: {...}@args: initModules: config:
fixableMergeModules (merge "") initModules args config;
fixOptionSets = merge: args: initModules:
fixMergeModules (merge "") initModules args;
# 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;
/* Option Properties */
# Generalize the problem of delayable properties. Any property can be created
# Tell that nothing is defined. When properties are evaluated, this type
# is used to remove an entry. Thus if your property evaluation semantic
# implies that you have to mute the content of an attribute, then your
# property should produce this value.
isNotdef = attrs: (typeOf attrs) == "notdef";
mkNotdef = {_type = "notdef";};
# General property type, it has a property attribute and a content
# attribute. The property attribute refer to an attribute set which
# contains a _type attribute and a list of functions which are used to
# evaluate this property. The content attribute is used to stack property
# on top of each other.
#
# The optional functions which may be contained in the property attribute
# are:
# - onDelay: run on a copied property.
# - onGlobalDelay: run on all copied properties.
# - onEval: run on an evaluated property.
# - onGlobalEval: run on a list of property stack on top of their values.
isProperty = attrs: (typeOf attrs) == "property";
mkProperty = p@{property, content, ...}: p // {
_type = "property";
};
# Go throw the stack of properties and apply the function `op' on all
# property and call the function `nul' on the final value which is not a
# property. The stack is traversed in reversed order. The `op' function
# should expect a property with a content which have been modified.
#
# Warning: The `op' function expects only one argument in order to avoid
# calls to mkProperties as the argument is already a valid property which
# contains the result of the folding inside the content attribute.
foldProperty = op: nul: attrs:
if isProperty attrs then
op (attrs // {
content = foldProperty op nul attrs.content;
})
else
nul attrs;
# Simple function which can be used as the `op' argument of the
# foldProperty function. Properties that you don't want to handle can be
# ignored with the `id' function. `isSearched' is a function which should
# check the type of a property and return a boolean value. `thenFun' and
# `elseFun' are functions which behave as the `op' argument of the
# foldProperty function.
foldFilter = isSearched: thenFun: elseFun: attrs:
if isSearched attrs.property then
thenFun attrs
else
elseFun attrs;
# Move properties from the current attribute set to the attribute
# contained in this attribute set. This trigger property handlers called
# `onDelay' and `onGlobalDelay'.
delayProperties = attrs:
let cleanAttrs = rmProperties attrs; in
if isProperty attrs then
lib.mapAttrs (a: v:
lib.addErrorContext "while moving properties on the attribute `${a}'." (
triggerPropertiesGlobalDelay a (
triggerPropertiesDelay a (
copyProperties attrs v
)))) cleanAttrs
else
attrs;
# Call onDelay functions.
triggerPropertiesDelay = name: attrs:
let
callOnDelay = p@{property, ...}:
lib.addErrorContext "while calling a onDelay function." (
if property ? onDelay then
property.onDelay name p
else
p
);
in
foldProperty callOnDelay id attrs;
# Call onGlobalDelay functions.
triggerPropertiesGlobalDelay = name: attrs:
let
globalDelayFuns = uniqListExt {
getter = property: property._type;
inputList = foldProperty (p@{property, content, ...}:
if property ? onGlobalDelay then
[ property ] ++ content
else
content
) (a: []) attrs;
};
callOnGlobalDelay = property: content:
lib.addErrorContext "while calling a onGlobalDelay function." (
property.onGlobalDelay name content
);
in
fold callOnGlobalDelay attrs globalDelayFuns;
# Expect a list of values which may have properties and return the same
# list of values where all properties have been evaluated and where all
# ignored values are removed. This trigger property handlers called
# `onEval' and `onGlobalEval'.
evalProperties = valList:
if valList != [] then
filter (x: !isNotdef x) (
lib.addErrorContext "while evaluating properties an attribute." (
triggerPropertiesGlobalEval (
map triggerPropertiesEval valList
)))
else
valList;
# Call onEval function
triggerPropertiesEval = val:
foldProperty (p@{property, ...}:
lib.addErrorContext "while calling a onEval function." (
if property ? onEval then
property.onEval p
else
p
)
) id val;
# Call onGlobalEval function
triggerPropertiesGlobalEval = valList:
let
globalEvalFuns = uniqListExt {
getter = property: property._type;
inputList =
fold (attrs: list:
foldProperty (p@{property, content, ...}:
if property ? onGlobalEval then
[ property ] ++ content
else
content
) (a: list) attrs
) [] valList;
};
callOnGlobalEval = property: valList:
lib.addErrorContext "while calling a onGlobalEval function." (
property.onGlobalEval valList
);
in
fold callOnGlobalEval valList globalEvalFuns;
# Remove all properties on top of a value and return the value.
rmProperties =
foldProperty (p@{content, ...}: content) id;
# Copy properties defined on a value on another value.
copyProperties = attrs: newAttrs:
foldProperty id (x: newAttrs) attrs;
/* If. ThenElse. Always. */
# create "if" statement that can be delayed on sets until a "then-else" or
# "always" set is reached. When an always set is reached the condition
# is ignore.
# Create a "If" property which only contains a condition.
isIf = attrs: (typeOf attrs) == "if";
mkIf = condition: content: mkProperty {
property = {
_type = "if";
onGlobalDelay = onIfGlobalDelay;
onEval = onIfEval;
inherit condition;
};
inherit content;
};
# Create a "ThenElse" property which contains choices which can choosed by
# the evaluation of an "If" statement.
isThenElse = attrs: (typeOf attrs) == "then-else";
mkThenElse = attrs:
assert attrs ? thenPart && attrs ? elsePart;
mkProperty {
property = {
_type = "then-else";
onEval = val: throw "Missing mkIf statement.";
inherit (attrs) thenPart elsePart;
};
content = mkNotdef;
};
# Create an "Always" property remove ignore all "If" statement.
isAlways = attrs: (typeOf attrs) == "always";
mkAlways = value:
mkProperty {
property = {
_type = "always";
onEval = p@{content, ...}: content;
inherit value;
};
content = mkNotdef;
};
# Remove all "If" statement defined on a value.
rmIf = foldProperty (
foldFilter isIf
({content, ...}: content)
id
) id;
# Evaluate the "If" statements when either "ThenElse" or "Always"
# statement is encounter. Otherwise it remove multiple If statement and
# replace them by one "If" staement where the condition is the list of all
# conditions joined with a "and" operation.
onIfGlobalDelay = name: content:
let
# extract if statements and non-if statements and repectively put them
# in the attribute list and attrs.
ifProps =
foldProperty
(foldFilter (p: isIf p || isThenElse p || isAlways p)
# then, push the codition inside the list list
(p@{property, content, ...}:
{ inherit (content) attrs;
list = [property] ++ content.list;
}
)
# otherwise, add the propertie.
(p@{property, content, ...}:
{ inherit (content) list;
attrs = p // { content = content.attrs; };
}
)
)
(attrs: { list = []; inherit attrs; })
content;
# compute the list of if statements.
evalIf = content: condition: list:
if list == [] then
mkIf condition content
else
let p = head list; in
# evaluate the condition.
if isThenElse p then
if condition then
copyProperties content p.thenPart
else
copyProperties content p.elsePart
# ignore the condition.
else if isAlways p then
copyProperties content p.value
# otherwise (isIf)
else
evalIf content (condition && p.condition) (tail list);
in
evalIf ifProps.attrs true ifProps.list;
# Evaluate the condition of the "If" statement to either get the value or
# to ignore the value.
onIfEval = p@{property, content, ...}:
if property.condition then
content
else
mkNotdef;
/* mkOverride */
# Create an "Override" statement which allow the user to define
# prioprities between values. The default priority is 100 and the lowest
# priorities are kept. The template argument must reproduce the same
# attribute set hierachy to override leaves of the hierarchy.
isOverride = attrs: (typeOf attrs) == "override";
mkOverride = priority: template: content: mkProperty {
property = {
_type = "override";
onDelay = onOverrideDelay;
onGlobalEval = onOverrideGlobalEval;
inherit priority template;
};
inherit content;
};
# Sugar to override the default value of the option by making a new
# default value based on the configuration.
mkDefaultValue = content: mkOverride 1000 {} content;
# Make the template traversal in function of the property traversal. If
# the template define a non-empty attribute set, then the property is
# copied only on all mentionned attributes inside the template.
# Otherwise, the property is kept on all sub-attribute definitions.
onOverrideDelay = name: p@{property, content, ...}:
let inherit (property) template; in
if isAttrs template && template != {} then
if hasAttr name template then
p // {
property = p.property // {
template = builtins.getAttr name template;
};
}
# Do not override the attribute \name\
else
content
# Override values defined inside the attribute \name\.
else
p;
# Ignore all values which have a higher value of the priority number.
onOverrideGlobalEval = valList:
let
defaultPrio = 100;
inherit (builtins) lessThan;
getPrioVal =
foldProperty
(foldFilter isOverride
(p@{property, content, ...}:
if content ? priority && lessThan content.priority property.priority then
content
else
content // {
inherit (property) priority;
}
)
(p@{property, content, ...}:
content // {
value = p // { content = content.value; };
}
)
) (value: { inherit value; });
addDefaultPrio = x:
if x ? priority then x
else x // { priority = defaultPrio; };
prioValList = map (x: addDefaultPrio (getPrioVal x)) valList;
higherPrio =
if prioValList == [] then
defaultPrio
else
fold (x: min:
if lessThan x.priority min then
x.priority
else
min
) (head prioValList).priority (tail prioValList);
in
map (x:
if x.priority == higherPrio then
x.value
else
mkNotdef
) prioValList;
}