NixOS / nixpkgs option handling

`lib.options.isOption`

isOption :: a -> bool

Returns true when the given argument is an option

lib.options.isOption usage example

isOption 1             // => false
isOption (mkOption {}) // => true

`lib.options.mkOption`

Creates an Option attribute set. mkOption accepts an attribute set with the following keys:

All keys default to null when not given.

pattern - structured function argument

default: Default value used when no definition is given in the configuration.
defaultText: Textual representation of the default, for the manual.
example: Example value used in the manual.
description: String describing the option.
relatedPackages: Related packages used in the manual (see genRelatedPackages in ../nixos/lib/make-options-doc/default.nix).
type: Option type, providing type-checking and value merging.
apply: Function that converts the option value to something else.
internal: Whether the option is for NixOS developers only.
visible: Whether the option shows up in the manual. Default: true. Use false to hide the option and any sub-options from submodules. Use "shallow" to hide only sub-options.
readOnly: Whether the option can be set only once

lib.options.mkOption usage example

mkOption { }  // => { _type = "option"; }
mkOption { default = "foo"; } // => { _type = "option"; default = "foo"; }

`lib.options.mkEnableOption`

Creates an Option attribute set for a boolean value option i.e an option to be toggled on or off:

name: Name for the created option

lib.options.mkEnableOption usage example

mkEnableOption "foo"
=> { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }

mkPackageOption :: pkgs -> string -> { default :: [string], example :: null | string | [string] } -> optionThe package is specified as a list of strings representing its attribute path in nixpkgs.Because of this, you need to pass nixpkgs itself as the first argument.The second argument is the name of the option, used in the description "The <name> package to use.".You can also pass an example value, either a literal string or a package's attribute path.You can omit the default path if the name of the option is also attribute path in nixpkgs.

Creates an Option attribute set for an option that specifies the package a module should use for some purpose.

pkgs: Package set (a specific version of nixpkgs)
name: Name for the package, shown in option description

pattern - structured function argument

default: Function argument
example: Function argument

lib.options.mkPackageOption usage example

mkPackageOption pkgs "hello" { }
=> { _type = "option"; default = «derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv»; defaultText = { ... }; description = "The hello package to use."; type = { ... }; }


mkPackageOption pkgs "GHC" {
default = [ "ghc" ];
example = "pkgs.haskell.packages.ghc924.ghc.withPackages (hkgs: [ hkgs.primes ])";
}
=> { _type = "option"; default = «derivation /nix/store/jxx55cxsjrf8kyh3fp2ya17q99w7541r-ghc-8.10.7.drv»; defaultText = { ... }; description = "The GHC package to use."; example = { ... }; type = { ... }; }

`lib.options.mkSinkUndeclaredOptions`

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.

attrs: Function argument

`lib.options.mergeEqualOption`

"Merge" option definitions by checking that they all have the same value.

loc: Function argument
defs: Function argument

`lib.options.getValues`

getValues :: [ { value :: a } ] -> [a]

Extracts values of all "value" keys of the given list.

lib.options.getValues usage example

getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
getValues [ ]                               // => [ ]

`lib.options.getFiles`

getFiles :: [ { file :: a } ] -> [a]

Extracts values of all "file" keys of the given list

lib.options.getFiles usage example

getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
getFiles [ ]                                         // => [ ]

`lib.options.scrubOptionValue`

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.

x: Function argument

`lib.options.literalExpression`

For use in the defaultText and example option attributes. Causes the given string to be rendered verbatim in the documentation as Nix code. This is necessary for complex values, e.g. functions, or values that depend on other values or packages.

text: Function argument

`lib.options.literalDocBook`

For use in the defaultText and example option attributes. Causes the given DocBook text to be inserted verbatim in the documentation, for when a literalExpression would be too hard to read.

text: Function argument

`lib.options.mdDoc`

Transition marker for documentation that's already migrated to markdown syntax.

text: Function argument

`lib.options.literalMD`

For use in the defaultText and example option attributes. Causes the given MD text to be inserted verbatim in the documentation, for when a literalExpression would be too hard to read.

text: Function argument

`lib.options.showOption`

Convert an option, described as a list of the option parts in to a safe, human readable version.

parts: Function argument

lib.options.showOption usage example

(showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
(showOption ["foo" "bar.baz" "tux"]) == "foo.bar.baz.tux"

Placeholders will not be quoted as they are not actual values:
(showOption ["foo" "*" "bar"]) == "foo.*.bar"
(showOption ["foo" "<name>" "bar"]) == "foo.<name>.bar"

Unlike attributes, options can also start with numbers:
(showOption ["windowManager" "2bwm" "enable"]) == "windowManager.2bwm.enable"