-
-
Notifications
You must be signed in to change notification settings - Fork 12.7k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
nixpkgs docs: move generators to its own file
- Loading branch information
Showing
2 changed files
with
91 additions
and
87 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,90 @@ | ||
| <section xmlns="http://docbook.org/ns/docbook" | ||
| xmlns:xlink="http://www.w3.org/1999/xlink" | ||
| xmlns:xi="http://www.w3.org/2001/XInclude" | ||
| xml:id="sec-generators"> | ||
| <title>Generators</title> | ||
|
|
||
| <para> | ||
| 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> | ||
| </para> | ||
|
|
||
| <para> | ||
| 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. | ||
| </para> | ||
|
|
||
| <para> | ||
| 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: | ||
| </para> | ||
|
|
||
| <programlisting> | ||
| with lib; | ||
| let | ||
| customToINI = generators.toINI { | ||
| # specifies how to format a key/value pair | ||
| mkKeyValue = generators.mkKeyValueDefault { | ||
| # specifies the generated string for a subset of nix values | ||
| mkValueString = v: | ||
| if v == true then ''"yes"'' | ||
| else if v == false then ''"no"'' | ||
| else if isString v then ''"${v}"'' | ||
| # and delegats all other values to the default generator | ||
| else generators.mkValueStringDefault {} v; | ||
| } ":"; | ||
| }; | ||
|
|
||
| # the INI file can now be given as plain old nix values | ||
| in customToINI { | ||
| main = { | ||
| pushinfo = true; | ||
| autopush = false; | ||
| host = "localhost"; | ||
| port = 42; | ||
| }; | ||
| mergetool = { | ||
| merge = "diff3"; | ||
| }; | ||
| } | ||
| </programlisting> | ||
|
|
||
| <para> | ||
| This will produce the following INI file as nix string: | ||
| </para> | ||
|
|
||
| <programlisting> | ||
| [main] | ||
| autopush:"no" | ||
| host:"localhost" | ||
| port:42 | ||
| pushinfo:"yes" | ||
| str\:ange:"very::strange" | ||
|
|
||
| [mergetool] | ||
| merge:"diff3" | ||
| </programlisting> | ||
|
|
||
| <note> | ||
| <para> | ||
| Nix store paths can be converted to strings by enclosing a derivation | ||
| attribute like so: <code>"${drv}"</code>. | ||
| </para> | ||
| </note> | ||
|
|
||
| <para> | ||
| Detailed documentation for each generator can be found in | ||
| <literal>lib/generators.nix</literal>. | ||
| </para> | ||
| </section> |