From c7d688df2210fa710b66b7f705cadc62a9e61c9a Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Tue, 26 Nov 2013 23:40:40 -0500 Subject: [PATCH] Add more examples for `struct` in Reference Please merge to v6.0 --- .../scribblings/reference/define-struct.scrbl | 72 +++++++++++++++++-- 1 file changed, 68 insertions(+), 4 deletions(-) diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/reference/define-struct.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/reference/define-struct.scrbl index 985b117ce3..36d8e4e849 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/reference/define-struct.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/reference/define-struct.scrbl @@ -3,7 +3,8 @@ racket/generic)) @(define posn-eval (make-base-eval)) -@(interaction-eval #:eval posn-eval (require (for-syntax racket/base))) +@(interaction-eval #:eval posn-eval + (require racket/match racket/stream (for-syntax racket/base))) @title[#:tag "define-struct"]{Defining Structure Types: @racket[struct]} @@ -102,6 +103,12 @@ must produce a @tech{structure type descriptor}. See and supertypes. If both @racket[super-id] and @racket[#:super] are provided, a syntax error is reported. +@examples[#:eval posn-eval + (struct document (author title content)) + (struct book document (publisher)) + (struct paper (journal) #:super struct:document) +] + If the @racket[#:mutable] option is specified for an individual field, then the field can be mutated in instances of the structure type, and a @tech{mutator} procedure is bound. Supplying @@ -110,6 +117,12 @@ supplying it for all @racket[field]s. If @racket[#:mutable] is specified as both a @racket[field-option] and @racket[struct-option], a syntax error is reported. +@examples[#:eval posn-eval + (struct cell ([content #:mutable]) #:transparent) + (define a-cell (cell 0)) + (set-cell-content! a-cell 1) +] + The @racket[#:inspector], @racket[#:auto-value], and @racket[#:guard] options specify an inspector, value for automatic fields, and guard procedure, respectively. See @racket[make-struct-type] for more @@ -120,6 +133,17 @@ multiple times, attaches a property value to the structure type; see @racket[#:transparent] option is a shorthand for @racket[#:inspector #f]. +@examples[#:eval posn-eval + (struct point (x y) #:inspector #f) + (point 3 5) + (struct celcius (temp) + #:guard (λ (temp name) + (unless (and (real? temp) (>= temp -273.15)) + (error "not a valid temperature")) + temp)) + (celcius -275) +] + @margin-note{Use the @racket[prop:procedure] property to implement an @as-index{applicable structure}, use @racket[prop:evt] to create a structure type whose instances are @tech{synchronizable events}, and @@ -133,6 +157,12 @@ cannot have a guard or properties, so using @racket[#:prefab] with @racket[#:property] is a syntax error. If a supertype is specified, it must also be a @tech{prefab} structure type. +@examples[#:eval posn-eval + (struct prefab-point (x y) #:prefab) + (prefab-point 1 2) + (prefab-point? #s(prefab-point 1 2)) +] + If @racket[constructor-id] is supplied, then the @tech{transformer binding} of @racket[id] records @racket[constructor-id] as the constructor binding; as a result, for example, @racket[struct-out] @@ -148,6 +178,13 @@ the symbolic form of @racket[constructor-id]. Only one of @racket[#:extra-constructor-name] and @racket[#:constructor-name] can be provided within a @racket[struct] form. +@examples[#:eval posn-eval + (struct color (r g b) #:constructor-name -color) + (struct rectangle (w h color) #:extra-constructor-name rect) + (rectangle 13 50 (-color 192 157 235)) + (rect 50 37 (-color 35 183 252)) +] + If @racket[#:reflection-name symbol-expr] is provided, then @racket[symbol-expr] must produce a symbol that is used to identify the structure type in reflective operations such as @@ -155,6 +192,12 @@ the structure type in reflective operations such as @racket[make-struct-type]. Structure printing uses the reflective name, as do the various procedures that are bound by @racket[struct]. +@examples[#:eval posn-eval + (struct circle (radius) #:reflection-name ') + (circle 15) + (circle-radius "bad") +] + If @racket[#:methods gen:name method-defs] is provided, then @racket[gen:name] must be a transformer binding for the static information about a generic interface produced by @racket[define-generics]. @@ -162,6 +205,17 @@ The @racket[method-defs] define the methods of the @racket[gen:name] interface. A @racket[define/generic] form or auxiliary definitions and expressions may also appear in @racket[method-defs]. +@examples[#:eval posn-eval + (struct constant-stream (val) + #:methods gen:stream + [(define (stream-empty? stream) #f) + (define (stream-first stream) + (constant-stream-val stream)) + (define (stream-rest stream) stream)]) + (stream-ref (constant-stream 'forever) 0) + (stream-ref (constant-stream 'forever) 50) +] + If the @racket[#:omit-define-syntaxes] option is supplied, then @racket[id] is not bound as a transformer. If the @racket[#:omit-define-values] option is supplied, then none of the @@ -169,6 +223,15 @@ usual variables are bound, but @racket[id] is bound. If both are supplied, then the @racket[struct] form is equivalent to @racket[(begin)]. +@examples[#:eval posn-eval + (struct square (side) #:omit-define-syntaxes) + (match (square 5) + (code:comment "fails to match because syntax is omitted") + [(struct square x) x]) + (struct ellipse (width height) #:omit-define-values) + ellipse-width +] + If @racket[#:auto] is supplied as a @racket[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 @@ -184,8 +247,6 @@ error is reported. If any @racket[field-option] or @racket[struct-option] keyword is repeated, other than @racket[#:property], a syntax error is reported. -For serialization, see @racket[define-serializable-struct]. - @defexamples[ #:eval posn-eval (struct posn (x y [z #:auto]) @@ -203,7 +264,10 @@ For serialization, see @racket[define-serializable-struct]. (color-posn-hue cp) cp (set-posn-z! cp 3) -]} +] + +For serialization, see @racket[define-serializable-struct]. +} @defform[(struct-field-index field-id)]{