From af5721a887c4062624212631cb67de5af55aa5bb Mon Sep 17 00:00:00 2001 From: Ryan Culpepper Date: Wed, 20 Mar 2013 10:52:16 -0400 Subject: [PATCH] added optional #:grammar clause to defform, etc original commit: 293b208af72c53b5bb2b625650b19a52d1cf256d --- collects/scribble/private/manual-form.rkt | 68 +++++++---- collects/scribblings/scribble/manual.scrbl | 132 +++++++++++---------- 2 files changed, 113 insertions(+), 87 deletions(-) diff --git a/collects/scribble/private/manual-form.rkt b/collects/scribble/private/manual-form.rkt index 18717a24..f07a63ac 100644 --- a/collects/scribble/private/manual-form.rkt +++ b/collects/scribble/private/manual-form.rkt @@ -29,9 +29,10 @@ (begin-for-syntax (define-splicing-syntax-class kind-kw #:description "#:kind keyword" - (pattern (~optional (~seq #:kind kind) - #:defaults ([kind #'#f])))) - + (pattern (~seq #:kind kind)) + (pattern (~seq) + #:with kind #'#f)) + (define-splicing-syntax-class id-kw #:description "#:id keyword" (pattern (~seq #:id [defined-id:id defined-id-expr])) @@ -43,20 +44,28 @@ (pattern (~seq) #:with defined-id #'#f #:with defined-id-expr #'#f)) - + (define-splicing-syntax-class literals-kw #:description "#:literals keyword" - (pattern (~optional (~seq #:literals (lit:id ...)) - #:defaults ([(lit 1) '()])))) + (pattern (~seq #:literals (lit:id ...))) + (pattern (~seq) + #:with (lit ...) #'())) (define-splicing-syntax-class contracts-kw #:description "#:contracts keyword" - (pattern (~optional (~seq #:contracts ([contract-nonterm:id contract-expr] ...)) - #:defaults ([(contract-nonterm 1) '()] - [(contract-expr 1) '()])))) + (pattern (~seq #:contracts (~and cs ([contract-nonterm:id contract-expr] ...)))) + (pattern (~seq) + #:with (~and cs ((contract-nonterm contract-expr) ...)) #'())) (define-syntax-class grammar - (pattern ([non-term-id:id non-term-form ...] ...))) + #:description "grammar" + (pattern ([non-term-id:id non-term-form ...+] ...))) + + (define-splicing-syntax-class subs-kw + #:description "#:grammar keyword" + #:attributes (g (g.non-term-id 1) (g.non-term-form 2)) + (pattern (~seq #:grammar g:grammar)) + (pattern (~seq) #:with g:grammar #'())) ) (define-syntax (defform*/subs stx) @@ -104,21 +113,23 @@ (define-syntax (defform* stx) (syntax-parse stx - [(_ k:kind-kw d:id-kw l:literals-kw [spec ...] desc ...) + [(_ k:kind-kw d:id-kw l:literals-kw [spec ...] + subs:subs-kw c:contracts-kw desc ...) (syntax/loc stx (defform*/subs #:kind k.kind #:id [d.defined-id d.defined-id-expr] #:literals (l.lit ...) - [spec ...] () desc ...))])) + [spec ...] subs.g #:contracts c.cs desc ...))])) (define-syntax (defform stx) (syntax-parse stx - [(_ k:kind-kw d:id-kw l:literals-kw spec desc ...) + [(_ k:kind-kw d:id-kw l:literals-kw spec + subs:subs-kw c:contracts-kw desc ...) (syntax/loc stx (defform*/subs #:kind k.kind #:id [d.defined-id d.defined-id-expr] #:literals (l.lit ...) - [spec] () desc ...))])) + [spec] subs.g #:contracts c.cs desc ...))])) (define-syntax (defform/subs stx) (syntax-parse stx @@ -131,14 +142,20 @@ (define-syntax (defform/none stx) (syntax-parse stx - [(_ k:kind-kw l:literals-kw spec c:contracts-kw desc ...) + [(_ k:kind-kw l:literals-kw spec subs:subs-kw c:contracts-kw desc ...) (syntax/loc stx (with-togetherable-racket-variables (l.lit ...) - ([form/none spec]) + ([form/none spec] + [non-term (subs.g.non-term-id subs.g.non-term-form ...)] ...) (*defforms k.kind #f - '(spec) (list (lambda (ignored) (racketblock0/form spec))) - null null + '(spec) + (list (lambda (ignored) (racketblock0/form spec))) + '((subs.g.non-term-id subs.g.non-term-form ...) ...) + (list (list (lambda () (racket subs.g.non-term-id)) + (lambda () (racketblock0/form subs.g.non-term-form)) + ...) + ...) (list (list (lambda () (racket c.contract-nonterm)) (lambda () (racketblock0 c.contract-expr))) ...) @@ -203,9 +220,9 @@ (define-syntax (specsubform stx) (syntax-parse stx - [(_ l:literals-kw spec desc ...) + [(_ l:literals-kw spec subs:subs-kw c:contracts-kw desc ...) (syntax/loc stx - (spec?form/subs #f #:literals (l.lit ...) spec () desc ...))])) + (spec?form/subs #f #:literals (l.lit ...) spec subs.g #:contracts c.cs desc ...))])) (define-syntax (specsubform/subs stx) (syntax-parse stx @@ -221,12 +238,11 @@ (define-syntax-rule (specspecsubform/subs spec subs desc ...) (make-blockquote "leftindent" (list (specsubform/subs spec subs desc ...)))) -(define-syntax specform - (syntax-rules () - [(_ #:literals (lit ...) spec desc ...) - (spec?form/subs #t #:literals (lit ...) spec () desc ...)] - [(_ spec desc ...) - (specform #:literals () spec desc ...)])) +(define-syntax (specform stx) + (syntax-parse stx + [(_ l:literals-kw spec subs:subs-kw c:contracts-kw desc ...) + (syntax/loc stx + (spec?form/subs #t #:literals (l.lit ...) spec subs.g #:contracts c.cs desc ...))])) (define-syntax (specform/subs stx) (syntax-parse stx diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index c0c596d4..38a4de96 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -812,7 +812,7 @@ Examples: @defform/subs[(defform maybe-kind maybe-id maybe-literals form-datum - maybe-contracts + maybe-grammar maybe-contracts pre-flow ...) ([maybe-kind code:blank (code:line #:kind kind-string-expr)] @@ -821,6 +821,8 @@ Examples: (code:line #:id [id id-expr])] [maybe-literals code:blank (code:line #:literals (literal-id ...))] + [maybe-grammar code:blank + (code:line #:grammar ([nonterm-id clause-datum ...+] ...))] [maybe-contracts code:blank (code:line #:contracts ([subform-datum contract-expr-datum] ...))])]{ @@ -856,19 +858,24 @@ non-terminal. If @racket[#:literals] clause is provided, however, instances of the @racket[literal-id]s are typeset normally (i.e., as determined by the enclosing context). +If a @racket[#:grammar] clause is provided, it includes an auxiliary +grammar of non-terminals shown with the @racket[id] form. Each +@racket[nonterm-id] is specified as being any of the corresponding +@racket[clause-datum]s. + If a @racket[#:contracts] clause is provided, each @racket[subform-datum] (typically an identifier that serves as a -meta-variable in @racket[form-datum]) is shown as producing a value -that must satisfy the contract described by +meta-variable in @racket[form-datum] or @racket[clause-datum]) is +shown as producing a value that must satisfy the contract described by @racket[contract-expr-datum]. Use @racket[#:contracts] only to -specify constraints on a @emph{value} produced by an expression; -for constraints on the @emph{syntax} of a @racket[subform-datum], -use grammar notation instead, possibly through an -auxiliary grammar specified using @racket[defform/subs]. +specify constraints on a @emph{value} produced by an expression; for +constraints on the @emph{syntax} of a @racket[subform-datum], use +grammar notation instead, possibly through an auxiliary grammar +specified with @racket[#:grammar]. -The typesetting of @racket[form-datum], @racket[subform-datum], and -@racket[contract-expr-datum] preserves the source layout, like -@racket[racketblock]. +The typesetting of @racket[form-datum], @racket[clause-datum], +@racket[subform-datum], and @racket[contract-expr-datum] preserves the +source layout, like @racket[racketblock]. Examples: @codeblock[#:keep-lang-line? #f]|{ @@ -889,11 +896,22 @@ Examples: the @racket[ingredient-expr]s will be mixed into the resulting sandwich. } + +@defform[(sandwich-factory maybe-name factory-component ...) + #:grammar + [(maybe-name (code:line) + name) + (factory-component (code:line #:protein protein-expr) + [vegetable vegetable-expr])]]{ + Constructs a sandwich factory. If @racket[maybe-name] is provided, + the factory will be named. Each of the @racket[factory-component] + clauses adds an additional ingredient to the sandwich pipeline. +} }| } @defform[(defform* maybe-kind maybe-id maybe-literals [form-datum ...+] - maybe-contracts + maybe-grammar maybe-contracts pre-flow ...)]{ Like @racket[defform], but for multiple forms using the same @@ -911,42 +929,9 @@ Examples: }| } -@defform[(defform/subs maybe-kind maybe-id maybe-literals form-datum - ([nonterm-id clause-datum ...+] ...) - maybe-contracts - pre-flow ...)]{ -Like @racket[defform], but including an auxiliary grammar of -non-terminals shown with the @racket[_id] form. Each -@racket[nonterm-id] is specified as being any of the corresponding -@racket[clause-datum]s, where the formatting of each -@racket[clause-datum] is preserved. - -Examples: -@codeblock[#:keep-lang-line? #f]|{ -#lang scribble/manual -@defform/subs[(sandwich-factory maybe-name factory-component ...) - [(maybe-name (code:line) - name) - (factory-component (code:line #:protein protein-expr) - [vegetable vegetable-expr])]]{ - Constructs a sandwich factory. If @racket[maybe-name] is provided, - the factory will be named. Each of the @racket[factory-component] - clauses adds an additional ingredient to the sandwich pipeline. -} -}| -} - - -@defform[(defform*/subs maybe-kind maybe-id maybe-literals [form-datum ...+] - ([nonterm-id clause-datum ...+] ...) - maybe-contracts - pre-flow ...)]{ - -Like @racket[defform/subs], but for multiple forms for @racket[_id].} - - -@defform[(defform/none maybe-kind maybe-literal form-datum maybe-contracts +@defform[(defform/none maybe-kind maybe-literal form-datum + maybe-grammar maybe-contracts pre-flow ...)]{ Like @racket[defform], but without registering a definition.} @@ -966,7 +951,7 @@ inline element. Use this form sparingly, because the typeset form does not stand out to the reader as a specification of @racket[id].} -@defform[(specform maybe-literals datum maybe-contracts +@defform[(specform maybe-literals datum maybe-grammar maybe-contracts pre-flow ...)]{ Like @racket[defform], but without indexing or registering a @@ -974,7 +959,7 @@ definition, and with indenting on the left for both the specification and the @racket[pre-flow]s.} -@defform[(specsubform maybe-literals datum maybe-contracts +@defform[(specsubform maybe-literals datum maybe-grammar maybe-contracts pre-flow ...)]{ Similar to @racket[defform], but without any specific identifier being @@ -989,16 +974,7 @@ procedure. In this description, a reference to any identifier in @racket[datum] is typeset as a sub-form non-terminal.} -@defform[(specsubform/subs maybe-literals datum - ([nonterm-id clause-datum ...+] ...) - maybe-contracts - pre-flow ...)]{ - -Like @racket[specsubform], but with a grammar like -@racket[defform/subs].} - - -@defform[(specspecsubform maybe-literals datum maybe-contracts +@defform[(specspecsubform maybe-literals datum maybe-grammar maybe-contracts pre-flow ...)]{ Like @racket[specsubform], but indented an extra level. Since using @@ -1007,13 +983,47 @@ nests indentation, @racket[specspecsubform] is for extra indentation without nesting a description.} +@deftogether[[ +@defform[(defform/subs maybe-kind maybe-id maybe-literals form-datum + ([nonterm-id clause-datum ...+] ...) + maybe-contracts + pre-flow ...)] +@defform[(defform*/subs maybe-kind maybe-id maybe-literals [form-datum ...+] + ([nonterm-id clause-datum ...+] ...) + maybe-contracts + pre-flow ...)] +@defform[(specform/subs maybe-literals datum + ([nonterm-id clause-datum ...+] ...) + maybe-contracts + pre-flow ...)] +@defform[(specsubform/subs maybe-literals datum + ([nonterm-id clause-datum ...+] ...) + maybe-contracts + pre-flow ...)] @defform[(specspecsubform/subs maybe-literals datum ([nonterm-id clause-datum ...+] ...) maybe-contracts - pre-flow ...)]{ + pre-flow ...)]]]{ -Like @racket[specspecsubform], but with a grammar like -@racket[defform/subs].} +Like @racket[defform], @racket[defform*], @racket[specform], +@racket[specsubform], and @racket[specspecsubform], respectively, but +the auxiliary grammar is mandatory and the @racket[#:grammar] keyword +is omitted. + +Examples: +@codeblock[#:keep-lang-line? #f]|{ +#lang scribble/manual +@defform/subs[(sandwich-factory maybe-name factory-component ...) + [(maybe-name (code:line) + name) + (factory-component (code:line #:protein protein-expr) + [vegetable vegetable-expr])]]{ + Constructs a sandwich factory. If @racket[maybe-name] is provided, + the factory will be named. Each of the @racket[factory-component] + clauses adds an additional ingredient to the sandwich pipeline. +} +}| +} @defform[(defparam id arg-id contract-expr-datum pre-flow ...)]{