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 let
  10   inherit (lib) generators isString;
  11
  12   customToINI = generators.toINI {
  13     # specifies how to format a key/value pair
  14     mkKeyValue = generators.mkKeyValueDefault {
  15       # specifies the generated string for a subset of nix values
  16       mkValueString = v:
  17              if v == true then ''"yes"''
  18         else if v == false then ''"no"''
  19         else if isString v then ''"${v}"''
  20         # and delegates all other values to the default generator
  21         else generators.mkValueStringDefault {} v;
  22     } ":";
  23   };
  24
  25 # the INI file can now be given as plain old nix values
  26 in customToINI {
  27   main = {
  28     pushinfo = true;
  29     autopush = false;
  30     host = "localhost";
  31     port = 42;
  32   };
  33   mergetool = {
  34     merge = "diff3";
  35   };
  36 }
  37 ```
  38
  39 This will produce the following INI file as nix string:
  40
  41 ```INI
  42 [main]
  43 autopush:"no"
  44 host:"localhost"
  45 port:42
  46 pushinfo:"yes"
  47 str\:ange:"very::strange"
  48
  49 [mergetool]
  50 merge:"diff3"
  51 ```
  52
  53 ::: {.note}
  54 Nix store paths can be converted to strings by enclosing a derivation attribute like so: `"${drv}"`.
  55 :::
  56
  57 Detailed documentation for each generator can be found [here](#sec-functions-library-generators)