# Options for Program Settings {#sec-settings-options}

Many programs have configuration files where program-specific settings
can be declared. File formats can be separated into two categories:

-   Nix-representable ones: These can trivially be mapped to a subset of
    Nix syntax. E.g. JSON is an example, since its values like
    `{"foo":{"bar":10}}` can be mapped directly to Nix:
    `{ foo = { bar = 10; }; }`. Other examples are INI, YAML and TOML.
    The following section explains the convention for these settings.

-   Non-nix-representable ones: These can't be trivially mapped to a
    subset of Nix syntax. Most generic programming languages are in this
    group, e.g. bash, since the statement `if true; then echo hi; fi`
    doesn't have a trivial representation in Nix.

    Currently there are no fixed conventions for these, but it is common
    to have a `configFile` option for setting the configuration file
    path directly. The default value of `configFile` can be an
    auto-generated file, with convenient options for controlling the
    contents. For example an option of type `attrsOf str` can be used
    for representing environment variables which generates a section
    like `export FOO="foo"`. Often it can also be useful to also include
    an `extraConfig` option of type `lines` to allow arbitrary text
    after the autogenerated part of the file.

## Nix-representable Formats (JSON, YAML, TOML, INI, ...) {#sec-settings-nix-representable}

By convention, formats like this are handled with a generic `settings`
option, representing the full program configuration as a Nix value. The
type of this option should represent the format. The most common formats
have a predefined type and string generator already declared under
`pkgs.formats`:

`pkgs.formats.javaProperties` { *`comment`* ? `"Generated with Nix"` }

:   A function taking an attribute set with values

    `comment`

    :   A string to put at the start of the
        file in a comment. It can have multiple
        lines.

    It returns the `type`: `attrsOf str` and a function
    `generate` to build a Java `.properties` file, taking
    care of the correct escaping, etc.

`pkgs.formats.hocon` { *`generator`* ? `<derivation>`, *`validator`* ? `<derivation>`, *`doCheck`* ? true }

:  A function taking an attribute set with values

    `generator`

    :   A derivation used for converting the JSON output
        from the nix settings into HOCON. This might be
        useful if your HOCON variant is slightly different
        from the java-based one, or for testing purposes.

    `validator`

    :   A derivation used for verifying that the HOCON
        output is correct and parsable. This might be
        useful if your HOCON variant is slightly different
        from the java-based one, or for testing purposes.

    `doCheck`

    :   Whether to enable/disable the validator check.

    It returns an attrset with a `type`, `generate` function,
    and a `lib` attset, as specified [below](#pkgs-formats-result).
    Some of the lib functions will be best understood if you have
    read the reference specification. You can find this
    specification here:

    <https://github.com/lightbend/config/blob/main/HOCON.md>

    Inside of `lib`, you will find these functions

    `mkInclude`

    :   This is used together with a specially named
        attribute `includes`, to include other HOCON
        sources into the document.

        The function has a shorthand variant where it
        is up to the HOCON parser to figure out what type
        of include is being used. The include will default
        to being non-required. If you want to be more
        explicit about the details of the include, you can
        provide an attrset with following arguments

        `required`

        :   Whether the parser should fail upon failure
            to include the document

        `type`

        :   Type of the source of the included document.
            Valid values are `file`, `url` and `classpath`.