aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2014-10-14 14:44:48 +0200
committerLudovic Courtès <ludo@gnu.org>2014-10-17 23:23:20 +0200
commite25408849ad70026e1673ea0adc9bd4df8ff32fc (patch)
tree1f76f7f9313d8caab7f618052b65d027dca80caf
parentbd53d327e123ee51eaaae214fe3992dac9d35678 (diff)
downloadguix-e25408849ad70026e1673ea0adc9bd4df8ff32fc.tar
guix-e25408849ad70026e1673ea0adc9bd4df8ff32fc.tar.gz
records: Improve the docstring of 'define-record-type*'.
* guix/records.scm (define-record-type*): Agument the docstring, give examples.
-rw-r--r--guix/records.scm33
1 files changed, 32 insertions, 1 deletions
diff --git a/guix/records.scm b/guix/records.scm
index cd887b77ce..93c52f0ffa 100644
--- a/guix/records.scm
+++ b/guix/records.scm
@@ -46,7 +46,38 @@
(lambda (s)
"Define the given record type such that an additional \"syntactic
constructor\" is defined, which allows instances to be constructed with named
-field initializers, à la SRFI-35, as well as default values."
+field initializers, à la SRFI-35, as well as default values. An example use
+may look like this:
+
+ (define-record-type* <thing> thing make-thing
+ thing?
+ (name thing-name (default \"chbouib\"))
+ (port thing-port
+ (default (current-output-port)) (thunked)))
+
+This example defines a macro 'thing' that can be used to instantiate records
+of this type:
+
+ (thing
+ (name \"foo\")
+ (port (current-error-port)))
+
+The value of 'name' or 'port' could as well be omitted, in which case the
+default value specified in the 'define-record-type*' form is used:
+
+ (thing)
+
+The 'port' field is \"thunked\", meaning that calls like '(thing-port x)' will
+actually compute the field's value in the current dynamic extent, which is
+useful when referring to fluids in a field's value.
+
+It is possible to copy an object 'x' created with 'thing' like this:
+
+ (thing (inherit x) (name \"bar\"))
+
+This expression returns a new object equal to 'x' except for its 'name'
+field."
+
(define (make-syntactic-constructor type name ctor fields thunked defaults)
"Make the syntactic constructor NAME for TYPE, that calls CTOR, and
expects all of FIELDS to be initialized. DEFAULTS is the list of