core/pkgs/pkgs-lib/formats.nix

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

678 lines
18 KiB
Nix
Raw Normal View History

2024-05-02 00:46:19 +00:00
{ lib, pkgs }:
rec {
/*
Every following entry represents a format for program configuration files
used for `settings`-style options (see https://github.com/NixOS/rfcs/pull/42).
Each entry should look as follows:
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
<format> = <parameters>: {
# ^^ Parameters for controlling the format
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
# The module system type most suitable for representing such a format
# The description needs to be overwritten for recursive types
type = ...;
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
# Utility functions for convenience, or special interactions with the
# format (optional)
2024-06-30 08:16:52 +00:00
lib = {
2024-05-02 00:46:19 +00:00
exampleFunction = ...
# Types specific to the format (optional)
types = { ... };
2024-06-30 08:16:52 +00:00
...
};
2024-05-02 00:46:19 +00:00
# generate :: Name -> Value -> Path
# A function for generating a file with a value of such a type
generate = ...;
2024-06-30 08:16:52 +00:00
});
2024-05-02 00:46:19 +00:00
Please note that `pkgs` may not always be available for use due to the split
options doc build introduced in fc614c37c653, so lazy evaluation of only the
'type' field is required.
2024-06-30 08:16:52 +00:00
*/
2024-05-02 00:46:19 +00:00
inherit (import ./formats/java-properties/default.nix { inherit lib pkgs; }) javaProperties;
libconfig = (import ./formats/libconfig/default.nix { inherit lib pkgs; }).format;
hocon = (import ./formats/hocon/default.nix { inherit lib pkgs; }).format;
json =
2024-06-30 08:16:52 +00:00
{ }:
{
2024-05-02 00:46:19 +00:00
2024-06-30 08:16:52 +00:00
type =
2024-05-02 00:46:19 +00:00
with lib.types;
2024-06-30 08:16:52 +00:00
let
2024-05-02 00:46:19 +00:00
valueType =
nullOr (oneOf [
2024-06-30 08:16:52 +00:00
bool
int
float
str
path
2024-05-02 00:46:19 +00:00
(attrsOf valueType)
(listOf valueType)
2024-06-30 08:16:52 +00:00
])
2024-05-02 00:46:19 +00:00
// {
description = "JSON value";
2024-06-30 08:16:52 +00:00
};
in
2024-05-02 00:46:19 +00:00
valueType;
generate =
name: value:
pkgs.callPackage (
{ runCommand, jq }:
runCommand name
2024-06-30 08:16:52 +00:00
{
2024-05-02 00:46:19 +00:00
nativeBuildInputs = [ jq ];
value = builtins.toJSON value;
passAsFile = [ "value" ];
2024-06-30 08:16:52 +00:00
}
''
2024-05-02 00:46:19 +00:00
jq . "$valuePath"> $out
2024-06-30 08:16:52 +00:00
''
) { };
2024-05-02 00:46:19 +00:00
};
yaml =
{ }:
2024-06-30 08:16:52 +00:00
{
2024-05-02 00:46:19 +00:00
generate =
name: value:
pkgs.callPackage (
{ runCommand, remarshal }:
runCommand name
2024-06-30 08:16:52 +00:00
{
2024-05-02 00:46:19 +00:00
nativeBuildInputs = [ remarshal ];
value = builtins.toJSON value;
passAsFile = [ "value" ];
2024-06-30 08:16:52 +00:00
}
''
2024-05-02 00:46:19 +00:00
json2yaml "$valuePath" "$out"
2024-06-30 08:16:52 +00:00
''
) { };
type =
2024-05-02 00:46:19 +00:00
with lib.types;
let
valueType =
nullOr (oneOf [
2024-06-30 08:16:52 +00:00
bool
2024-05-02 00:46:19 +00:00
int
2024-06-30 08:16:52 +00:00
float
str
path
2024-05-02 00:46:19 +00:00
(attrsOf valueType)
(listOf valueType)
2024-06-30 08:16:52 +00:00
])
// {
2024-05-02 00:46:19 +00:00
description = "YAML value";
2024-06-30 08:16:52 +00:00
};
in
2024-05-02 00:46:19 +00:00
valueType;
};
# the ini formats share a lot of code
inherit
(
let
singleIniAtom =
with lib.types;
nullOr (oneOf [
bool
int
float
str
])
// {
description = "INI atom (null, bool, int, float or string)";
};
iniAtom =
with lib.types;
{ listsAsDuplicateKeys, listToValue }:
if listsAsDuplicateKeys then
coercedTo singleIniAtom lib.singleton (listOf singleIniAtom)
// {
description = singleIniAtom.description + " or a list of them for duplicate keys";
}
else if listToValue != null then
coercedTo singleIniAtom lib.singleton (nonEmptyListOf singleIniAtom)
// {
description = singleIniAtom.description + " or a non-empty list of them";
}
else
singleIniAtom;
iniSection =
with lib.types;
{ listsAsDuplicateKeys, listToValue }@args:
attrsOf (iniAtom args)
// {
description = "section of an INI file (attrs of " + (iniAtom args).description + ")";
};
maybeToList =
listToValue:
if listToValue != null then
lib.mapAttrs (key: val: if lib.isList val then listToValue val else val)
else
lib.id;
in
{
ini =
2024-06-30 08:16:52 +00:00
{
2024-05-02 00:46:19 +00:00
# Represents lists as duplicate keys
listsAsDuplicateKeys ? false,
# Alternative to listsAsDuplicateKeys, converts list to non-list
# listToValue :: [IniAtom] -> IniAtom
listToValue ? null,
...
}@args:
assert listsAsDuplicateKeys -> listToValue == null;
{
type = lib.types.attrsOf (iniSection {
listsAsDuplicateKeys = listsAsDuplicateKeys;
listToValue = listToValue;
});
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
generate =
name: value:
lib.pipe value [
(lib.mapAttrs (_: maybeToList listToValue))
(lib.generators.toINI (removeAttrs args [ "listToValue" ]))
(pkgs.writeText name)
];
};
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
iniWithGlobalSection =
{
# Represents lists as duplicate keys
listsAsDuplicateKeys ? false,
# Alternative to listsAsDuplicateKeys, converts list to non-list
# listToValue :: [IniAtom] -> IniAtom
listToValue ? null,
...
}@args:
assert listsAsDuplicateKeys -> listToValue == null;
{
type = lib.types.submodule {
options = {
sections = lib.mkOption rec {
type = lib.types.attrsOf (iniSection {
listsAsDuplicateKeys = listsAsDuplicateKeys;
listToValue = listToValue;
});
default = { };
description = type.description;
};
globalSection = lib.mkOption rec {
type = iniSection {
listsAsDuplicateKeys = listsAsDuplicateKeys;
listToValue = listToValue;
};
default = { };
description = "global " + type.description;
2024-06-30 08:16:52 +00:00
};
2024-05-02 00:46:19 +00:00
};
};
generate =
2024-06-30 08:16:52 +00:00
name:
{
2024-05-02 00:46:19 +00:00
sections ? { },
globalSection ? { },
2024-06-30 08:16:52 +00:00
...
}:
2024-05-02 00:46:19 +00:00
pkgs.writeText name (
lib.generators.toINIWithGlobalSection (removeAttrs args [ "listToValue" ]) {
globalSection = maybeToList listToValue globalSection;
sections = lib.mapAttrs (_: maybeToList listToValue) sections;
2024-06-30 08:16:52 +00:00
}
);
2024-05-02 00:46:19 +00:00
};
gitIni =
{
listsAsDuplicateKeys ? false,
...
}@args:
{
type =
let
atom = iniAtom {
listsAsDuplicateKeys = listsAsDuplicateKeys;
listToValue = null;
2024-06-30 08:16:52 +00:00
};
in
2024-05-02 00:46:19 +00:00
with lib.types;
attrsOf (attrsOf (either atom (attrsOf atom)));
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
generate = name: value: pkgs.writeText name (lib.generators.toGitINI value);
};
}
)
ini
iniWithGlobalSection
gitIni
;
# As defined by systemd.syntax(7)
#
# null does not set any value, which allows for RFC42 modules to specify
# optional config options.
systemd =
let
mkValueString = lib.generators.mkValueStringDefault { };
mkKeyValue = k: v: if v == null then "# ${k} is unset" else "${k} = ${mkValueString v}";
in
ini {
listsAsDuplicateKeys = true;
inherit mkKeyValue;
};
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
keyValue =
{
# Represents lists as duplicate keys
listsAsDuplicateKeys ? false,
# Alternative to listsAsDuplicateKeys, converts list to non-list
# listToValue :: [Atom] -> Atom
listToValue ? null,
...
}@args:
assert listsAsDuplicateKeys -> listToValue == null;
{
type =
with lib.types;
let
singleAtom =
nullOr (oneOf [
2024-06-30 08:16:52 +00:00
bool
int
float
str
])
// {
2024-05-02 00:46:19 +00:00
description = "atom (null, bool, int, float or string)";
2024-06-30 08:16:52 +00:00
};
2024-05-02 00:46:19 +00:00
2024-06-30 08:16:52 +00:00
atom =
2024-05-02 00:46:19 +00:00
if listsAsDuplicateKeys then
coercedTo singleAtom lib.singleton (listOf singleAtom)
2024-06-30 08:16:52 +00:00
// {
2024-05-02 00:46:19 +00:00
description = singleAtom.description + " or a list of them for duplicate keys";
2024-06-30 08:16:52 +00:00
}
2024-05-02 00:46:19 +00:00
else if listToValue != null then
coercedTo singleAtom lib.singleton (nonEmptyListOf singleAtom)
2024-06-30 08:16:52 +00:00
// {
2024-05-02 00:46:19 +00:00
description = singleAtom.description + " or a non-empty list of them";
2024-06-30 08:16:52 +00:00
}
else
2024-05-02 00:46:19 +00:00
singleAtom;
2024-06-30 08:16:52 +00:00
in
2024-05-02 00:46:19 +00:00
attrsOf atom;
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
generate =
name: value:
let
transformedValue =
if listToValue != null then
lib.mapAttrs (key: val: if lib.isList val then listToValue val else val) value
else
value;
in
pkgs.writeText name (
lib.generators.toKeyValue (removeAttrs args [ "listToValue" ]) transformedValue
);
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
};
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
toml =
{ }:
json { }
// {
type =
with lib.types;
let
valueType =
oneOf [
bool
int
float
str
path
(attrsOf valueType)
(listOf valueType)
]
// {
description = "TOML value";
};
in
valueType;
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
generate =
name: value:
pkgs.callPackage (
{ runCommand, remarshal }:
runCommand name
{
nativeBuildInputs = [ remarshal ];
value = builtins.toJSON value;
passAsFile = [ "value" ];
}
''
json2toml "$valuePath" "$out"
''
) { };
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
};
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
/*
For configurations of Elixir project, like config.exs or runtime.exs
Most Elixir project are configured using the [Config] Elixir DSL
Since Elixir has more types than Nix, we need a way to map Nix types to
more than 1 Elixir type. To that end, this format provides its own library,
and its own set of types.
To be more detailed, a Nix attribute set could correspond in Elixir to a
[Keyword list] (the more common type), or it could correspond to a [Map].
A Nix string could correspond in Elixir to a [String] (also called
"binary"), an [Atom], or a list of chars (usually discouraged).
A Nix array could correspond in Elixir to a [List] or a [Tuple].
Some more types exists, like records, regexes, but since they are less used,
we can leave the `mkRaw` function as an escape hatch.
For more information on how to use this format in modules, please refer to
the Elixir section of the Nixos documentation.
TODO: special Elixir values doesn't show up nicely in the documentation
[Config]: <https://hexdocs.pm/elixir/Config.html>
[Keyword list]: <https://hexdocs.pm/elixir/Keyword.html>
[Map]: <https://hexdocs.pm/elixir/Map.html>
[String]: <https://hexdocs.pm/elixir/String.html>
[Atom]: <https://hexdocs.pm/elixir/Atom.html>
[List]: <https://hexdocs.pm/elixir/List.html>
[Tuple]: <https://hexdocs.pm/elixir/Tuple.html>
*/
elixirConf =
{
elixir ? pkgs.elixir,
}:
with lib;
let
toElixir =
value:
with builtins;
if value == null then
"nil"
else if value == true then
"true"
else if value == false then
"false"
else if isInt value || isFloat value then
toString value
else if isString value then
string value
else if isAttrs value then
attrs value
else if isList value then
list value
2024-06-30 08:16:52 +00:00
else
2024-05-02 00:46:19 +00:00
abort "formats.elixirConf: should never happen (value = ${value})";
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
escapeElixir = escape [
"\\"
"#"
"\""
];
string = value: "\"${escapeElixir value}\"";
attrs =
set:
if set ? _elixirType then
specialType set
else
let
toKeyword = name: value: "${name}: ${toElixir value}";
keywordList = concatStringsSep ", " (mapAttrsToList toKeyword set);
in
"[" + keywordList + "]";
listContent = values: concatStringsSep ", " (map toElixir values);
list = values: "[" + (listContent values) + "]";
specialType =
{ value, _elixirType }:
if _elixirType == "raw" then
value
else if _elixirType == "atom" then
value
else if _elixirType == "map" then
elixirMap value
else if _elixirType == "tuple" then
tuple value
2024-06-30 08:16:52 +00:00
else
2024-05-02 00:46:19 +00:00
abort "formats.elixirConf: should never happen (_elixirType = ${_elixirType})";
elixirMap =
set:
let
toEntry = name: value: "${toElixir name} => ${toElixir value}";
entries = concatStringsSep ", " (mapAttrsToList toEntry set);
in
"%{${entries}}";
tuple = values: "{${listContent values}}";
toConf =
values:
let
keyConfig =
rootKey: key: value:
"config ${rootKey}, ${key}, ${toElixir value}";
keyConfigs = rootKey: values: mapAttrsToList (keyConfig rootKey) values;
rootConfigs = flatten (mapAttrsToList keyConfigs values);
in
''
import Config
${concatStringsSep "\n" rootConfigs}
'';
in
{
type =
with lib.types;
let
valueType =
nullOr (oneOf [
bool
int
float
str
(attrsOf valueType)
(listOf valueType)
])
// {
description = "Elixir value";
};
in
attrsOf (attrsOf (valueType));
lib =
let
mkRaw = value: {
inherit value;
_elixirType = "raw";
};
in
{
inherit mkRaw;
# Fetch an environment variable at runtime, with optional fallback
mkGetEnv =
{
envVariable,
fallback ? null,
}:
mkRaw "System.get_env(${toElixir envVariable}, ${toElixir fallback})";
/*
Make an Elixir atom.
Note: lowercase atoms still need to be prefixed by ':'
*/
mkAtom = value: {
inherit value;
_elixirType = "atom";
};
# Make an Elixir tuple out of a list.
mkTuple = value: {
inherit value;
_elixirType = "tuple";
};
# Make an Elixir map out of an attribute set.
mkMap = value: {
inherit value;
_elixirType = "map";
};
/*
Contains Elixir types. Every type it exports can also be replaced
by raw Elixir code (i.e. every type is `either type rawElixir`).
It also reexports standard types, wrapping them so that they can
also be raw Elixir.
*/
types =
with lib.types;
let
isElixirType = type: x: (x._elixirType or "") == type;
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
rawElixir = mkOptionType {
name = "rawElixir";
description = "raw elixir";
check = isElixirType "raw";
};
elixirOr = other: either other rawElixir;
2024-06-30 08:16:52 +00:00
in
{
2024-05-02 00:46:19 +00:00
inherit rawElixir elixirOr;
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
atom = elixirOr (mkOptionType {
name = "elixirAtom";
description = "elixir atom";
check = isElixirType "atom";
2024-06-30 08:16:52 +00:00
});
2024-05-02 00:46:19 +00:00
tuple = elixirOr (mkOptionType {
name = "elixirTuple";
description = "elixir tuple";
check = isElixirType "tuple";
2024-06-30 08:16:52 +00:00
});
2024-05-02 00:46:19 +00:00
map = elixirOr (mkOptionType {
name = "elixirMap";
description = "elixir map";
check = isElixirType "map";
});
# Wrap standard types, since anything in the Elixir configuration
# can be raw Elixir
}
// lib.mapAttrs (_name: type: elixirOr type) lib.types;
};
generate =
name: value:
pkgs.runCommand name
{
value = toConf value;
passAsFile = [ "value" ];
nativeBuildInputs = [ elixir ];
}
''
cp "$valuePath" "$out"
mix format "$out"
'';
};
# Outputs a succession of Python variable assignments
# Useful for many Django-based services
pythonVars =
{ }:
{
type =
with lib.types;
let
valueType =
nullOr (oneOf [
bool
float
int
path
str
(attrsOf valueType)
(listOf valueType)
])
// {
description = "Python value";
};
in
attrsOf valueType;
generate =
name: value:
pkgs.callPackage (
{
runCommand,
python3,
black,
}:
runCommand name
{
nativeBuildInputs = [
python3
black
];
value = builtins.toJSON value;
pythonGen = ''
import json
import os
2024-06-30 08:16:52 +00:00
2024-05-02 00:46:19 +00:00
with open(os.environ["valuePath"], "r") as f:
for key, value in json.load(f).items():
print(f"{key} = {repr(value)}")
'';
passAsFile = [
"value"
"pythonGen"
];
}
''
cat "$valuePath"
python3 "$pythonGenPath" > $out
black $out
''
) { };
};
}