aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBruno Victal <mirai@makinata.eu>2023-03-26 19:41:29 +0100
committerLiliana Marie Prikler <liliana.prikler@gmail.com>2023-04-02 12:31:51 +0200
commit6f48efa9b89f3c33f7b2827cae88e87ec64faa09 (patch)
tree23a236dd58239e625aa540d68cbd833f40371af5 /doc
parent2ebbe8e9df66d6607cafa38a79926e4c9ac0d151 (diff)
downloadguix-6f48efa9b89f3c33f7b2827cae88e87ec64faa09.tar
guix-6f48efa9b89f3c33f7b2827cae88e87ec64faa09.tar.gz
services: configuration: Add user-defined sanitizer support.
This changes the 'custom-serializer' field into a generic 'extra-args' field that can be extended to support new literals. Within extra-args, the literals 'sanitizer' and 'serializer' allow for user-defined sanitization and serialization procedures respectively. The 'empty-serializer' was also added as a literal to be used as before. To prevent confusion between the new “explicit” style of specifying a sanitizer, and the old “implicit” style, the latter has been deprecated, and a warning is issued if it is encountered. * gnu/services/configuration.scm (define-configuration-helper): Rename 'custom-serializer' to 'extra-args'. Add support for literals 'sanitizer', 'serializer' and 'empty-serializer'. Rename procedure 'field-sanitizer' to 'default-field-sanitizer' to avoid syntax clash. Only define default field sanitizers if user-defined ones are absent. (normalize-extra-args): New variable. (<configuration-field>)[sanitizer]: New field. * doc/guix.texi (Complex Configurations): Document the newly added literals. * tests/services/configuration.scm: Add tests for the new literals. Signed-off-by: Liliana Marie Prikler <liliana.prikler@gmail.com>
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi29
1 files changed, 27 insertions, 2 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index a58ea8f9ec..495a930d0d 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -41219,7 +41219,7 @@ A clause can have one of the following forms:
(@var{field-name}
(@var{type} @var{default-value})
@var{documentation}
- @var{serializer})
+ (serializer @var{serializer}))
(@var{field-name}
(@var{type})
@@ -41228,7 +41228,18 @@ A clause can have one of the following forms:
(@var{field-name}
(@var{type})
@var{documentation}
- @var{serializer})
+ (serializer @var{serializer}))
+
+(@var{field-name}
+ (@var{type})
+ @var{documentation}
+ (sanitizer @var{sanitizer})
+
+(@var{field-name}
+ (@var{type})
+ @var{documentation}
+ (sanitizer @var{sanitizer})
+ (serializer @var{serializer}))
@end example
@var{field-name} is an identifier that denotes the name of the field in
@@ -41251,6 +41262,20 @@ an object of the record type.
@var{documentation} is a string formatted with Texinfo syntax which
should provide a description of what setting this field does.
+@var{sanitizer} is a procedure which takes one argument,
+a user-supplied value, and returns a ``sanitized'' value for the field.
+If no sanitizer is specified, a default sanitizer is used, which raises
+an error if the value is not of type @var{type}.
+
+An example of a sanitizer for a field that accepts both strings and
+symbols looks like this:
+@lisp
+(define (sanitize-foo value)
+ (cond ((string? value) value)
+ ((symbol? value) (symbol->string value))
+ (else (error "bad value"))))
+@end lisp
+
@var{serializer} is the name of a procedure which takes two arguments,
the first is the name of the field, and the second is the value
corresponding to the field. The procedure should return a string or