From e0ce4d1d20205ba93897acdbb8170f6676e945c3 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Fri, 22 Jun 2007 06:49:22 +0000 Subject: [PATCH] document new define-struct svn: r6715 --- collects/scribble/eval.ss | 2 +- collects/scribblings/new-struct.ss | 1 + .../scribblings/reference/define-struct.scrbl | 142 ++++++++++++++++++ collects/scribblings/reference/derived.scrbl | 3 + 4 files changed, 147 insertions(+), 1 deletion(-) create mode 100644 collects/scribblings/reference/define-struct.scrbl diff --git a/collects/scribble/eval.ss b/collects/scribble/eval.ss index e4a660aaa9..01a05770ce 100644 --- a/collects/scribble/eval.ss +++ b/collects/scribble/eval.ss @@ -1,5 +1,5 @@ -(module eval mzscheme +(module eval (lib "new-lambda.ss" "scribblings") (require "manual.ss" "struct.ss" "scheme.ss" diff --git a/collects/scribblings/new-struct.ss b/collects/scribblings/new-struct.ss index 7ef679961d..0f8dac8b77 100644 --- a/collects/scribblings/new-struct.ss +++ b/collects/scribblings/new-struct.ss @@ -110,6 +110,7 @@ (when immutable? (bad "redundant" (car ps) " for field")) (loop (cdr ps) def-val auto? #t)] + #; [(eq? #:default (syntax-e (car ps))) (check-exprs 1 ps) (when def-val diff --git a/collects/scribblings/reference/define-struct.scrbl b/collects/scribblings/reference/define-struct.scrbl new file mode 100644 index 0000000000..39465f1c7a --- /dev/null +++ b/collects/scribblings/reference/define-struct.scrbl @@ -0,0 +1,142 @@ +#reader(lib "docreader.ss" "scribble") +@require["mz.ss"] + +@title{Structure Types: @scheme[define-struct]} + +@defform/subs[(define-struct id-maybe-super (field ...) + struct-option ...) + ([id-maybe-super id + (id super-id)] + [field field-id + [field-id field-option ...]] + [struct-option #:immutable + (code:line #:super super-expr) + (code:line #:inspector inspector-expr) + (code:line #:auto-value auto-expr) + (code:line #:guard guard-expr) + (code:line #:property prop-expr val-exr) + #:omit-define-syntaxes + #:omit-define-values] + [field-option #:immutable + #:auto])]{ + +Creates a new structure type, and binds transformers and +variables related to the new structure type. A +@scheme[define-struct] form with @math{n} @scheme[field]s defines +up to @math{4+2n} names: + +@itemize{ + + @item{@schemeidfont{struct:}@scheme[id], a @tech{structure type descriptor} + value that represents the new datatype.} + + @item{@schemeidfont{make-}@scheme[id], a @deftech{constructor} + procedure that takes @math{m} arguments and returns a new + instance of the structure type, where @math{m} is the number of + @scheme[field]s that do not include an @scheme[#:auto] option.} + + @item{@scheme[id]@schemeidfont{?}, a @deftech{predicate} procedure + that returns @scheme[#t] for instances of the structure type + (constructed by @schemeidfont{make-}@scheme[id] or the + @tech{constructor} for a subtype) and @scheme[#f] for any other + value.} + + @item{@scheme[id]@schemeidfont{-}@scheme[field-id], for each + @scheme[field]; an @deftech{accessor} procedure that takes an + instance of the structure type and extracts the value for the + corresponding field.} + + @item{@schemeidfont{set-}@scheme[id]@schemeidfont{-}@scheme[field-id]@schemeidfont{!}, + for each @scheme[field] that does not include a + @scheme[#:immutable] option, and only when the + @scheme[#:immutable] option is not specified as a + @scheme[struct-option]; a @deftech{mutator} procedure that + takes an instance of the structure type and a new field + value. The structure is destructively updated with the new + value, and @|void-const| is returned.} + + @item{@scheme[id], a transformer binding that encapsulates + information about the structure type declaration. This binding + is used to define subtypes, and it also works with the + @scheme[shared] and @scheme[match] forms. For detailed + information about the binding of @scheme[id], see + @secref["mz:structinfo"].} + +} + +If @scheme[super-id] is provided, it must have a transformer binding +of the same sort bound to @scheme[id] (see @secref["mz:structinfo"]), +and it specifies a supertype for the new structure type. Alternately, +the @scheme[#:super] option can be used to specify an expression that +must produce a @tech{structure type descriptor}. See +@scheme[make-struct-type] for more information on structure subtypes +and supertypes. If both @scheme[super-id] and @scheme[#:super] are +provided, a syntax error is reported. + +If the @scheme[#:immutable] option is specified for an individual +field, then the field cannot be mutated in instances of the structure +type, and no @tech{mutator} procedure is bound. Supplying +@scheme[#:immutable] as a @scheme[struct-option] is the same as +supplying it for all @scheme[field]s. If @scheme[#:immutable] is +specified as both a @scheme[field-option] and @scheme[struct-option], +a syntax error is reported. + +The @scheme[#:inspector], @scheme[#:auto-value], and @scheme[#:guard] +options specify an inspector, value for automatic fields, and guard +procedure, respectively. See @scheme[make-struct-type] for more +information on these properties of a structure type. The +@scheme[#:property] option, which is the only one that can be +specified multiple times, attaches a property value to the structure +type; see @scheme[make-struct-type] for more information on +properties. + +If the @scheme[#:omit-define-syntaxes] option is supplied, then +@scheme[id] is not bound as a transformer. If the +@scheme[#:omit-define-values] option is supplied, then none of the +usual variables are bound. If both are supplied, then the +@scheme[define-struct] form is equivalent to @scheme[(begin)]. + +If @scheme[#:auto] is supplied as a @scheme[field-option], then the +@tech{constructor} procedure for the structure type does not accept an +argument corresponding to the field. Instead, the structure type's +automatic value is used for the field, as specified by the +@scheme[#:auto-value] option, or as defaults to @scheme[#f] when +@scheme[#:auto-value] is not supplied. + +If a @scheme[field] includes the @scheme[#:auto] option, then all +fields after it must also include @scheme[#:auto], otherwise a syntax +error is reported. If any @scheme[field-option] or +@scheme[struct-option] keyword is repeated, other than +@scheme[#:property], a syntax error is reported. + +@defexamples[ +(define-struct posn (x y [z #:auto]) + #:auto-value 0 + #:inspector #f) +(make-posn 1 2) +(posn? (make-posn 1 2)) +(posn-y (make-posn 1 2)) +] + +@defs+int[ +[(define-struct (color-posn posn) (hue)) + (define cp (make-color-posn 1 2 "blue"))] +(color-posn-hue cp) +cp +(set-posn-z! cp 3) +]} + +@defform[(struct-field-index field-id)]{ + +This form can only appear as an expression within a +@scheme[define-struct] form; normally, it is used with +@scheme[#:property], especially for a property like +@scheme[prop:procedure]. The result of + +@defexamples[ +(define-struct mood-procedure ([base #:immutable] rating) + #:property prop:procedure (struct-field-index base)) +(define happy+ (make-mood-procedure add1 10)) +(happy+ 2) +(mood-procedure-rating happy+) +]} diff --git a/collects/scribblings/reference/derived.scrbl b/collects/scribblings/reference/derived.scrbl index 058b1a241d..9ec95f486d 100644 --- a/collects/scribblings/reference/derived.scrbl +++ b/collects/scribblings/reference/derived.scrbl @@ -143,5 +143,8 @@ Equivalent to @scheme[(when (not test-expr) expr ...)]. (display " there")) ]} +@;------------------------------------------------------------------------ +@include-section["define-struct.scrbl"] + @;------------------------------------------------------------------------ @include-section["for.scrbl"]