6a117e2759
Render un`_type`d defaults and examples as `literalExpression`s using
`lib.generators.toPretty` so that consumers don't have to reinvent Nix
pretty-printing. `renderOptionValue` is kept internal for now intentionally.
Make `toPretty` print floats as valid Nix values (without a tilde).
Get rid of the now-obsolete `substSpecial` function.
Move towards disallowing evaluation of packages in the manual by
raising a warning on `pkgs.foo.{outPath,drvPath}`; later, this should
throw an error. Instead, module authors should use `literalExpression`
and `mkPackageOption`.
425 lines
15 KiB
Nix
425 lines
15 KiB
Nix
/* Functions that generate widespread file
|
||
* formats from nix data structures.
|
||
*
|
||
* They all follow a similar interface:
|
||
* generator { config-attrs } data
|
||
*
|
||
* `config-attrs` are “holes” in the generators
|
||
* with sensible default implementations that
|
||
* can be overwritten. The default implementations
|
||
* are mostly generators themselves, called with
|
||
* their respective default values; they can be reused.
|
||
*
|
||
* Tests can be found in ./tests/misc.nix
|
||
* Documentation in the manual, #sec-generators
|
||
*/
|
||
{ lib }:
|
||
with (lib).trivial;
|
||
let
|
||
libStr = lib.strings;
|
||
libAttr = lib.attrsets;
|
||
|
||
inherit (lib) isFunction;
|
||
in
|
||
|
||
rec {
|
||
|
||
## -- HELPER FUNCTIONS & DEFAULTS --
|
||
|
||
/* Convert a value to a sensible default string representation.
|
||
* The builtin `toString` function has some strange defaults,
|
||
* suitable for bash scripts but not much else.
|
||
*/
|
||
mkValueStringDefault = {}: v: with builtins;
|
||
let err = t: v: abort
|
||
("generators.mkValueStringDefault: " +
|
||
"${t} not supported: ${toPretty {} v}");
|
||
in if isInt v then toString v
|
||
# convert derivations to store paths
|
||
else if lib.isDerivation v then toString v
|
||
# we default to not quoting strings
|
||
else if isString v then v
|
||
# isString returns "1", which is not a good default
|
||
else if true == v then "true"
|
||
# here it returns to "", which is even less of a good default
|
||
else if false == v then "false"
|
||
else if null == v then "null"
|
||
# if you have lists you probably want to replace this
|
||
else if isList v then err "lists" v
|
||
# same as for lists, might want to replace
|
||
else if isAttrs v then err "attrsets" v
|
||
# functions can’t be printed of course
|
||
else if isFunction v then err "functions" v
|
||
# Floats currently can't be converted to precise strings,
|
||
# condition warning on nix version once this isn't a problem anymore
|
||
# See https://github.com/NixOS/nix/pull/3480
|
||
else if isFloat v then libStr.floatToString v
|
||
else err "this value is" (toString v);
|
||
|
||
|
||
/* Generate a line of key k and value v, separated by
|
||
* character sep. If sep appears in k, it is escaped.
|
||
* Helper for synaxes with different separators.
|
||
*
|
||
* mkValueString specifies how values should be formatted.
|
||
*
|
||
* mkKeyValueDefault {} ":" "f:oo" "bar"
|
||
* > "f\:oo:bar"
|
||
*/
|
||
mkKeyValueDefault = {
|
||
mkValueString ? mkValueStringDefault {}
|
||
}: sep: k: v:
|
||
"${libStr.escape [sep] k}${sep}${mkValueString v}";
|
||
|
||
|
||
## -- FILE FORMAT GENERATORS --
|
||
|
||
|
||
/* Generate a key-value-style config file from an attrset.
|
||
*
|
||
* mkKeyValue is the same as in toINI.
|
||
*/
|
||
toKeyValue = {
|
||
mkKeyValue ? mkKeyValueDefault {} "=",
|
||
listsAsDuplicateKeys ? false
|
||
}:
|
||
let mkLine = k: v: mkKeyValue k v + "\n";
|
||
mkLines = if listsAsDuplicateKeys
|
||
then k: v: map (mkLine k) (if lib.isList v then v else [v])
|
||
else k: v: [ (mkLine k v) ];
|
||
in attrs: libStr.concatStrings (lib.concatLists (libAttr.mapAttrsToList mkLines attrs));
|
||
|
||
|
||
/* Generate an INI-style config file from an
|
||
* attrset of sections to an attrset of key-value pairs.
|
||
*
|
||
* generators.toINI {} {
|
||
* foo = { hi = "${pkgs.hello}"; ciao = "bar"; };
|
||
* baz = { "also, integers" = 42; };
|
||
* }
|
||
*
|
||
*> [baz]
|
||
*> also, integers=42
|
||
*>
|
||
*> [foo]
|
||
*> ciao=bar
|
||
*> hi=/nix/store/y93qql1p5ggfnaqjjqhxcw0vqw95rlz0-hello-2.10
|
||
*
|
||
* The mk* configuration attributes can generically change
|
||
* the way sections and key-value strings are generated.
|
||
*
|
||
* For more examples see the test cases in ./tests/misc.nix.
|
||
*/
|
||
toINI = {
|
||
# apply transformations (e.g. escapes) to section names
|
||
mkSectionName ? (name: libStr.escape [ "[" "]" ] name),
|
||
# format a setting line from key and value
|
||
mkKeyValue ? mkKeyValueDefault {} "=",
|
||
# allow lists as values for duplicate keys
|
||
listsAsDuplicateKeys ? false
|
||
}: attrsOfAttrs:
|
||
let
|
||
# map function to string for each key val
|
||
mapAttrsToStringsSep = sep: mapFn: attrs:
|
||
libStr.concatStringsSep sep
|
||
(libAttr.mapAttrsToList mapFn attrs);
|
||
mkSection = sectName: sectValues: ''
|
||
[${mkSectionName sectName}]
|
||
'' + toKeyValue { inherit mkKeyValue listsAsDuplicateKeys; } sectValues;
|
||
in
|
||
# map input to ini sections
|
||
mapAttrsToStringsSep "\n" mkSection attrsOfAttrs;
|
||
|
||
/* Generate an INI-style config file from an attrset
|
||
* specifying the global section (no header), and an
|
||
* attrset of sections to an attrset of key-value pairs.
|
||
*
|
||
* generators.toINIWithGlobalSection {} {
|
||
* globalSection = {
|
||
* someGlobalKey = "hi";
|
||
* };
|
||
* sections = {
|
||
* foo = { hi = "${pkgs.hello}"; ciao = "bar"; };
|
||
* baz = { "also, integers" = 42; };
|
||
* }
|
||
*
|
||
*> someGlobalKey=hi
|
||
*>
|
||
*> [baz]
|
||
*> also, integers=42
|
||
*>
|
||
*> [foo]
|
||
*> ciao=bar
|
||
*> hi=/nix/store/y93qql1p5ggfnaqjjqhxcw0vqw95rlz0-hello-2.10
|
||
*
|
||
* The mk* configuration attributes can generically change
|
||
* the way sections and key-value strings are generated.
|
||
*
|
||
* For more examples see the test cases in ./tests/misc.nix.
|
||
*
|
||
* If you don’t need a global section, you can also use
|
||
* `generators.toINI` directly, which only takes
|
||
* the part in `sections`.
|
||
*/
|
||
toINIWithGlobalSection = {
|
||
# apply transformations (e.g. escapes) to section names
|
||
mkSectionName ? (name: libStr.escape [ "[" "]" ] name),
|
||
# format a setting line from key and value
|
||
mkKeyValue ? mkKeyValueDefault {} "=",
|
||
# allow lists as values for duplicate keys
|
||
listsAsDuplicateKeys ? false
|
||
}: { globalSection, sections }:
|
||
( if globalSection == {}
|
||
then ""
|
||
else (toKeyValue { inherit mkKeyValue listsAsDuplicateKeys; } globalSection)
|
||
+ "\n")
|
||
+ (toINI { inherit mkSectionName mkKeyValue listsAsDuplicateKeys; } sections);
|
||
|
||
/* Generate a git-config file from an attrset.
|
||
*
|
||
* It has two major differences from the regular INI format:
|
||
*
|
||
* 1. values are indented with tabs
|
||
* 2. sections can have sub-sections
|
||
*
|
||
* generators.toGitINI {
|
||
* url."ssh://git@github.com/".insteadOf = "https://github.com";
|
||
* user.name = "edolstra";
|
||
* }
|
||
*
|
||
*> [url "ssh://git@github.com/"]
|
||
*> insteadOf = https://github.com/
|
||
*>
|
||
*> [user]
|
||
*> name = edolstra
|
||
*/
|
||
toGitINI = attrs:
|
||
with builtins;
|
||
let
|
||
mkSectionName = name:
|
||
let
|
||
containsQuote = libStr.hasInfix ''"'' name;
|
||
sections = libStr.splitString "." name;
|
||
section = head sections;
|
||
subsections = tail sections;
|
||
subsection = concatStringsSep "." subsections;
|
||
in if containsQuote || subsections == [ ] then
|
||
name
|
||
else
|
||
''${section} "${subsection}"'';
|
||
|
||
# generation for multiple ini values
|
||
mkKeyValue = k: v:
|
||
let mkKeyValue = mkKeyValueDefault { } " = " k;
|
||
in concatStringsSep "\n" (map (kv: "\t" + mkKeyValue kv) (lib.toList v));
|
||
|
||
# converts { a.b.c = 5; } to { "a.b".c = 5; } for toINI
|
||
gitFlattenAttrs = let
|
||
recurse = path: value:
|
||
if isAttrs value && !lib.isDerivation value then
|
||
lib.mapAttrsToList (name: value: recurse ([ name ] ++ path) value) value
|
||
else if length path > 1 then {
|
||
${concatStringsSep "." (lib.reverseList (tail path))}.${head path} = value;
|
||
} else {
|
||
${head path} = value;
|
||
};
|
||
in attrs: lib.foldl lib.recursiveUpdate { } (lib.flatten (recurse [ ] attrs));
|
||
|
||
toINI_ = toINI { inherit mkKeyValue mkSectionName; };
|
||
in
|
||
toINI_ (gitFlattenAttrs attrs);
|
||
|
||
/* Generates JSON from an arbitrary (non-function) value.
|
||
* For more information see the documentation of the builtin.
|
||
*/
|
||
toJSON = {}: builtins.toJSON;
|
||
|
||
|
||
/* YAML has been a strict superset of JSON since 1.2, so we
|
||
* use toJSON. Before it only had a few differences referring
|
||
* to implicit typing rules, so it should work with older
|
||
* parsers as well.
|
||
*/
|
||
toYAML = toJSON;
|
||
|
||
withRecursion =
|
||
{
|
||
/* If this option is not null, the given value will stop evaluating at a certain depth */
|
||
depthLimit
|
||
/* If this option is true, an error will be thrown, if a certain given depth is exceeded */
|
||
, throwOnDepthLimit ? true
|
||
}:
|
||
assert builtins.isInt depthLimit;
|
||
let
|
||
specialAttrs = [
|
||
"__functor"
|
||
"__functionArgs"
|
||
"__toString"
|
||
"__pretty"
|
||
];
|
||
stepIntoAttr = evalNext: name:
|
||
if builtins.elem name specialAttrs
|
||
then id
|
||
else evalNext;
|
||
transform = depth:
|
||
if depthLimit != null && depth > depthLimit then
|
||
if throwOnDepthLimit
|
||
then throw "Exceeded maximum eval-depth limit of ${toString depthLimit} while trying to evaluate with `generators.withRecursion'!"
|
||
else const "<unevaluated>"
|
||
else id;
|
||
mapAny = with builtins; depth: v:
|
||
let
|
||
evalNext = x: mapAny (depth + 1) (transform (depth + 1) x);
|
||
in
|
||
if isAttrs v then mapAttrs (stepIntoAttr evalNext) v
|
||
else if isList v then map evalNext v
|
||
else transform (depth + 1) v;
|
||
in
|
||
mapAny 0;
|
||
|
||
/* Pretty print a value, akin to `builtins.trace`.
|
||
* Should probably be a builtin as well.
|
||
* The pretty-printed string should be suitable for rendering default values
|
||
* in the NixOS manual. In particular, it should be as close to a valid Nix expression
|
||
* as possible.
|
||
*/
|
||
toPretty = {
|
||
/* If this option is true, attrsets like { __pretty = fn; val = …; }
|
||
will use fn to convert val to a pretty printed representation.
|
||
(This means fn is type Val -> String.) */
|
||
allowPrettyValues ? false,
|
||
/* If this option is true, the output is indented with newlines for attribute sets and lists */
|
||
multiline ? true
|
||
}:
|
||
let
|
||
go = indent: v: with builtins;
|
||
let isPath = v: typeOf v == "path";
|
||
introSpace = if multiline then "\n${indent} " else " ";
|
||
outroSpace = if multiline then "\n${indent}" else " ";
|
||
in if isInt v then toString v
|
||
# toString loses precision on floats, so we use toJSON instead. This isn't perfect
|
||
# as the resulting string may not parse back as a float (e.g. 42, 1e-06), but for
|
||
# pretty-printing purposes this is acceptable.
|
||
else if isFloat v then builtins.toJSON v
|
||
else if isString v then
|
||
let
|
||
lines = filter (v: ! isList v) (builtins.split "\n" v);
|
||
escapeSingleline = libStr.escape [ "\\" "\"" "\${" ];
|
||
escapeMultiline = libStr.replaceStrings [ "\${" "''" ] [ "''\${" "'''" ];
|
||
singlelineResult = "\"" + concatStringsSep "\\n" (map escapeSingleline lines) + "\"";
|
||
multilineResult = let
|
||
escapedLines = map escapeMultiline lines;
|
||
# The last line gets a special treatment: if it's empty, '' is on its own line at the "outer"
|
||
# indentation level. Otherwise, '' is appended to the last line.
|
||
lastLine = lib.last escapedLines;
|
||
in "''" + introSpace + concatStringsSep introSpace (lib.init escapedLines)
|
||
+ (if lastLine == "" then outroSpace else introSpace + lastLine) + "''";
|
||
in
|
||
if multiline && length lines > 1 then multilineResult else singlelineResult
|
||
else if true == v then "true"
|
||
else if false == v then "false"
|
||
else if null == v then "null"
|
||
else if isPath v then toString v
|
||
else if isList v then
|
||
if v == [] then "[ ]"
|
||
else "[" + introSpace
|
||
+ libStr.concatMapStringsSep introSpace (go (indent + " ")) v
|
||
+ outroSpace + "]"
|
||
else if isFunction v then
|
||
let fna = lib.functionArgs v;
|
||
showFnas = concatStringsSep ", " (libAttr.mapAttrsToList
|
||
(name: hasDefVal: if hasDefVal then name + "?" else name)
|
||
fna);
|
||
in if fna == {} then "<function>"
|
||
else "<function, args: {${showFnas}}>"
|
||
else if isAttrs v then
|
||
# apply pretty values if allowed
|
||
if allowPrettyValues && v ? __pretty && v ? val
|
||
then v.__pretty v.val
|
||
else if v == {} then "{ }"
|
||
else if v ? type && v.type == "derivation" then
|
||
"<derivation ${v.name or "???"}>"
|
||
else "{" + introSpace
|
||
+ libStr.concatStringsSep introSpace (libAttr.mapAttrsToList
|
||
(name: value:
|
||
"${libStr.escapeNixIdentifier name} = ${go (indent + " ") value};") v)
|
||
+ outroSpace + "}"
|
||
else abort "generators.toPretty: should never happen (v = ${v})";
|
||
in go "";
|
||
|
||
# PLIST handling
|
||
toPlist = {}: v: let
|
||
isFloat = builtins.isFloat or (x: false);
|
||
expr = ind: x: with builtins;
|
||
if x == null then "" else
|
||
if isBool x then bool ind x else
|
||
if isInt x then int ind x else
|
||
if isString x then str ind x else
|
||
if isList x then list ind x else
|
||
if isAttrs x then attrs ind x else
|
||
if isFloat x then float ind x else
|
||
abort "generators.toPlist: should never happen (v = ${v})";
|
||
|
||
literal = ind: x: ind + x;
|
||
|
||
bool = ind: x: literal ind (if x then "<true/>" else "<false/>");
|
||
int = ind: x: literal ind "<integer>${toString x}</integer>";
|
||
str = ind: x: literal ind "<string>${x}</string>";
|
||
key = ind: x: literal ind "<key>${x}</key>";
|
||
float = ind: x: literal ind "<real>${toString x}</real>";
|
||
|
||
indent = ind: expr "\t${ind}";
|
||
|
||
item = ind: libStr.concatMapStringsSep "\n" (indent ind);
|
||
|
||
list = ind: x: libStr.concatStringsSep "\n" [
|
||
(literal ind "<array>")
|
||
(item ind x)
|
||
(literal ind "</array>")
|
||
];
|
||
|
||
attrs = ind: x: libStr.concatStringsSep "\n" [
|
||
(literal ind "<dict>")
|
||
(attr ind x)
|
||
(literal ind "</dict>")
|
||
];
|
||
|
||
attr = let attrFilter = name: value: name != "_module" && value != null;
|
||
in ind: x: libStr.concatStringsSep "\n" (lib.flatten (lib.mapAttrsToList
|
||
(name: value: lib.optionals (attrFilter name value) [
|
||
(key "\t${ind}" name)
|
||
(expr "\t${ind}" value)
|
||
]) x));
|
||
|
||
in ''<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||
<plist version="1.0">
|
||
${expr "" v}
|
||
</plist>'';
|
||
|
||
/* Translate a simple Nix expression to Dhall notation.
|
||
* Note that integers are translated to Integer and never
|
||
* the Natural type.
|
||
*/
|
||
toDhall = { }@args: v:
|
||
with builtins;
|
||
let concatItems = lib.strings.concatStringsSep ", ";
|
||
in if isAttrs v then
|
||
"{ ${
|
||
concatItems (lib.attrsets.mapAttrsToList
|
||
(key: value: "${key} = ${toDhall args value}") v)
|
||
} }"
|
||
else if isList v then
|
||
"[ ${concatItems (map (toDhall args) v)} ]"
|
||
else if isInt v then
|
||
"${if v < 0 then "" else "+"}${toString v}"
|
||
else if isBool v then
|
||
(if v then "True" else "False")
|
||
else if isFunction v then
|
||
abort "generators.toDhall: cannot convert a function to Dhall"
|
||
else if isNull v then
|
||
abort "generators.toDhall: cannot convert a null to Dhall"
|
||
else
|
||
builtins.toJSON v;
|
||
}
|