pyrox.dev
Merge pull request #126004 from ryantm/md-generators
doc/functions/generators: convert to CommonMark
authored by Ryan Mulligan and committed by GitHub 8eab3bef 2072bba9
+1
-1
doc/functions.xml
+1
-1
doc/functions.xml
···
7
7
The nixpkgs repository has several utility functions to manipulate Nix expressions.
8
8
</para>
9
9
<xi:include href="functions/library.xml" />
10
-
<xi:include href="functions/generators.xml" />
10
+
<xi:include href="functions/generators.section.xml" />
11
11
<xi:include href="functions/debug.section.xml" />
12
12
<xi:include href="functions/prefer-remote-fetch.section.xml" />
13
13
<xi:include href="functions/nix-gitignore.section.xml" />
+56
doc/functions/generators.section.md
+56
doc/functions/generators.section.md
···
1
+
# Generators {#sec-generators}
2
+
Generators are functions that create file formats from nix data structures, e. g. for configuration files. There are generators available for: `INI`, `JSON` and `YAML`
3
+
4
+
All generators follow a similar call interface: `generatorName configFunctions data`, where `configFunctions` is an attrset of user-defined functions that format nested parts of the content. They each have common defaults, so often they do not need to be set manually. An example is `mkSectionName ? (name: libStr.escape [ "[" "]" ] name)` from the `INI` generator. It receives the name of a section and sanitizes it. The default `mkSectionName` escapes `[` and `]` with a backslash.
5
+
6
+
Generators can be fine-tuned to produce exactly the file format required by your application/service. One example is an INI-file format which uses `: ` as separator, the strings `"yes"`/`"no"` as boolean values and requires all string values to be quoted:
7
+
8
+
```nix
9
+
with lib;
10
+
let
11
+
customToINI = generators.toINI {
12
+
# specifies how to format a key/value pair
13
+
mkKeyValue = generators.mkKeyValueDefault {
14
+
# specifies the generated string for a subset of nix values
15
+
mkValueString = v:
16
+
if v == true then ''"yes"''
17
+
else if v == false then ''"no"''
18
+
else if isString v then ''"${v}"''
19
+
# and delegats all other values to the default generator
20
+
else generators.mkValueStringDefault {} v;
21
+
} ":";
22
+
};
23
+
24
+
# the INI file can now be given as plain old nix values
25
+
in customToINI {
26
+
main = {
27
+
pushinfo = true;
28
+
autopush = false;
29
+
host = "localhost";
30
+
port = 42;
31
+
};
32
+
mergetool = {
33
+
merge = "diff3";
34
+
};
35
+
}
36
+
```
37
+
38
+
This will produce the following INI file as nix string:
39
+
40
+
```INI
41
+
[main]
42
+
autopush:"no"
43
+
host:"localhost"
44
+
port:42
45
+
pushinfo:"yes"
46
+
str\:ange:"very::strange"
47
+
48
+
[mergetool]
49
+
merge:"diff3"
50
+
```
51
+
52
+
::: note
53
+
Nix store paths can be converted to strings by enclosing a derivation attribute like so: `"${drv}"`.
54
+
:::
55
+
56
+
Detailed documentation for each generator can be found in `lib/generators.nix`.
-74
doc/functions/generators.xml
-74
doc/functions/generators.xml
···
1
-
<section xmlns="http://docbook.org/ns/docbook"
2
-
xmlns:xlink="http://www.w3.org/1999/xlink"
3
-
xmlns:xi="http://www.w3.org/2001/XInclude"
4
-
xml:id="sec-generators">
5
-
<title>Generators</title>
6
-
7
-
<para>
8
-
Generators are functions that create file formats from nix data structures, e. g. for configuration files. There are generators available for: <literal>INI</literal>, <literal>JSON</literal> and <literal>YAML</literal>
9
-
</para>
10
-
11
-
<para>
12
-
All generators follow a similar call interface: <code>generatorName configFunctions data</code>, where <literal>configFunctions</literal> is an attrset of user-defined functions that format nested parts of the content. They each have common defaults, so often they do not need to be set manually. An example is <code>mkSectionName ? (name: libStr.escape [ "[" "]" ] name)</code> from the <literal>INI</literal> generator. It receives the name of a section and sanitizes it. The default <literal>mkSectionName</literal> escapes <literal>[</literal> and <literal>]</literal> with a backslash.
13
-
</para>
14
-
15
-
<para>
16
-
Generators can be fine-tuned to produce exactly the file format required by your application/service. One example is an INI-file format which uses <literal>: </literal> as separator, the strings <literal>"yes"</literal>/<literal>"no"</literal> as boolean values and requires all string values to be quoted:
17
-
</para>
18
-
19
-
<programlisting>
20
-
with lib;
21
-
let
22
-
customToINI = generators.toINI {
23
-
# specifies how to format a key/value pair
24
-
mkKeyValue = generators.mkKeyValueDefault {
25
-
# specifies the generated string for a subset of nix values
26
-
mkValueString = v:
27
-
if v == true then ''"yes"''
28
-
else if v == false then ''"no"''
29
-
else if isString v then ''"${v}"''
30
-
# and delegats all other values to the default generator
31
-
else generators.mkValueStringDefault {} v;
32
-
} ":";
33
-
};
34
-
35
-
# the INI file can now be given as plain old nix values
36
-
in customToINI {
37
-
main = {
38
-
pushinfo = true;
39
-
autopush = false;
40
-
host = "localhost";
41
-
port = 42;
42
-
};
43
-
mergetool = {
44
-
merge = "diff3";
45
-
};
46
-
}
47
-
</programlisting>
48
-
49
-
<para>
50
-
This will produce the following INI file as nix string:
51
-
</para>
52
-
53
-
<programlisting>
54
-
[main]
55
-
autopush:"no"
56
-
host:"localhost"
57
-
port:42
58
-
pushinfo:"yes"
59
-
str\:ange:"very::strange"
60
-
61
-
[mergetool]
62
-
merge:"diff3"
63
-
</programlisting>
64
-
65
-
<note>
66
-
<para>
67
-
Nix store paths can be converted to strings by enclosing a derivation attribute like so: <code>"${drv}"</code>.
68
-
</para>
69
-
</note>
70
-
71
-
<para>
72
-
Detailed documentation for each generator can be found in <literal>lib/generators.nix</literal>.
73
-
</para>
74
-
</section>