diff options
author | Naïm Favier <n@monade.li> | 2021-10-03 17:19:19 +0200 |
---|---|---|
committer | Naïm Favier <n@monade.li> | 2021-10-03 17:19:19 +0200 |
commit | 52a2e4136e270f9efd6838adb69304fe6d4d431e (patch) | |
tree | e7343cc6a8e7b34c27e235d99a1b1c04531b78af /lib | |
parent | c3bf08d1b0597e730be0271137f928df90c8b13b (diff) | |
download | nixlib-52a2e4136e270f9efd6838adb69304fe6d4d431e.tar nixlib-52a2e4136e270f9efd6838adb69304fe6d4d431e.tar.gz nixlib-52a2e4136e270f9efd6838adb69304fe6d4d431e.tar.bz2 nixlib-52a2e4136e270f9efd6838adb69304fe6d4d431e.tar.lz nixlib-52a2e4136e270f9efd6838adb69304fe6d4d431e.tar.xz nixlib-52a2e4136e270f9efd6838adb69304fe6d4d431e.tar.zst nixlib-52a2e4136e270f9efd6838adb69304fe6d4d431e.zip |
lib/options: add literalExpression and literalDocBook, deprecate literalExample
Diffstat (limited to 'lib')
-rw-r--r-- | lib/default.nix | 4 | ||||
-rw-r--r-- | lib/options.nix | 24 |
2 files changed, 21 insertions, 7 deletions
diff --git a/lib/default.nix b/lib/default.nix index bb99a1be8a8c..3f942eb5fb9e 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -123,8 +123,8 @@ let inherit (self.options) isOption mkEnableOption mkSinkUndeclaredOptions mergeDefaultOption mergeOneOption mergeEqualOption getValues getFiles optionAttrSetToDocList optionAttrSetToDocList' - scrubOptionValue literalExample showOption showFiles - unknownModule mkOption; + scrubOptionValue literalExpression literalExample literalDocBook + showOption showFiles unknownModule mkOption; inherit (self.types) isType setType defaultTypeMerge defaultFunctor isOptionType mkOptionType; inherit (self.asserts) diff --git a/lib/options.nix b/lib/options.nix index 119a67fb7d82..b3164181312e 100644 --- a/lib/options.nix +++ b/lib/options.nix @@ -54,7 +54,7 @@ rec { Example: mkOption { } // => { _type = "option"; } - mkOption { defaultText = "foo"; } // => { _type = "option"; defaultText = "foo"; } + mkOption { default = "foo"; } // => { _type = "option"; default = "foo"; } */ mkOption = { @@ -212,11 +212,25 @@ rec { 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. + /* 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. */ - literalExample = text: { _type = "literalExample"; inherit text; }; + literalExpression = text: + if ! isString text then throw "literalExpression expects a string." + else { _type = "literalExpression"; inherit text; }; + + literalExample = lib.warn "literalExample is deprecated, use literalExpression instead, or use literalDocBook for a non-Nix description." literalExpression; + + + /* 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. + */ + literalDocBook = text: + if ! isString text then throw "literalDocBook expects a string." + else { _type = "literalDocBook"; inherit text; }; # Helper functions. |