mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-25 00:12:56 +00:00
nixos/doc: add documentation for formats.hocon and formats.libconfig (#320339)
This commit is contained in:
Artturin
GitHub
commit
7a199f5dd6
@ -46,6 +46,237 @@ have a predefined type and string generator already declared under
|
||||
`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`.
|
||||
See upstream documentation for the semantics
|
||||
behind each value
|
||||
|
||||
`value`
|
||||
|
||||
: The URI/path/classpath pointing to the source of
|
||||
the document to be included.
|
||||
|
||||
`Example usage:`
|
||||
|
||||
```nix
|
||||
let
|
||||
format = pkgs.formats.hocon { };
|
||||
hocon_file = pkgs.writeText "to_include.hocon" ''
|
||||
a = 1;
|
||||
'';
|
||||
in {
|
||||
some.nested.hocon.attrset = {
|
||||
_includes = [
|
||||
(format.lib.mkInclude hocon_file)
|
||||
(format.lib.mkInclude "https://example.com/to_include.hocon")
|
||||
(format.lib.mkInclude {
|
||||
required = true;
|
||||
type = "file";
|
||||
value = include_file;
|
||||
})
|
||||
];
|
||||
...
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
`mkAppend`
|
||||
|
||||
: This is used to invoke the `+=` operator.
|
||||
This can be useful if you need to add something
|
||||
to a list that is included from outside of nix.
|
||||
See upstream documentation for the semantics
|
||||
behind the `+=` operation.
|
||||
|
||||
`Example usage:`
|
||||
|
||||
```nix
|
||||
let
|
||||
format = pkgs.formats.hocon { };
|
||||
hocon_file = pkgs.writeText "to_include.hocon" ''
|
||||
a = [ 1 ];
|
||||
b = [ 2 ];
|
||||
'';
|
||||
in {
|
||||
_includes = [
|
||||
(format.lib.mkInclude hocon_file)
|
||||
];
|
||||
|
||||
c = 3;
|
||||
a = format.lib.mkAppend 3;
|
||||
b = format.lib.mkAppend (format.lib.mkSubstitution "c");
|
||||
}
|
||||
```
|
||||
|
||||
`mkSubstitution`
|
||||
|
||||
: This is used to make HOCON substitutions.
|
||||
Similarly to `mkInclude`, this function has
|
||||
a shorthand variant where you just give it
|
||||
the string with the substitution value.
|
||||
The substitution is not optional by default.
|
||||
Alternatively, you can provide an attrset
|
||||
with more options
|
||||
|
||||
`optional`
|
||||
|
||||
: Whether the parser should fail upon
|
||||
failure to fetch the substitution value.
|
||||
|
||||
`value`
|
||||
|
||||
: The name of the variable to use for
|
||||
substitution.
|
||||
|
||||
See upstream documentation for semantics
|
||||
behind the substitution functionality.
|
||||
|
||||
`Example usage:`
|
||||
|
||||
```nix
|
||||
let
|
||||
format = pkgs.formats.hocon { };
|
||||
in {
|
||||
a = 1;
|
||||
b = format.lib.mkSubstitution "a";
|
||||
c = format.lib.mkSubstition "SOME_ENVVAR";
|
||||
d = format.lib.mkSubstition {
|
||||
value = "SOME_OPTIONAL_ENVVAR";
|
||||
optional = true;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
`Implementation notes:`
|
||||
|
||||
- classpath includes are not implemented in pyhocon,
|
||||
which is used for validating the HOCON output. This
|
||||
means that if you are using classpath includes,
|
||||
you will want to either use an alternative validator
|
||||
or set `doCheck = false` in the format options.
|
||||
|
||||
`pkgs.formats.libconfig` { *`generator`* ? `<derivation>`, *`validator`* ? `<derivation>` }
|
||||
|
||||
: A function taking an attribute set with values
|
||||
|
||||
`generator`
|
||||
|
||||
: A derivation used for converting the JSON output
|
||||
from the nix settings into libconfig. This might be
|
||||
useful if your libconfig variant is slightly different
|
||||
from the original one, or for testing purposes.
|
||||
|
||||
`validator`
|
||||
|
||||
: A derivation used for verifying that the libconfig
|
||||
output is correct and parsable. This might be
|
||||
useful if your libconfig variant is slightly different
|
||||
from the original one, or for testing purposes.
|
||||
|
||||
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://hyperrealm.github.io/libconfig/libconfig_manual.html#Configuration-Files>
|
||||
|
||||
Inside of `lib`, you will find these functions
|
||||
|
||||
`mkHex`, `mkOctal`, `mkFloat`
|
||||
|
||||
: Use these to specify numbers in other formats.
|
||||
|
||||
`Example usage:`
|
||||
|
||||
```nix
|
||||
let
|
||||
format = pkgs.formats.libconfig { };
|
||||
in {
|
||||
myHexValue = format.lib.mkHex "0x1FC3";
|
||||
myOctalValue = format.lib.mkOctal "0027";
|
||||
myFloatValue = format.lib.mkFloat "1.2E-3";
|
||||
}
|
||||
```
|
||||
|
||||
`mkArray`, `mkList`
|
||||
|
||||
: Use these to differentiate between whether
|
||||
a nix list should be considered as a libconfig
|
||||
array or a libconfig list. See the upstream
|
||||
documentation for the semantics behind these types.
|
||||
|
||||
`Example usage:`
|
||||
|
||||
```nix
|
||||
let
|
||||
format = pkgs.formats.libconfig { };
|
||||
in {
|
||||
myList = format.lib.mkList [ "foo" 1 true ];
|
||||
myArray = format.lib.mkArray [ 1 2 3 ];
|
||||
}
|
||||
```
|
||||
|
||||
`Implementation notes:`
|
||||
|
||||
- Since libconfig does not allow setting names to start with an underscore,
|
||||
this is used as a prefix for both special types and include directives.
|
||||
|
||||
- The difference between 32bit and 64bit values became optional in libconfig
|
||||
1.5, so we assume 64bit values for all numbers.
|
||||
|
||||
`pkgs.formats.json` { }
|
||||
|
||||
: A function taking an empty attribute set (for future extensibility)
|
||||
|
||||
@ -27,13 +27,9 @@ let
|
||||
'';
|
||||
in
|
||||
{
|
||||
# https://github.com/lightbend/config/blob/main/HOCON.md
|
||||
format = {
|
||||
generator ? hocon-generator
|
||||
, validator ? hocon-validator
|
||||
# `include classpath("")` is not implemented in pyhocon.
|
||||
# In the case that you need this functionality,
|
||||
# you will have to disable pyhocon validation.
|
||||
, doCheck ? true
|
||||
}: let
|
||||
hoconLib = {
|
||||
|
||||
@ -3,14 +3,6 @@
|
||||
}:
|
||||
let
|
||||
inherit (pkgs) buildPackages callPackage;
|
||||
# Implementation notes:
|
||||
# Libconfig spec: https://hyperrealm.github.io/libconfig/libconfig_manual.html
|
||||
#
|
||||
# Since libconfig does not allow setting names to start with an underscore,
|
||||
# this is used as a prefix for both special types and include directives.
|
||||
#
|
||||
# The difference between 32bit and 64bit values became optional in libconfig
|
||||
# 1.5, so we assume 64bit values for all numbers.
|
||||
|
||||
libconfig-generator = buildPackages.rustPlatform.buildRustPackage {
|
||||
name = "libconfig-generator";
|
||||
|
||||
Loading…
Reference in New Issue
Block a user