doc: Rewrite define-configuration.
Rewrite this section to make it easier to document later syntactical changes. * doc/guix.texi (Complex Configurations): Rewrite define-configuration documentation. Fix simple serializer example. Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
This commit is contained in:
parent
dd65564db0
commit
3872ecf274
102
doc/guix.texi
102
doc/guix.texi
|
@ -42576,54 +42576,33 @@ and to make it easier to create Scheme bindings for these configuration
|
||||||
files, you can use the utilities defined in the @code{(gnu services
|
files, you can use the utilities defined in the @code{(gnu services
|
||||||
configuration)} module.
|
configuration)} module.
|
||||||
|
|
||||||
The main utility is the @code{define-configuration} macro, which you
|
The main utility is the @code{define-configuration} macro, a helper
|
||||||
will use to define a Scheme record type (@pxref{Record Overview,,,
|
used to define a Scheme record type (@pxref{Record Overview,,,
|
||||||
guile, GNU Guile Reference Manual}). The Scheme record will be
|
guile, GNU Guile Reference Manual}). The fields from this Scheme record
|
||||||
serialized to a configuration file by using @dfn{serializers}, which are
|
can be serialized using @dfn{serializers}, which are procedures that take
|
||||||
procedures that take some kind of Scheme value and returns a
|
some kind of Scheme value and translates them into another Scheme value or
|
||||||
G-expression (@pxref{G-Expressions}), which should, once serialized to
|
@ref{G-Expressions}.
|
||||||
the disk, return a string. More details are listed below.
|
|
||||||
|
|
||||||
@defmac define-configuration name clause1 clause2 @dots{}
|
@defmac define-configuration name clause1 clause2 @dots{}
|
||||||
Create a record type named @code{@var{name}} that contains the
|
Create a record type named @code{@var{name}} that contains the
|
||||||
fields found in the clauses.
|
fields found in the clauses.
|
||||||
|
|
||||||
A clause can have one of the following forms:
|
A clause has the following form:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
(@var{field-name}
|
(@var{field-name}
|
||||||
(@var{type} @var{default-value})
|
@var{type-decl}
|
||||||
@var{documentation})
|
|
||||||
|
|
||||||
(@var{field-name}
|
|
||||||
(@var{type} @var{default-value})
|
|
||||||
@var{documentation}
|
@var{documentation}
|
||||||
(serializer @var{serializer}))
|
@var{option*}
|
||||||
|
@dots{})
|
||||||
(@var{field-name}
|
|
||||||
(@var{type})
|
|
||||||
@var{documentation})
|
|
||||||
|
|
||||||
(@var{field-name}
|
|
||||||
(@var{type})
|
|
||||||
@var{documentation}
|
|
||||||
(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
|
@end example
|
||||||
|
|
||||||
@var{field-name} is an identifier that denotes the name of the field in
|
@var{field-name} is an identifier that denotes the name of the field in
|
||||||
the generated record.
|
the generated record.
|
||||||
|
|
||||||
|
@var{type-decl} is either @code{@var{type}} for fields that require a
|
||||||
|
value to be set or @code{(@var{type} @var{default})} otherwise.
|
||||||
|
|
||||||
@var{type} is the type of the value corresponding to @var{field-name};
|
@var{type} is the type of the value corresponding to @var{field-name};
|
||||||
since Guile is untyped, a predicate
|
since Guile is untyped, a predicate
|
||||||
procedure---@code{@var{type}?}---will be called on the value
|
procedure---@code{@var{type}?}---will be called on the value
|
||||||
|
@ -42641,6 +42620,28 @@ an object of the record type.
|
||||||
@var{documentation} is a string formatted with Texinfo syntax which
|
@var{documentation} is a string formatted with Texinfo syntax which
|
||||||
should provide a description of what setting this field does.
|
should provide a description of what setting this field does.
|
||||||
|
|
||||||
|
@var{option*} is one of the following subclauses:
|
||||||
|
|
||||||
|
@table @asis
|
||||||
|
@item @code{empty-serializer}
|
||||||
|
Exclude this field from serialization.
|
||||||
|
|
||||||
|
@item @code{(serializer @var{serializer})}
|
||||||
|
@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
|
||||||
|
@ref{G-Expressions} that represents the content that will be serialized
|
||||||
|
to the configuration file. If none is specified, a procedure of the
|
||||||
|
name @code{serialize-@var{type}} will be used.
|
||||||
|
|
||||||
|
An example of a simple serializer procedure:
|
||||||
|
@lisp
|
||||||
|
(define (serialize-boolean field-name value)
|
||||||
|
(let ((value (if value "true" "false")))
|
||||||
|
#~(string-append '#$field-name " = " #$value)))
|
||||||
|
@end lisp
|
||||||
|
|
||||||
|
@item @code{(sanitizer @var{sanitizer})}
|
||||||
@var{sanitizer} is a procedure which takes one argument,
|
@var{sanitizer} is a procedure which takes one argument,
|
||||||
a user-supplied value, and returns a ``sanitized'' value for the field.
|
a user-supplied value, and returns a ``sanitized'' value for the field.
|
||||||
If no sanitizer is specified, a default sanitizer is used, which raises
|
If no sanitizer is specified, a default sanitizer is used, which raises
|
||||||
|
@ -42654,21 +42655,7 @@ symbols looks like this:
|
||||||
((symbol? value) (symbol->string value))
|
((symbol? value) (symbol->string value))
|
||||||
(else (error "bad value"))))
|
(else (error "bad value"))))
|
||||||
@end lisp
|
@end lisp
|
||||||
|
@end table
|
||||||
@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
|
|
||||||
G-expression (@pxref{G-Expressions}) that represents the content that
|
|
||||||
will be serialized to the configuration file. If none is specified, a
|
|
||||||
procedure of the name @code{serialize-@var{type}} will be used.
|
|
||||||
|
|
||||||
A simple serializer procedure could look like this:
|
|
||||||
|
|
||||||
@lisp
|
|
||||||
(define (serialize-boolean field-name value)
|
|
||||||
(let ((value (if value "true" "false")))
|
|
||||||
#~(string-append #$field-name #$value)))
|
|
||||||
@end lisp
|
|
||||||
|
|
||||||
In some cases multiple different configuration records might be defined
|
In some cases multiple different configuration records might be defined
|
||||||
in the same file, but their serializers for the same type might have to
|
in the same file, but their serializers for the same type might have to
|
||||||
|
@ -42689,13 +42676,13 @@ manually specify a custom @var{serializer} for every field.
|
||||||
|
|
||||||
(define-configuration foo-configuration
|
(define-configuration foo-configuration
|
||||||
(label
|
(label
|
||||||
(string)
|
string
|
||||||
"The name of label.")
|
"The name of label.")
|
||||||
(prefix foo-))
|
(prefix foo-))
|
||||||
|
|
||||||
(define-configuration bar-configuration
|
(define-configuration bar-configuration
|
||||||
(ip-address
|
(ip-address
|
||||||
(string)
|
string
|
||||||
"The IPv4 address for this device.")
|
"The IPv4 address for this device.")
|
||||||
(prefix bar-))
|
(prefix bar-))
|
||||||
@end lisp
|
@end lisp
|
||||||
|
@ -42787,11 +42774,6 @@ Return a G-expression that contains the values corresponding to the
|
||||||
disk by using something like @code{mixed-text-file}.
|
disk by using something like @code{mixed-text-file}.
|
||||||
@end deffn
|
@end deffn
|
||||||
|
|
||||||
@deffn {Procedure} empty-serializer field-name value
|
|
||||||
A serializer that just returns an empty string. The
|
|
||||||
@code{serialize-package} procedure is an alias for this.
|
|
||||||
@end deffn
|
|
||||||
|
|
||||||
Once you have defined a configuration record, you will most likely also
|
Once you have defined a configuration record, you will most likely also
|
||||||
want to document it so that other people know to use it. To help with
|
want to document it so that other people know to use it. To help with
|
||||||
that, there are two procedures, both of which are documented below.
|
that, there are two procedures, both of which are documented below.
|
||||||
|
@ -42894,7 +42876,7 @@ Below is an example of a record type created using
|
||||||
|
|
||||||
(define-configuration contact-configuration
|
(define-configuration contact-configuration
|
||||||
(name
|
(name
|
||||||
(string)
|
string
|
||||||
"The name of the contact."
|
"The name of the contact."
|
||||||
serialize-contact-name)
|
serialize-contact-name)
|
||||||
(phone-number
|
(phone-number
|
||||||
|
@ -42904,15 +42886,15 @@ Below is an example of a record type created using
|
||||||
maybe-string
|
maybe-string
|
||||||
"The person's email address.")
|
"The person's email address.")
|
||||||
(married?
|
(married?
|
||||||
(boolean)
|
boolean
|
||||||
"Whether the person is married."))
|
"Whether the person is married."))
|
||||||
|
|
||||||
(define-configuration contacts-list-configuration
|
(define-configuration contacts-list-configuration
|
||||||
(name
|
(name
|
||||||
(string)
|
string
|
||||||
"The name of the owner of this contact list.")
|
"The name of the owner of this contact list.")
|
||||||
(email
|
(email
|
||||||
(string)
|
string
|
||||||
"The owner's email address.")
|
"The owner's email address.")
|
||||||
(contacts
|
(contacts
|
||||||
(list-of-contact-configurations '())
|
(list-of-contact-configurations '())
|
||||||
|
|
Loading…
Reference in New Issue