lib.generators: functions that create file formats from nix data structures

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

Further Documentation can be found here.

`lib.generators.mkValueStringDefault`

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.

Inputs

Options : Empty set, there may be configuration options in the future

v : 2. Function argument

Located at lib/generators.nix:90 in <nixpkgs>.

`lib.generators.mkKeyValueDefault`

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"

Inputs

Structured function argument : mkValueString (optional, default: mkValueStringDefault {}) : Function to convert values to strings

sep

: 2. Function argument

k

: 3. Function argument

v

: 4. Function argument

Located at lib/generators.nix:147 in <nixpkgs>.

`lib.generators.toKeyValue`

Generate a key-value-style config file from an attrset.

Inputs

Structured function argument

: mkKeyValue (optional, default: mkKeyValueDefault {} "=") : format a setting line from key and value

: listsAsDuplicateKeys (optional, default: false) : allow lists as values for duplicate keys

: indent (optional, default: "") : Initial indentation level

Located at lib/generators.nix:173 in <nixpkgs>.

`lib.generators.toINI`

Generate an INI-style config file from an attrset of sections to an attrset of key-value pairs.

Inputs

Structured function argument

: mkSectionName (optional, default: (name: escape [ "[" "]" ] name)) : apply transformations (e.g. escapes) to section names

: mkKeyValue (optional, default: {} "=") : format a setting line from key and value

: listsAsDuplicateKeys (optional, default: false) : allow lists as values for duplicate keys

Examples

lib.generators.toINI usage example

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.

Located at lib/generators.nix:227 in <nixpkgs>.

`lib.generators.toINIWithGlobalSection`

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.

Inputs

1. Structured function argument

: mkSectionName (optional, default: (name: escape [ "[" "]" ] name)) : apply transformations (e.g. escapes) to section names

: mkKeyValue (optional, default: {} "=") : format a setting line from key and value

: listsAsDuplicateKeys (optional, default: false) : allow lists as values for duplicate keys

2. Structured function argument

: globalSection (required) : global section key-value pairs

: sections (optional, default: {}) : attrset of sections to key-value pairs

Examples

lib.generators.toINIWithGlobalSection usage example

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.

Located at lib/generators.nix:305 in <nixpkgs>.

`lib.generators.toGitINI`

Generate a git-config file from an attrset.

It has two major differences from the regular INI format:

values are indented with tabs
sections can have sub-sections

Further: https://git-scm.com/docs/git-config#EXAMPLES

Examples

lib.generators.toGitINI usage example

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"

Inputs

attrs

: Key-value pairs to be converted to a git-config file. See: https://git-scm.com/docs/git-config#_variables for possible values.

Located at lib/generators.nix:353 in <nixpkgs>.

`lib.generators.mkDconfKeyValue`

mkKeyValueDefault wrapper that handles dconf INI quirks. The main differences of the format is that it requires strings to be quoted.

Located at lib/generators.nix:400 in <nixpkgs>.

`lib.generators.toDconfINI`

Generates INI in dconf keyfile style. See https://help.gnome.org/admin/system-admin-guide/stable/dconf-keyfiles.html.en for details.

Located at lib/generators.nix:406 in <nixpkgs>.

`lib.generators.withRecursion`

Recurses through a Value limited to a certain depth. (depthLimit)

If the depth is exceeded, an error is thrown, unless throwOnDepthLimit is set to false.

Inputs

Structured function argument

: depthLimit (required) : If this option is not null, the given value will stop evaluating at a certain depth

: throwOnDepthLimit (optional, default: true) : If this option is true, an error will be thrown, if a certain given depth is exceeded

Value : The value to be evaluated recursively

Located at lib/generators.nix:426 in <nixpkgs>.

`lib.generators.toPretty`

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.

Inputs

Structured function argument : allowPrettyValues : 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.) : multiline : If this option is true, the output is indented with newlines for attribute sets and lists : indent : Initial indentation level

Value : The value to be pretty printed

Located at lib/generators.nix:483 in <nixpkgs>.

`lib.generators.toPlist`

Translate a simple Nix expression to Plist notation.

Inputs

Options : Empty set, there may be configuration options in the future

Value : The value to be converted to Plist

Located at lib/generators.nix:557 in <nixpkgs>.

`lib.generators.toDhall`

Translate a simple Nix expression to Dhall notation.

Note that integers are translated to Integer and never the Natural type.

Inputs

Options

: Empty set, there may be configuration options in the future

Value

: The value to be converted to Dhall

Located at lib/generators.nix:622 in <nixpkgs>.

`lib.generators.toLua`

Translate a simple Nix expression to Lua representation with occasional Lua-inlines that can be constructed by mkLuaInline function.

Configuration:

multiline - by default is true which results in indented block-like view.
indent - initial indent.
asBindings - by default generate single value, but with this use attrset to set global vars.

Attention:

Regardless of multiline parameter there is no trailing newline.

Inputs

Structured function argument

: multiline (optional, default: true) : If this option is true, the output is indented with newlines for attribute sets and lists : indent (optional, default: "") : Initial indentation level : asBindings (optional, default: false) : Interpret as variable bindings

Value

: The value to be converted to Lua

Type

toLua :: AttrSet -> Any -> String

Examples

lib.generators.toLua usage example

generators.toLua {}
  {
    cmd = [ "typescript-language-server" "--stdio" ];
    settings.workspace.library = mkLuaInline ''vim.api.nvim_get_runtime_file("", true)'';
  }
->
 {
   ["cmd"] = {
     "typescript-language-server",
     "--stdio"
   },
   ["settings"] = {
     ["workspace"] = {
       ["library"] = (vim.api.nvim_get_runtime_file("", true))
     }
   }
 }

Located at lib/generators.nix:704 in <nixpkgs>.

`lib.generators.mkLuaInline`

Mark string as Lua expression to be inlined when processed by toLua.

Inputs

expr

: 1. Function argument

Type

mkLuaInline :: String -> AttrSet

Located at lib/generators.nix:771 in <nixpkgs>.