Add 'nixpkgs/' from commit 'abf060725d7614bd3b9f96764262dfbc2f9c2199'

git-subtree-dir: nixpkgs
git-subtree-mainline: 4e31070265257dc67d120c27e0f75c2344fdfa9a
git-subtree-split: abf060725d7614bd3b9f96764262dfbc2f9c2199

1 files changed, 207 insertions, 0 deletions

diff --git a/nixpkgs/lib/options.nix b/nixpkgs/lib/options.nix
new file mode 100644
index 000000000000..791930eafbd0
--- /dev/null
+++ b/nixpkgs/lib/options.nix
@@ -0,0 +1,207 @@
+# Nixpkgs/NixOS option handling.
+{ lib }:
+
+with lib.trivial;
+with lib.lists;
+with lib.attrsets;
+with lib.strings;
+
+rec {
+
+  /* Returns true when the given argument is an option
+
+     Type: isOption :: a -> bool
+
+     Example:
+       isOption 1             // => false
+       isOption (mkOption {}) // => true
+  */
+  isOption = lib.isType "option";
+
+  /* Creates an Option attribute set. mkOption accepts an attribute set with the following keys:
+
+     All keys default to `null` when not given.
+
+     Example:
+       mkOption { }  // => { _type = "option"; }
+       mkOption { defaultText = "foo"; } // => { _type = "option"; defaultText = "foo"; }
+  */
+  mkOption =
+    {
+    # Default value used when no definition is given in the configuration.
+    default ? null,
+    # Textual representation of the default, for the manual.
+    defaultText ? null,
+    # Example value used in the manual.
+    example ? null,
+    # String describing the option.
+    description ? null,
+    # Related packages used in the manual (see `genRelatedPackages` in ../nixos/doc/manual/default.nix).
+    relatedPackages ? null,
+    # Option type, providing type-checking and value merging.
+    type ? null,
+    # Function that converts the option value to something else.
+    apply ? null,
+    # Whether the option is for NixOS developers only.
+    internal ? null,
+    # Whether the option shows up in the manual.
+    visible ? null,
+    # Whether the option can be set only once
+    readOnly ? null,
+    # Obsolete, used by types.optionSet.
+    options ? null
+    } @ attrs:
+    attrs // { _type = "option"; };
+
+  /* Creates an Option attribute set for a boolean value option i.e an
+     option to be toggled on or off:
+
+     Example:
+       mkEnableOption "foo"
+       => { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }
+  */
+  mkEnableOption =
+    # Name for the created option
+    name: mkOption {
+    default = false;
+    example = true;
+    description = "Whether to enable ${name}.";
+    type = lib.types.bool;
+  };
+
+  /* This option accepts anything, but it does not produce any result.
+
+     This is useful for sharing a module across different module sets
+     without having to implement similar features as long as the
+     values of the options are not accessed. */
+  mkSinkUndeclaredOptions = attrs: mkOption ({
+    internal = true;
+    visible = false;
+    default = false;
+    description = "Sink for option definitions.";
+    type = mkOptionType {
+      name = "sink";
+      check = x: true;
+      merge = loc: defs: false;
+    };
+    apply = x: throw "Option value is not readable because the option is not declared.";
+  } // attrs);
+
+  mergeDefaultOption = loc: defs:
+    let list = getValues defs; in
+    if length list == 1 then head list
+    else if all isFunction list then x: mergeDefaultOption loc (map (f: f x) list)
+    else if all isList list then concatLists list
+    else if all isAttrs list then foldl' lib.mergeAttrs {} list
+    else if all isBool list then foldl' lib.or false list
+    else if all isString list then lib.concatStrings list
+    else if all isInt list && all (x: x == head list) list then head list
+    else throw "Cannot merge definitions of `${showOption loc}' given in ${showFiles (getFiles defs)}.";
+
+  mergeOneOption = loc: defs:
+    if defs == [] then abort "This case should never happen."
+    else if length defs != 1 then
+      throw "The unique option `${showOption loc}' is defined multiple times, in ${showFiles (getFiles defs)}."
+    else (head defs).value;
+
+  /* "Merge" option definitions by checking that they all have the same value. */
+  mergeEqualOption = loc: defs:
+    if defs == [] then abort "This case should never happen."
+    else foldl' (val: def:
+      if def.value != val then
+        throw "The option `${showOption loc}' has conflicting definitions, in ${showFiles (getFiles defs)}."
+      else
+        val) (head defs).value defs;
+
+  /* Extracts values of all "value" keys of the given list.
+
+     Type: getValues :: [ { value :: a } ] -> [a]
+
+     Example:
+       getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
+       getValues [ ]                               // => [ ]
+  */
+  getValues = map (x: x.value);
+
+  /* Extracts values of all "file" keys of the given list
+
+     Type: getFiles :: [ { file :: a } ] -> [a]
+
+     Example:
+       getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
+       getFiles [ ]                                         // => [ ]
+  */
+  getFiles = map (x: x.file);
+
+  # Generate documentation template from the list of option declaration like
+  # the set generated with filterOptionSets.
+  optionAttrSetToDocList = optionAttrSetToDocList' [];
+
+  optionAttrSetToDocList' = prefix: options:
+    concatMap (opt:
+      let
+        docOption = rec {
+          loc = opt.loc;
+          name = showOption opt.loc;
+          description = opt.description or (throw "Option `${name}' has no description.");
+          declarations = filter (x: x != unknownModule) opt.declarations;
+          internal = opt.internal or false;
+          visible = opt.visible or true;
+          readOnly = opt.readOnly or false;
+          type = opt.type.description or null;
+        }
+        // optionalAttrs (opt ? example) { example = scrubOptionValue opt.example; }
+        // optionalAttrs (opt ? default) { default = scrubOptionValue opt.default; }
+        // optionalAttrs (opt ? defaultText) { default = opt.defaultText; }
+        // optionalAttrs (opt ? relatedPackages && opt.relatedPackages != null) { inherit (opt) relatedPackages; };
+
+        subOptions =
+          let ss = opt.type.getSubOptions opt.loc;
+          in if ss != {} then optionAttrSetToDocList' opt.loc ss else [];
+      in
+        [ docOption ] ++ subOptions) (collect isOption options);
+
+
+  /* This function recursively removes all derivation attributes from
+     `x` except for the `name` attribute.
+
+     This is to make the generation of `options.xml` much more
+     efficient: the XML representation of derivations is very large
+     (on the order of megabytes) and is not actually used by the
+     manual generator.
+  */
+  scrubOptionValue = x:
+    if isDerivation x then
+      { type = "derivation"; drvPath = x.name; outPath = x.name; name = x.name; }
+    else if isList x then map scrubOptionValue x
+    else if isAttrs x then mapAttrs (n: v: scrubOptionValue v) (removeAttrs x ["_args"])
+    else x;
+
+
+  /* For use in the `example` option attribute. It causes the given
+     text to be included verbatim in documentation. This is necessary
+     for example values that are not simple values, e.g., functions.
+  */
+  literalExample = text: { _type = "literalExample"; inherit text; };
+
+  # Helper functions.
+
+  /* Convert an option, described as a list of the option parts in to a
+     safe, human readable version.
+
+     Example:
+       (showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
+       (showOption ["foo" "bar.baz" "tux"]) == "foo.\"bar.baz\".tux"
+  */
+  showOption = parts: let
+    escapeOptionPart = part:
+      let
+        escaped = lib.strings.escapeNixString part;
+      in if escaped == "\"${part}\""
+         then part
+         else escaped;
+    in (concatStringsSep ".") (map escapeOptionPart parts);
+  showFiles = files: concatStringsSep " and " (map (f: "`${f}'") files);
+  unknownModule = "<unknown-file>";
+
+}