Mirrors/home-manager
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs, dconf: GVariant documentation improvements

Browse source 
PR #3956
This commit is contained in:
Robert Helgesson 2023-05-07 12:42:23 +02:00
parent c752906800 0b4ec66640
commit 990b82ecd3
No known key found for this signature in database
GPG key ID: 36BDAA14C2797E89
2 changed files with 65 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

108
docs/writing-modules.adoc
View file

@ -7,7 +7,7 @@ The module system in Home Manager is based entirely on the NixOS module system s
[[sec-option-types]] [[sec-option-types]]
=== Option Types === Option Types
:wikipedia-dag: https://en.wikipedia.org/w/index.php?title=Directed_acyclic_graph&oldid=939656095 :wikipedia-dag: https://en.wikipedia.org/w/index.php?title=Directed_acyclic_graph&oldid=939656095
:gvariant-description: https://developer.gnome.org/glib/stable/glib-GVariant.html#glib-GVariant.description :gvariant-description: https://docs.gtk.org/glib/struct.Variant.html#description
Overall the basic option types are the same in Home Manager as NixOS. A few Home Manager options, however, make use of custom types that are worth describing in more detail. These are the option types `dagOf` and `gvariant` that are used, for example, by <<opt-programs.ssh.matchBlocks>> and <<opt-dconf.settings>>. Overall the basic option types are the same in Home Manager as NixOS. A few Home Manager options, however, make use of custom types that are worth describing in more detail. These are the option types `dagOf` and `gvariant` that are used, for example, by <<opt-programs.ssh.matchBlocks>> and <<opt-dconf.settings>>.
@ -77,13 +77,13 @@ foo.bar = {
+ +
would place `c` before `b` and after `a` in the graph. would place `c` before `b` and after `a` in the graph.
`hm.types.gvariant`:: [[sec-option-types-gvariant]]`hm.types.gvariant`::
This type is useful for options representing {gvariant-description}[GVariant] values. The type accepts all primitive GVariant types as well as arrays and tuples. Dictionaries are not currently supported. This type is useful for options representing {gvariant-description}[GVariant] values. The type accepts all primitive GVariant types as well as arrays, tuples, ``maybe'' types, and dictionaries.
+ +
To create a GVariant value you can use a number of provided functions. Examples assume an option `foo.bar` of type `hm.types.gvariant`. Some Nix values are automatically coerced to matching GVariant value but the GVariant model is richer so you may need to use one of the provided constructor functions. Examples assume an option `foo.bar` of type `hm.types.gvariant`.
+ +
`hm.gvariant.mkBoolean (v: bool)`::: [[sec-option-types-gvariant-mkBoolean]]`hm.gvariant.mkBoolean (v: bool)`:::
Takes a Nix value `v` to a GVariant `boolean` value. Note, Nix booleans are automatically coerced using this function. That is, Takes a Nix value `v` to a GVariant `boolean` value (GVariant format string `b`). Note, Nix booleans are automatically coerced using this function. That is,
+ +
[source,nix] [source,nix]
---- ----
@ -96,8 +96,8 @@ is equivalent to
---- ----
foo.bar = true; foo.bar = true;
---- ----
`hm.gvariant.mkString (v: string)`::: [[sec-option-types-gvariant-mkString]]`hm.gvariant.mkString (v: string)`:::
Takes a Nix value `v` to a GVariant `string` value. Note, Nix strings are automatically coerced using this function. That is, Takes a Nix value `v` to a GVariant `string` value (GVariant format string `s`). Note, Nix strings are automatically coerced using this function. That is,
+ +
[source,nix] [source,nix]
---- ----
@ -110,16 +110,16 @@ is equivalent to
---- ----
foo.bar = "a string"; foo.bar = "a string";
---- ----
`hm.gvariant.mkObjectpath (v: string)`::: [[sec-option-types-gvariant-mkObjectpath]]`hm.gvariant.mkObjectpath (v: string)`:::
Takes a Nix value `v` to a GVariant `objectpath` value. Takes a Nix value `v` to a GVariant `objectpath` value (GVariant format string `o`).
`hm.gvariant.mkUchar (v: string)`::: [[sec-option-types-gvariant-mkUchar]]`hm.gvariant.mkUchar (v: string)`:::
Takes a Nix value `v` to a GVariant `uchar` value. Takes a Nix value `v` to a GVariant `uchar` value (GVariant format string `y`).
`hm.gvariant.mkInt16 (v: int)`::: [[sec-option-types-gvariant-mkInt16]]`hm.gvariant.mkInt16 (v: int)`:::
Takes a Nix value `v` to a GVariant `int16` value. Takes a Nix value `v` to a GVariant `int16` value (GVariant format string `n`).
`hm.gvariant.mkUint16 (v: int)`::: [[sec-option-types-gvariant-mkUint16]]`hm.gvariant.mkUint16 (v: int)`:::
Takes a Nix value `v` to a GVariant `uint16` value. Takes a Nix value `v` to a GVariant `uint16` value (GVariant format string `q`).
`hm.gvariant.mkInt32 (v: int)`::: [[sec-option-types-gvariant-mkInt32]]`hm.gvariant.mkInt32 (v: int)`:::
Takes a Nix value `v` to a GVariant `int32` value. Note, Nix integers are automatically coerced using this function. That is, Takes a Nix value `v` to a GVariant `int32` value (GVariant format string `i`). Note, Nix integers are automatically coerced using this function. That is,
+ +
[source,nix] [source,nix]
---- ----
@ -132,14 +132,14 @@ is equivalent to
---- ----
foo.bar = 7; foo.bar = 7;
---- ----
`hm.gvariant.mkUint32 (v: int)`::: [[sec-option-types-gvariant-mkUint32]]`hm.gvariant.mkUint32 (v: int)`:::
Takes a Nix value `v` to a GVariant `uint32` value. Takes a Nix value `v` to a GVariant `uint32` value (GVariant format string `u`).
`hm.gvariant.mkInt64 (v: int)`::: [[sec-option-types-gvariant-mkInt64]]`hm.gvariant.mkInt64 (v: int)`:::
Takes a Nix value `v` to a GVariant `int64` value. Takes a Nix value `v` to a GVariant `int64` value (GVariant format string `x`).
`hm.gvariant.mkUint64 (v: int)`::: [[sec-option-types-gvariant-mkUint64]]`hm.gvariant.mkUint64 (v: int)`:::
Takes a Nix value `v` to a GVariant `uint64` value. Takes a Nix value `v` to a GVariant `uint64` value (GVariant format string `t`).
`hm.gvariant.mkDouble (v: double)`::: [[sec-option-types-gvariant-mkDouble]]`hm.gvariant.mkDouble (v: double)`:::
Takes a Nix value `v` to a GVariant `double` value. Note, Nix floats are automatically coerced using this function. That is, Takes a Nix value `v` to a GVariant `double` value (GVariant format string `d`). Note, Nix floats are automatically coerced using this function. That is,
+ +
[source,nix] [source,nix]
---- ----
@ -153,43 +153,43 @@ is equivalent to
foo.bar = 3.14; foo.bar = 3.14;
---- ----
+ +
`hm.gvariant.mkArray type elements`::: [[sec-option-types-gvariant-mkArray]]`hm.gvariant.mkArray type elements`:::
Builds a GVariant array containing the given list of elements, where each element is a GVariant value of the given type. The `type` value can be constructed using Builds a GVariant array containing the given list of elements, where each element is a GVariant value of the given type (GVariant format string `a${type}`). The `type` value can be constructed using
+ +
-- --
- `hm.gvariant.type.string` - `hm.gvariant.type.string` (GVariant format string `s`)
- `hm.gvariant.type.boolean` - `hm.gvariant.type.boolean` (GVariant format string `b`)
- `hm.gvariant.type.uchar` - `hm.gvariant.type.uchar` (GVariant format string `y`)
- `hm.gvariant.type.int16` - `hm.gvariant.type.int16` (GVariant format string `n`)
- `hm.gvariant.type.uint16` - `hm.gvariant.type.uint16` (GVariant format string `q`)
- `hm.gvariant.type.int32` - `hm.gvariant.type.int32` (GVariant format string `i`)
- `hm.gvariant.type.uint32` - `hm.gvariant.type.uint32` (GVariant format string `u`)
- `hm.gvariant.type.int64` - `hm.gvariant.type.int64` (GVariant format string `x`)
- `hm.gvariant.type.uint64` - `hm.gvariant.type.uint64` (GVariant format string `t`)
- `hm.gvariant.type.double` - `hm.gvariant.type.double` (GVariant format string `d`)
- `hm.gvariant.type.variant` - `hm.gvariant.type.variant` (GVariant format string `v`)
- `hm.gvariant.type.arrayOf type` - `hm.gvariant.type.arrayOf type` (GVariant format string `a${type}`)
- `hm.gvariant.type.maybeOf type` - `hm.gvariant.type.maybeOf type` (GVariant format string `m${type}`)
- `hm.gvariant.type.tupleOf types` - `hm.gvariant.type.tupleOf types` (GVariant format string `(${lib.concatStrings types})`)
- `hm.gvariant.type.dictionaryEntryOf types` - `hm.gvariant.type.dictionaryEntryOf [keyType valueType]` (GVariant format string `{${keyType}${valueType}}`)
-- --
+ +
where `type` and `types` are themselves a type and list of types, respectively. where `type` and `types` are themselves a type and list of types, respectively.
+ +
`hm.gvariant.mkEmptyArray type`::: [[sec-option-types-gvariant-mkEmptyArray]]`hm.gvariant.mkEmptyArray type`:::
An alias of `hm.gvariant.mkArray type []`. An alias of <<sec-option-types-gvariant-mkArray,`hm.gvariant.mkArray type []`>>.
+ +
`hm.gvariant.mkNothing type`::: [[sec-option-types-gvariant-mkNothing]]`hm.gvariant.mkNothing type`:::
Builds a GVariant maybe value whose (non-existent) element is of the given type. The `type` value is constructed as described for the `mkArray` function above. Builds a GVariant maybe value (GVariant format string `m${type}`) whose (non-existent) element is of the given type. The `type` value is constructed as described for the <<sec-option-types-gvariant-mkArray,`mkArray`>> function above.
+ +
`hm.gvariant.mkJust element`::: [[sec-option-types-gvariant-mkJust]]`hm.gvariant.mkJust element`:::
Builds a GVariant maybe value containing the given GVariant element. Builds a GVariant maybe value (GVariant format string `m${element.type}`) containing the given GVariant element.
+ +
`hm.gvariant.mkTuple elements`::: [[sec-option-types-gvariant-mkTuple]]`hm.gvariant.mkTuple elements`:::
Builds a GVariant tuple containing the given list of elements, where each element is a GVariant value. Builds a GVariant tuple containing the given list of elements, where each element is a GVariant value.
+ +
`hm.gvariant.mkVariant element`::: [[sec-option-types-gvariant-mkVariant]]`hm.gvariant.mkVariant element`:::
Builds a GVariant variant which contains the value of a GVariant element. Builds a GVariant variant (GVariant format string `v`) which contains the value of a GVariant element.
+ +
`hm.gvariant.mkDictionaryEntry elements`::: [[sec-option-types-gvariant-mkDictionaryEntry]]`hm.gvariant.mkDictionaryEntry [key value]`:::
Builds a GVariant dictionary entry containing the given list of elements, where each element is a GVariant value. Builds a GVariant dictionary entry containing the given list of elements (GVariant format string `{${key.type}${value.type}}`), where each element is a GVariant value.

11
modules/misc/dconf.nix
View file

@ -59,6 +59,17 @@ in {
''; '';
description = '' description = ''
Settings to write to the dconf configuration system. Settings to write to the dconf configuration system.
</para><para>
Note that the database is strongly-typed so you need to use the same types
as described in the GSettings schema. For example, if an option is of type
<literal>uint32</literal> (<literal>u</literal>), you need to wrap the number
using the <literal>lib.hm.gvariant.mkUint32</literal> constructor.
Otherwise, since Nix integers are implicitly coerced to <literal>int32</literal>
(<literal>i</literal>), it would get stored in the database as such, and GSettings
might be confused when loading the setting.
</para><para>
You might want to use <link xlink:href="https://github.com/gvolpe/dconf2nix">dconf2nix</link>
to convert dconf database dumps into compatible Nix expression.
''; '';
}; };
}; };