From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:403:478a::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id YLfEAK+AIWUupQAA9RJhRA:P1 (envelope-from ) for ; Sat, 07 Oct 2023 18:00:47 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:478a::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id YLfEAK+AIWUupQAA9RJhRA (envelope-from ) for ; Sat, 07 Oct 2023 18:00:47 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id A6C2A56231 for ; Sat, 7 Oct 2023 18:00:46 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1696694446; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding:resent-cc: resent-from:resent-sender:resent-message-id:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post; bh=2mdSnUvZnJgsBSelbOku0hfxjUWanZJIoIjPbsqPbAM=; b=DLi+XyLED9RwxfNmpQSefwNpGn1rj46qt6PmHeoxAAbMpiWE/OdlD3aghNLjC+tIf/7UyI bUFgkrAINL1LqfxN9wPJzRl+ro7zcqU4ArtiqmsJMFiVtuWBgxD7mnFDceKDMi1QjZODqV CbWfa0ch2ypXxOnKrAH1FCaMO5IezTpnwJ6dN4N108MoHTKIm38nT+jvD8cKnuJzOTJ9wm clUhrgPaEI8XC2A5Uzi3a5ZP2Y9kvEIya4fYmf71pzIIEqTBzCK1mIta+rA88PUNKgZEDP u6s3Aysb2BJqGJO5BMa3fG4t1XbCZusoy8eOe/tz9DtxBzZkP2P0J5i94VDM7A== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1696694446; a=rsa-sha256; cv=none; b=X2uS8u21nXEfv+qV+p/S4xH0tWLySeylBE7sx6vN8bIji/66osbLmMhH63iLcG2ugVOWFc ZDjqfaB2YMZiHQUmELFtpotati9leiKIEc+KpRYek7OQjCVjyRsqVikK8dLzE4ZRg7MpZv dXWM8Uy3UyMd51kRqmLB42PhY5XqJeGc8QDuBUJvV+zUz16ND1Oty4wCMA0ZYVq0JLXZPR 5s3ZVKI7IcMsPfQqo5a5ct0sWKdLJBYWwmp6KQmxSRf+hQIncas+sjS8HiSsYjHiDLClwo FWBoZfHKP327pMWly6DRoGrJ5fOFesZ7dNSkO9qUxHDxGufkfpC3ObZvMfFnqQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qp9iT-00089j-Fk; Sat, 07 Oct 2023 11:59:45 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qp9iR-00089C-KW for guix-patches@gnu.org; Sat, 07 Oct 2023 11:59:43 -0400 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qp9iR-00019B-Cc for guix-patches@gnu.org; Sat, 07 Oct 2023 11:59:43 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qp9ik-0002U7-R7 for guix-patches@gnu.org; Sat, 07 Oct 2023 12:00:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#63985] [PATCH v4 4/5] doc: Rewrite define-configuration. Resent-From: Bruno Victal Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Sat, 07 Oct 2023 16:00:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 63985 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 63985@debbugs.gnu.org Cc: Bruno Victal Received: via spool by 63985-submit@debbugs.gnu.org id=B63985.16966943889474 (code B ref 63985); Sat, 07 Oct 2023 16:00:02 +0000 Received: (at 63985) by debbugs.gnu.org; 7 Oct 2023 15:59:48 +0000 Received: from localhost ([127.0.0.1]:55734 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qp9iV-0002Sk-Oh for submit@debbugs.gnu.org; Sat, 07 Oct 2023 11:59:48 -0400 Received: from smtpm5.myservices.hosting ([185.26.105.236]:49366) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qp9iT-0002Sb-Kv for 63985@debbugs.gnu.org; Sat, 07 Oct 2023 11:59:46 -0400 Received: from mail1.netim.hosting (unknown [185.26.106.173]) by smtpm5.myservices.hosting (Postfix) with ESMTP id 59A3A20D9B for <63985@debbugs.gnu.org>; Sat, 7 Oct 2023 17:59:25 +0200 (CEST) Received: from localhost (localhost [127.0.0.1]) by mail1.netim.hosting (Postfix) with ESMTP id B55BE8009C; Sat, 7 Oct 2023 17:59:24 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at mail1.netim.hosting Received: from mail1.netim.hosting ([127.0.0.1]) by localhost (mail1-2.netim.hosting [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id vsSjk1n_E2Be; Sat, 7 Oct 2023 17:59:24 +0200 (CEST) Received: from guix-nuc.home.arpa (unknown [10.192.1.83]) (Authenticated sender: lumen@makinata.eu) by mail1.netim.hosting (Postfix) with ESMTPSA id 28D5380095; Sat, 7 Oct 2023 17:59:24 +0200 (CEST) From: Bruno Victal Date: Sat, 7 Oct 2023 16:59:08 +0100 Message-ID: X-Mailer: git-send-email 2.41.0 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: guix-patches-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Scanner: mx0.migadu.com X-Migadu-Spam-Score: -4.72 X-Spam-Score: -4.72 X-Migadu-Queue-Id: A6C2A56231 X-TUID: PyBQdJLvsgRL 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. --- doc/guix.texi | 102 +++++++++++++++++++++----------------------------- 1 file changed, 42 insertions(+), 60 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 52a573f0d8..e4a1523dfb 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -42576,54 +42576,33 @@ Complex Configurations files, you can use the utilities defined in the @code{(gnu services configuration)} module. -The main utility is the @code{define-configuration} macro, which you -will use to define a Scheme record type (@pxref{Record Overview,,, -guile, GNU Guile Reference Manual}). The Scheme record will be -serialized to a configuration file by using @dfn{serializers}, which are -procedures that take some kind of Scheme value and returns a -G-expression (@pxref{G-Expressions}), which should, once serialized to -the disk, return a string. More details are listed below. +The main utility is the @code{define-configuration} macro, a helper +used to define a Scheme record type (@pxref{Record Overview,,, +guile, GNU Guile Reference Manual}). The fields from this Scheme record +can be serialized using @dfn{serializers}, which are procedures that take +some kind of Scheme value and translates them into another Scheme value or +@ref{G-Expressions}. @defmac define-configuration name clause1 clause2 @dots{} Create a record type named @code{@var{name}} that contains the fields found in the clauses. -A clause can have one of the following forms: +A clause has the following form: @example (@var{field-name} - (@var{type} @var{default-value}) - @var{documentation}) - -(@var{field-name} - (@var{type} @var{default-value}) - @var{documentation} - (serializer @var{serializer})) - -(@var{field-name} - (@var{type}) - @var{documentation}) - -(@var{field-name} - (@var{type}) - @var{documentation} - (serializer @var{serializer})) - -(@var{field-name} - (@var{type}) + @var{type-decl} @var{documentation} - (sanitizer @var{sanitizer}) - -(@var{field-name} - (@var{type}) - @var{documentation} - (sanitizer @var{sanitizer}) - (serializer @var{serializer})) + @var{option*} + @dots{}) @end example @var{field-name} is an identifier that denotes the name of the field in 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}; since Guile is untyped, a predicate procedure---@code{@var{type}?}---will be called on the value @@ -42641,6 +42620,28 @@ Complex Configurations @var{documentation} is a string formatted with Texinfo syntax which 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, a user-supplied value, and returns a ``sanitized'' value for the field. If no sanitizer is specified, a default sanitizer is used, which raises @@ -42654,21 +42655,7 @@ Complex Configurations ((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 -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 +@end table In some cases multiple different configuration records might be defined in the same file, but their serializers for the same type might have to @@ -42689,13 +42676,13 @@ Complex Configurations (define-configuration foo-configuration (label - (string) + string "The name of label.") (prefix foo-)) (define-configuration bar-configuration (ip-address - (string) + string "The IPv4 address for this device.") (prefix bar-)) @end lisp @@ -42787,11 +42774,6 @@ Complex Configurations disk by using something like @code{mixed-text-file}. @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 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. @@ -42894,7 +42876,7 @@ Complex Configurations (define-configuration contact-configuration (name - (string) + string "The name of the contact." serialize-contact-name) (phone-number @@ -42904,15 +42886,15 @@ Complex Configurations maybe-string "The person's email address.") (married? - (boolean) + boolean "Whether the person is married.")) (define-configuration contacts-list-configuration (name - (string) + string "The name of the owner of this contact list.") (email - (string) + string "The owner's email address.") (contacts (list-of-contact-configurations '()) -- 2.41.0