GNU bug report logs - #67787
[PATCH] doc: Add documentation for define-record-type*

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: guix-patches; Severity: minor; Reported by: Skyler Ferris <skyvine@HIDDEN>; Keywords: patch; merged with #67786; dated Mon, 11 Dec 2023 20:18:03 UTC; Maintainer for guix-patches is guix-patches@HIDDEN.
Merged 67786 67787. Request was from Mathieu Othacehe <mathieu@HIDDEN> to control <at> debbugs.gnu.org. Full text available.

Message received at 67787 <at> debbugs.gnu.org:


Received: (at 67787) by debbugs.gnu.org; 11 Dec 2023 20:19:55 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Dec 11 15:19:54 2023
Received: from localhost ([127.0.0.1]:54741 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1rCmks-0001CP-LF
	for submit <at> debbugs.gnu.org; Mon, 11 Dec 2023 15:19:54 -0500
Received: from mail-40133.protonmail.ch ([185.70.40.133]:13087)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <skyvine@HIDDEN>) id 1rCmkp-0001C9-VB
 for 67787 <at> debbugs.gnu.org; Mon, 11 Dec 2023 15:19:53 -0500
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=protonmail.com;
 s=protonmail3; t=1702325970; x=1702585170;
 bh=gU/LClMCfRrcCXxw8Wi8ZMXxnqzM/B/XeNT0DHQf+qE=;
 h=Date:To:From:Subject:Message-ID:In-Reply-To:References:
 Feedback-ID:From:To:Cc:Date:Subject:Reply-To:Feedback-ID:
 Message-ID:BIMI-Selector;
 b=WmbMZlRS+CfSWP1JeLbbKQbfsPPwMH2mwAlgMLLbWkGyAZGouQJzGB7DIEoDABrSY
 +Fb7JudXV6re0yxbKYxJHCS2xd+HHiEVV8wkQOgsc9CAq7KRfdWnKoxUSWi4SSCBJZ
 Fhadg7YBWY5NvuK95HWCiDaS0MAQ5ftPeJdyCn7itVRz9RP+lljA52oPgelZPh64EZ
 WAc8y1ahXeM6h06tnPrc0sa0PMXIT8olfb27aLQ/YtecGIUutkppv83PpuJTIHaj84
 +x84Gcxxlg5wN/wdjoiuwFt5iDslHPBygj03zGQroW6B/N6hSK74ZqO5DsIV7P9+i0
 1ItD4wzwRylig==
Date: Mon, 11 Dec 2023 20:19:24 +0000
To: 67787 <at> debbugs.gnu.org
From: Skyler Ferris <skyvine@HIDDEN>
Subject: Re: bug#67787: Acknowledgement ([PATCH] doc: Add documentation for
 define-record-type*)
Message-ID: <9a80dc3e-928f-46e6-914b-d483f82421be@HIDDEN>
In-Reply-To: <handler.67787.B.17023258404363.ack <at> debbugs.gnu.org>
References: <9bf2efa9c7aab1661fcf5180d1e536fc6dc0e9b3.1702324538.git.skyvine@HIDDEN>
 <handler.67787.B.17023258404363.ack <at> debbugs.gnu.org>
Feedback-ID: 40635331:user:proton
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-Spam-Score: -0.0 (/)
X-Debbugs-Envelope-To: 67787
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)

This is a duplicate of bug 67786. Apologies for the noise.

On 12/11/23 12:18, help-debbugs@HIDDEN wrote:
> Thank you for filing a new bug report with debbugs.gnu.org.
>
> This is an automatically generated reply to let you know your message
> has been received.
>
> Your message is being forwarded to the package maintainers and other
> interested parties for their attention; they will reply in due course.
>
> Your message has been sent to the package maintainer(s):
>   guix-patches@HIDDEN
>
> If you wish to submit further information on this problem, please
> send it to 67787 <at> debbugs.gnu.org.
>
> Please do not send mail to help-debbugs@HIDDEN unless you wish
> to report a problem with the Bug-tracking system.
>
> --
> 67787: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D67787
> GNU Bug Tracking System
> Contact help-debbugs@HIDDEN with problems





Information forwarded to guix-patches@HIDDEN:
bug#67787; Package guix-patches. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 11 Dec 2023 20:17:20 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Dec 11 15:17:20 2023
Received: from localhost ([127.0.0.1]:54733 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1rCmiN-00018I-LE
	for submit <at> debbugs.gnu.org; Mon, 11 Dec 2023 15:17:20 -0500
Received: from lists.gnu.org ([2001:470:142::17]:51864)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <skyvine@HIDDEN>) id 1rCmiL-00017l-Th
 for submit <at> debbugs.gnu.org; Mon, 11 Dec 2023 15:17:18 -0500
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 <skyvine@HIDDEN>)
 id 1rCmhu-0000IF-H6
 for guix-patches@HIDDEN; Mon, 11 Dec 2023 15:16:52 -0500
Received: from c-24-143-119-132.customer.broadstripe.net ([24.143.119.132]
 helo=localhost)
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <skyvine@HIDDEN>)
 id 1rCmhs-00009y-GX
 for guix-patches@HIDDEN; Mon, 11 Dec 2023 15:16:50 -0500
Received: from [127.0.0.1] (helo=localhost.localdomain)
 by localhost with esmtp (Exim 4.96.1)
 (envelope-from <skyvine@HIDDEN>) id 1rCmRC-0000Gn-2K;
 Mon, 11 Dec 2023 11:59:34 -0800
From: Skyler Ferris <skyvine@HIDDEN>
To: guix-patches@HIDDEN
Subject: [PATCH] doc: Add documentation for define-record-type*
Date: Mon, 11 Dec 2023 11:59:20 -0800
Message-ID: <9bf2efa9c7aab1661fcf5180d1e536fc6dc0e9b3.1702324538.git.skyvine@HIDDEN>
X-Mailer: git-send-email 2.41.0
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Received-SPF: softfail client-ip=24.143.119.132;
 envelope-from=skyvine@HIDDEN; helo=localhost
X-Spam_score_int: 72
X-Spam_score: 7.2
X-Spam_bar: +++++++
X-Spam_report: (7.2 / 5.0 requ) BAYES_00=-1.9, FREEMAIL_FROM=0.001,
 FSL_HELO_NON_FQDN_1=0.001, HELO_LOCALHOST=3.828, KHOP_HELO_FCRDNS=0.26,
 RCVD_IN_PBL=3.335, RDNS_DYNAMIC=0.982, SPF_SOFTFAIL=0.665,
 SPOOFED_FREEMAIL=0.001,
 T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no autolearn_force=no
X-Spam_action: reject
X-Spam-Score: 1.0 (+)
X-Debbugs-Envelope-To: submit
Cc: Skyler Ferris <skyvine@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.0 (/)

* doc/guix.texi: Add sections describing the typical usage and API
reference for define-record-type*

Change-Id: I19e7220553d10652c794e6e0172b2c9ee961f54f
---
 doc/contributing.texi |   1 -
 doc/guix.texi         | 274 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 274 insertions(+), 1 deletion(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 9e9b89782c..60fcf95b77 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1311,7 +1311,6 @@ Data Types and Pattern Matching
 notably the fact that it is hard to read, error-prone, and a hindrance
 to proper type error reports.
 
-@findex define-record-type*
 @findex match-record
 @cindex pattern matching
 Guix code should define appropriate data types (for instance, using
diff --git a/doc/guix.texi b/doc/guix.texi
index 1fd2e21608..e9d0fd1466 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -12561,6 +12561,280 @@ G-Expressions
 @code{(*approximate*)}, but this may change.
 @end deffn
 
+@node Records in Guix
+@section Records in Guix
+Guix uses @code{define-record-type*} to define structures with a lispy format.
+Packages, operating systems, etc are all defined with
+@code{define-record-type*} facilities. If one was using this facility to
+define preferences for a text editor, it might look like this:
+
+@lisp
+;; The only valid emulation modes are the symbol 'emacs, the symbol 'vim, or
+;; the boolean #f. As a convenience to the user, if they pass in a string
+;; first convert it to a symbol and accept it if it is valid.
+(define (sanitize-emulation-mode value)
+  (let ((symbolized-value (cond ((not value)     #f)
+                                ((string? value) (string->symbol value))
+                                (#t              value))))
+    (unless (or (not symbolized-value)
+                (eq? symbolized-value 'emacs)
+                (eq? symbolized-value 'vim))
+      (throw 'bad-emulation-made
+             (format #f "Unrecognized emulation mode: ~s" value)))
+    symbolized-value))
+
+(define-record-type*
+  <editor-preferences> editor-preferences make-editor-preferences
+  editor-preferences? this-editor-preferences
+  (background-color editor-preferences-background-color
+                    (default "000000"))
+  (text-color       editor-preferences-text-color
+                    (default "FFFFFF"))
+  (emulation-mode   editor-preferences-emulation-mode
+                    (default #f)
+                    (sanitize sanitize-emulation-mode)))
+@end lisp
+
+A user could then define their preferences like this:
+
+@lisp
+(define my-preferences
+  (editor-preferences
+    (background-color "222222")
+    (emulation-mode   'vim)))
+@end lisp
+
+The value contained in @code{my-preferences} contains a custom
+@code{background-color} and @code{emulation-mode}, but keeps the default
+@code{text-color} (@code{"FFFFFF"}). If an invalid @code{emulation-mode} had
+been specified, for example if the user passed in @code{"vi"} instead of
+@code{"vim"}, @code{sanitize-emulation-mode} would immediately throw an error.
+
+The program can access values like this:
+
+@lisp
+(editor-preferences-background-color my-preferences)
+@result{} "222222"
+(editor-preferences-text-color my-preferences)
+@result{} "FFFFFF"
+(editor-preferences-emulation-mode my-preferences)
+@result{} 'vim
+@end lisp
+
+There is no way to define setters (all instances are immutable).
+
+@node Record Inheritance
+@subsection Record Inheritance
+It is also possible to inherit from previously defined instances when creating
+new ones. Continuing with the editor example, someone might want to base their
+preferences on their friend's preferences but customize a value:
+
+@lisp
+(define friends-preferences
+  (editor-preferences
+    (inherit my-preferences)
+    (emulation-mode 'emacs)))
+@end lisp
+
+This keeps the same @code{background-color} and @code{text-color} that are
+contained in @code{my-preferences} but changes the @code{emulation-mode} to
+be @code{'emacs} instead of @code{'vim}.
+
+Sometimes it does not make sense for a field to be inherited. Suppose that the
+@code{<editor-preferences>} type is updated to contain a username so that a
+friendly greeting can be displayed when the program starts up:
+
+@lisp
+;; Usernames must be strings. It would be strange to pass a username as a
+;; symbol, so throw an error in case the user meant to pass in a variable's
+;; value instead of a literal symbol.
+(define (sanitize-username value)
+  (unless (string? value)
+    (throw 'bad-username
+           (format #f "Usernames must be strings! Got: ~s" value)))
+  value)
+
+(define (sanitize-emulation-mode value)
+  (let ((symbolized-value (cond ((not value)     #f)
+                                ((string? value) (string->symbol value))
+                                (#t              value))))
+    (unless (or (not symbolized-value)
+                (eq? symbolized-value 'emacs)
+                (eq? symbolized-value 'vim))
+      (throw 'bad-emulation-made
+             (format #f "Unrecognized emulation mode: ~s" value)))
+    symbolized-value))
+
+(define-record-type*
+  <editor-preferences> editor-preferences make-editor-preferences
+  editor-preferences? this-editor-preferences
+  (username         editor-preferences-username
+                    (innate)
+                    (sanitize sanitize-username))
+  (background-color editor-preferences-background-color
+                    (default "000000"))
+  (text-color       editor-preferences-text-color
+                    (default "FFFFFF"))
+  (emulation-mode   editor-preferences-emulation-mode
+                    (default #f)
+                    (sanitize sanitize-emulation-mode)))
+@end lisp
+
+There are a couple of differences in the new @code{username} field compared to
+the fields we looked at earlier. It is marked as @code{innate}, which means
+that it will not be inherited. For example, consider what would happen if we
+tried to define new instances like this:
+
+@lisp
+(define my-preferences
+  (editor-preferences
+    (username         "my-username")
+    (background-color "222222")
+    (emulation-mode   'vim)))
+
+(define friends-preferences
+  (editor-preferences
+    (inherit my-preferences)
+    (emulation-mode 'emacs)))
+@end lisp
+
+While the @code{friends-preferences} instance still inherits the values for
+@code{background-color} and @code{text-color}, it will not inherit the value
+for @code{username}. Furthermore, as the @code{username} field does not define
+a default value the attempted creation of @code{friends-preferences} will
+actually throw an error. Instead, we could do this:
+
+@lisp
+(define my-preferences
+  (editor-preferences
+    (username         "my-username")
+    (background-color "222222")
+    (emulation-mode   'vim)))
+
+(define friends-preferences
+  (editor-preferences
+    (inherit        my-preferences)
+    (username       "friends-username")
+    (emulation-mode 'emacs)))
+@end lisp
+
+@node @code{define-record-type*} Reference
+@subsection @code{define-record-type*} Reference
+@defmac define-record-type* name syntactic-constructor constructor predicate this-identifier fields ...
+
+Define a new record type and associated helpers.
+
+@table @var
+@item name
+A symbol used to name the type, as would normally be provided to a plain
+@code{define-record-type} form. For example, @code{<package>}.
+
+@item syntactic-constructor
+A symbol that will be used to define the user-facing constructor. For example,
+the symbol @code{package} is the syntactic constructor for the @code{<package>}
+structure.
+
+@item constructor
+A symbol that will be used to define the traditional constructor. It is used in
+the implementation of the syntactic constructor, but will not typically be used
+elsewhere. The traditional @code{make-name} (for example, @code{make-package})
+is a fine value to use here.
+
+@item predicate
+A symbol that will be used to test if a value is an instance of this record.
+For example, @code{package?}.
+
+@item this-identifier
+This symbol can be used when defining fields that need to refer to the struct
+that contains them. For an example of this, see the @code{thunked} field
+property, below.
+
+@item fields
+A set of field specifiers which take the following form:
+
+@lisp
+(field-name field-getter properties ...)
+@end lisp
+
+Each of the properties must have one of the following forms:
+
+@table @code
+@item (default @var{value})
+Defines the default value for the field, if the user does not specify one using
+the syntactic constructor.
+
+@item (innate)
+Fields marked as innate will not be inherited from parent objects (see
+Instantiating Records, below, for details of object inheritance).
+
+@item (sanitize @var{proc})
+The value given by the user will be passed into @var{proc} before being stored
+in the object. For example, consider this struct definition:
+
+@lisp
+(define-record-type* <thing> thing make-thing
+  thing?
+  this-thing
+  (name  thing-name
+         (sanitize (lambda (value)
+                     (cond ((string? value) value)
+                           ((symbol? value) (symbol->string value))
+                           (else (throw 'bad! value)))))))
+@end lisp
+
+When creating @code{thing} instances either a string or a symbol can be
+supplied but it will always be stored as a string:
+
+@lisp
+(string? (thing-name (thing (name "some-name"))))
+@result{} #t
+(string? (thing-name (thing (name 'some-name))))
+@result{} #t
+(thing (name 1994))
+@result{} Throw to key `bad!' with args `(1994)'.
+@end lisp
+
+@item (thunked)
+Fields marked as @code{thunked} will actually compute the field's value in the
+current dynamic extent which is useful when referring to fluids in a field's
+value. Furthermore, that thunk can access the record it belongs to via the
+@code{this-identifier}. For example:
+
+@lisp
+(define-record-type* <rectangle> rectangle make-rectangle
+  rectangle?
+  this-rectangle
+  (width  rectangle-width)
+  (height rectangle-height)
+  (area rectangle-area (thunked)
+                       (default (* (rectangle-width  this-rectangle)
+                                   (rectangle-height this-rectangle)))))
+
+(define base-rectangle
+  (rectangle
+    (width  2)
+    (height 4)))
+
+(define derived-rectangle
+  (rectangle
+    (inherit base)
+    (width   6)))
+
+(rectangle-area base-rectangle)
+@result{} 8
+
+(rectangle-area derived-rectangle
+@result{} 24
+@end lisp
+
+@item (delayed)
+Fields marked as @code{delayed} are similar to @code{thunked} fields, except
+that they are effectively wrapped in a @code{(delay @dots{})} form. Note that
+delayed fields cannot use @code{this-identifier}.
+@end table
+@end table
+@end defmac
+
 @node Invoking guix repl
 @section Invoking @command{guix repl}
 

base-commit: 2b782f67266b42bb40015bd23ce2443be2f9b01f
-- 
2.41.0





Acknowledgement sent to Skyler Ferris <skyvine@HIDDEN>:
New bug report received and forwarded. Copy sent to guix-patches@HIDDEN. Full text available.
Report forwarded to guix-patches@HIDDEN:
bug#67787; Package guix-patches. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Sat, 20 Jan 2024 12:30:02 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.