0840430b21
by removing a redundant expression in an error message, adding tests, and documenting the fact that a syntax-error message can expose the pattern source to users
503 lines
18 KiB
Racket
503 lines
18 KiB
Racket
#lang scribble/doc
|
|
@(require "mz.ss")
|
|
|
|
@(define lit-ellipsis (scheme ...))
|
|
|
|
@(define syntax-eval
|
|
(lambda ()
|
|
(let ([the-eval (make-base-eval)])
|
|
(the-eval '(require (for-syntax racket/base)))
|
|
the-eval)))
|
|
|
|
@title[#:tag "stx-patterns"]{Pattern-Based Syntax Matching}
|
|
|
|
@defform/subs[(syntax-case stx-expr (literal-id ...)
|
|
clause ...)
|
|
([clause [pattern result-expr]
|
|
[pattern fender-expr result-expr]]
|
|
[pattern _
|
|
id
|
|
(pattern ...)
|
|
(pattern ...+ . pattern)
|
|
(pattern ... pattern ellipsis pattern ...)
|
|
(pattern ... pattern ellipsis pattern ... . pattern)
|
|
(code:line #,(tt "#")(pattern ...))
|
|
(code:line #,(tt "#")(pattern ... pattern ellipsis pattern ...))
|
|
(code:line #,(tt "#s")(key-datum pattern ...))
|
|
(code:line #,(tt "#s")(key-datum pattern ... pattern ellipsis pattern ...))
|
|
(ellipsis stat-pattern)
|
|
const]
|
|
[stat-pattern id
|
|
(stat-pattern ...)
|
|
(stat-pattern ...+ . stat-pattern)
|
|
(code:line #,(tt "#")(stat-pattern ...))
|
|
const]
|
|
[ellipsis #,lit-ellipsis])]{
|
|
|
|
Finds the first @scheme[pattern] that matches the syntax object
|
|
produced by @scheme[stx-expr], and for which the corresponding
|
|
@scheme[fender-expr] (if any) produces a true value; the result is
|
|
from the corresponding @scheme[result-expr], which is in tail position
|
|
for the @scheme[syntax-case] form. If no @scheme[clause] matches, then
|
|
the @exnraise[exn:fail:syntax]; the exception is generated by calling
|
|
@scheme[raise-syntax-error] with @scheme[#f] as the ``name'' argument,
|
|
a string with a generic error message, and the result of @scheme[stx-expr].
|
|
|
|
A syntax object matches a @scheme[pattern] as follows:
|
|
|
|
@specsubform[_]{
|
|
|
|
A @scheme[_] pattern (i.e., an identifier with the same binding as
|
|
@scheme[_]) matches any syntax object.}
|
|
|
|
@specsubform[id]{
|
|
|
|
An @scheme[id] matches any syntax object when it is not bound to
|
|
@scheme[...] or @scheme[_] and does not have the same binding as
|
|
any @scheme[literal-id]. The @scheme[id] is further bound as
|
|
@deftech{pattern variable} for the corresponding @scheme[fender-expr]
|
|
(if any) and @scheme[result-expr]. A pattern-variable binding is a
|
|
transformer binding; the pattern variable can be reference only
|
|
through forms like @scheme[syntax]. The binding's value is the syntax
|
|
object that matched the pattern with a @deftech{depth marker} of
|
|
@math{0}.
|
|
|
|
An @scheme[id] that has the same binding as a @scheme[literal-id]
|
|
matches a syntax object that is an identifier with the same binding
|
|
in the sense of @scheme[free-identifier=?]. The match does not
|
|
introduce any @tech{pattern variables}.}
|
|
|
|
@specsubform[(pattern ...)]{
|
|
|
|
A @scheme[(pattern ...)] pattern matches a syntax object whose datum
|
|
form (i.e., without lexical information) is a list with as many
|
|
elements as sub-@scheme[pattern]s in the pattern, and where each
|
|
syntax object that corresponds to an element of the list matches
|
|
the corresponding sub-@scheme[pattern].
|
|
|
|
Any @tech{pattern variables} bound by the sub-@scheme[pattern]s are
|
|
bound by the complete pattern; the bindings must all be distinct.}
|
|
|
|
@specsubform[(pattern ...+ . pattern)]{
|
|
|
|
The last @scheme[pattern] must not be a @racket/form[(pattern ...)],
|
|
@racket/form[(pattern ...+ . pattern)], @racket/form[(pattern ... pattern
|
|
ellipsis pattern ...)], or @racket/form[(pattern ... pattern ellipsis
|
|
pattern ... . pattern)] form.
|
|
|
|
Like the previous kind of pattern, but matches syntax objects that
|
|
are not necessarily lists; for @math{n} sub-@scheme[pattern]s before
|
|
the last sub-@scheme[pattern], the syntax object's datum must be a
|
|
pair such that @math{n-1} @scheme[cdr]s produce pairs. The last
|
|
sub-@scheme[pattern] is matched against the syntax object
|
|
corresponding to the @math{n}th @scheme[cdr] (or the
|
|
@scheme[datum->syntax] coercion of the datum using the nearest
|
|
enclosing syntax object's lexical context and source location).}
|
|
|
|
@specsubform[(pattern ... pattern ellipsis pattern ...)]{
|
|
|
|
Like the @scheme[(pattern ...)] kind of pattern, but matching a
|
|
syntax object with any number (zero or more) elements that match the
|
|
sub-@scheme[pattern] followed by @scheme[ellipsis] in the
|
|
corresponding position relative to other sub-@scheme[pattern]s.
|
|
|
|
For each pattern variable bound by the sub-@scheme[pattern] followed
|
|
by @scheme[ellipsis], the larger pattern binds the same pattern
|
|
variable to a list of values, one for each element of the syntax
|
|
object matched to the sub-@scheme[pattern], with an incremented
|
|
@tech{depth marker}. (The sub-@scheme[pattern] itself may contain
|
|
@scheme[ellipsis], leading to a pattern variables bound to lists of
|
|
lists of syntax objects with a @tech{depth marker} of @math{2}, and
|
|
so on.)}
|
|
|
|
@specsubform[(pattern ... pattern ellipsis pattern ... . pattern)]{
|
|
|
|
Like the previous kind of pattern, but with a final
|
|
sub-@scheme[pattern] as for @scheme[(pattern ...+ . pattern)]. The
|
|
final @scheme[pattern] never matches a syntax object whose datum is a
|
|
pair.}
|
|
|
|
@specsubform[(code:line #,(tt "#")(pattern ...))]{
|
|
|
|
Like a @scheme[(pattern ...)] pattern, but matching a vector syntax object
|
|
whose elements match the corresponding sub-@scheme[pattern]s.}
|
|
|
|
@specsubform[(code:line #,(tt "#")(pattern ... pattern ellipsis pattern ...))]{
|
|
|
|
Like a @scheme[(pattern ... pattern ellipsis pattern ...)] pattern,
|
|
but matching a vector syntax object whose elements match the
|
|
corresponding sub-@scheme[pattern]s.}
|
|
|
|
@specsubform[(code:line #,(tt "#s")(key-datum pattern ...))]{
|
|
|
|
Like a @scheme[(pattern ...)] pattern, but matching a @tech{prefab}
|
|
structure syntax object whose fields match the corresponding
|
|
sub-@scheme[pattern]s. The @scheme[key-datum] must correspond to a
|
|
valid first argument to @scheme[make-prefab-struct].}
|
|
|
|
@specsubform[(code:line #,(tt "#s")(key-datum pattern ... pattern ellipsis pattern ...))]{
|
|
|
|
Like a @scheme[(pattern ... pattern ellipsis pattern ...)] pattern,
|
|
but matching a @tech{prefab} structure syntax object whose elements
|
|
match the corresponding sub-@scheme[pattern]s.}
|
|
|
|
@specsubform[(ellipsis stat-pattern)]{
|
|
|
|
Matches the same as @scheme[stat-pattern], which is like a @scheme[pattern],
|
|
but identifiers with the binding @scheme[...] are treated the same as
|
|
other @scheme[id]s.}
|
|
|
|
@specsubform[const]{
|
|
|
|
A @scheme[const] is any datum that does not match one of the
|
|
preceding forms; a syntax object matches a @scheme[const] pattern
|
|
when its datum is @scheme[equal?] to the @scheme[quote]d
|
|
@scheme[const].}
|
|
|
|
@mz-examples[
|
|
(require (for-syntax racket/base))
|
|
(define-syntax (swap stx)
|
|
(syntax-case stx ()
|
|
[(_ a b) #'(let ([t a])
|
|
(set! a b)
|
|
(set! b t))]))
|
|
|
|
(let ([x 5] [y 10])
|
|
(swap x y)
|
|
(list x y))
|
|
|
|
(syntax-case #'(ops 1 2 3 => +) (=>)
|
|
[(_ x ... => op) #'(op x ...)])
|
|
|
|
(syntax-case #'(let ([x 5] [y 9] [z 12])
|
|
(+ x y z))
|
|
(let)
|
|
[(let ([var expr] ...) body ...)
|
|
(list #'(var ...)
|
|
#'(expr ...))])
|
|
]}
|
|
|
|
@defform[(syntax-case* stx-expr (literal-id ...) id-compare-expr
|
|
clause ...)]{
|
|
|
|
Like @scheme[syntax-case], but @scheme[id-compare-expr] must produce a
|
|
procedure that accepts two arguments. A @scheme[literal-id] in a
|
|
@scheme[_pattern] matches an identifier for which the procedure
|
|
returns true when given the identifier to match (as the first argument)
|
|
and the identifier in the @scheme[_pattern] (as the second argument).
|
|
|
|
In other words, @scheme[syntax-case] is like @scheme[syntax-case*] with
|
|
an @scheme[id-compare-expr] that produces @scheme[free-identifier=?].}
|
|
|
|
|
|
@defform[(with-syntax ([pattern stx-expr] ...)
|
|
body ...+)]{
|
|
|
|
Similar to @scheme[syntax-case], in that it matches a @scheme[pattern]
|
|
to a syntax object. Unlike @scheme[syntax-case], all @scheme[pattern]s
|
|
are matched, each to the result of a corresponding @scheme[stx-expr],
|
|
and the pattern variables from all matches (which must be distinct)
|
|
are bound with a single @scheme[body] sequence. The result of the
|
|
@scheme[with-syntax] form is the result of the last @scheme[body],
|
|
which is in tail position with respect to the @scheme[with-syntax]
|
|
form.
|
|
|
|
If any @scheme[pattern] fails to match the corresponding
|
|
@scheme[stx-expr], the @exnraise[exn:fail:syntax].
|
|
|
|
A @scheme[with-syntax] form is roughly equivalent to the following
|
|
@scheme[syntax-case] form:
|
|
|
|
@schemeblock[
|
|
(syntax-case (list stx-expr ...) ()
|
|
[(pattern ...) (let () body ...+)])
|
|
]
|
|
|
|
However, if any individual @scheme[stx-expr] produces a
|
|
non-@tech{syntax object}, then it is converted to one using
|
|
@scheme[datum->syntax] and the lexical context and source location of
|
|
the individual @scheme[stx-expr].
|
|
|
|
@examples[#:eval (syntax-eval)
|
|
(define-syntax (hello stx)
|
|
(syntax-case stx ()
|
|
[(_ name place)
|
|
(with-syntax ([print-name #'(printf "~a\n" 'name)]
|
|
[print-place #'(printf "~a\n" 'place)])
|
|
#'(begin
|
|
(define (name times)
|
|
(printf "Hello\n")
|
|
(for ([i (in-range 0 times)])
|
|
print-name))
|
|
(define (place times)
|
|
(printf "From\n")
|
|
(for ([i (in-range 0 times)])
|
|
print-place))))]))
|
|
|
|
(hello jon utah)
|
|
(jon 2)
|
|
(utah 2)
|
|
|
|
(define-syntax (math stx)
|
|
(define (make+1 expression)
|
|
(with-syntax ([e expression])
|
|
#'(+ e 1)))
|
|
(syntax-case stx ()
|
|
[(_ numbers ...)
|
|
(with-syntax ([(added ...)
|
|
(map make+1
|
|
(syntax->list #'(numbers ...)))])
|
|
#'(begin
|
|
(printf "got ~a\n" added)
|
|
...))]))
|
|
|
|
(math 3 1 4 1 5 9)
|
|
]}
|
|
|
|
@defform/subs[(syntax template)
|
|
([template id
|
|
(template-elem ...)
|
|
(template-elem ...+ . template)
|
|
(code:line #,(tt "#")(template-elem ...))
|
|
(code:line #,(tt "#s")(key-datum template-elem ...))
|
|
(ellipsis stat-template)
|
|
const]
|
|
[template-elem (code:line template ellipsis ...)]
|
|
[stat-template id
|
|
(stat-template ...)
|
|
(stat-template ... . stat-template)
|
|
(code:line #,(tt "#")(stat-template ...))
|
|
(code:line #,(tt "#s")(key-datum stat-template ...))
|
|
const]
|
|
[ellipsis #,lit-ellipsis])]{
|
|
|
|
Constructs a syntax object based on a @scheme[template],which can
|
|
inlude @tech{pattern variables} bound by @scheme[syntax-case] or
|
|
@scheme[with-syntax].
|
|
|
|
Template forms produce a syntax object as follows:
|
|
|
|
@specsubform[id]{
|
|
|
|
If @scheme[id] is bound as a @tech{pattern variable}, then
|
|
@scheme[id] as a template produces the @tech{pattern variable}'s
|
|
match result. Unless the @scheme[id] is a sub-@scheme[template] that is
|
|
replicated by @scheme[ellipsis] in a larger @scheme[template], the
|
|
@tech{pattern variable}'s value must be a syntax object with a
|
|
@tech{depth marker} of @math{0} (as opposed to a list of
|
|
matches).
|
|
|
|
More generally, if the @tech{pattern variable}'s value has a depth
|
|
marker @math{n}, then it can only appear within a template where it
|
|
is replicated by at least @math{n} @scheme[ellipsis]es. In that case,
|
|
the template will be replicated enough times to use each match result
|
|
at least once.
|
|
|
|
If @scheme[id] is not bound as a pattern variable, then @scheme[id]
|
|
as a template produces @scheme[(quote-syntax id)].}
|
|
|
|
@specsubform[(template-elem ...)]{
|
|
|
|
Produces a syntax object whose datum is a list, and where the
|
|
elements of the list correspond to syntax objects produced by the
|
|
@scheme[template-elem]s.
|
|
|
|
A @scheme[template-elem] is a sub-@scheme[template] replicated by any
|
|
number of @scheme[ellipsis]es:
|
|
|
|
@itemize[
|
|
|
|
@item{If the sub-@scheme[template] is replicated by no
|
|
@scheme[ellipsis]es, then it generates a single syntax object to
|
|
incorporate into the result syntax object.}
|
|
|
|
@item{If the sub-@scheme[template] is replicated by one
|
|
@scheme[ellipsis], then it generates a sequence of syntax objects
|
|
that is ``inlined'' into the resulting syntax object.
|
|
|
|
The number of generated elements depends on the values of
|
|
@tech{pattern variables} referenced within the
|
|
sub-@scheme[template]. There must be at least one @tech{pattern
|
|
variable} whose value has a @tech{depth marker} less than the
|
|
number of @scheme[ellipsis]es after the pattern variable within the
|
|
sub-@scheme[template].
|
|
|
|
If a @tech{pattern variable} is replicated by more
|
|
@scheme[ellipsis]es in a @scheme[template] than the @tech{depth
|
|
marker} of its binding, then the @tech{pattern variable}'s result
|
|
is determined normally for inner @scheme[ellipsis]es (up to the
|
|
binding's @tech{depth marker}), and then the result is replicated
|
|
as necessary to satisfy outer @scheme[ellipsis]es.}
|
|
|
|
@item{For each @scheme[ellipsis] after the first one, the preceding
|
|
element (with earlier replicating @scheme[ellipsis]es) is
|
|
conceptually wrapped with parentheses for generating output, and
|
|
then the wrapping parentheses are removed in the resulting syntax
|
|
object.}]}
|
|
|
|
@specsubform[(template-elem ... . template)]{
|
|
|
|
Like the previous form, but the result is not necessarily a list;
|
|
instead, the place of the empty list in the resulting syntax object's
|
|
datum is taken by the syntax object produced by @scheme[template].}
|
|
|
|
@specsubform[(code:line #,(tt "#")(template-elem ...))]{
|
|
|
|
Like the @scheme[(template-elem ...)] form, but producing a syntax
|
|
object whose datum is a vector instead of a list.}
|
|
|
|
@specsubform[(code:line #,(tt "#s")(key-datum template-elem ...))]{
|
|
|
|
Like the @scheme[(template-elem ...)] form, but producing a syntax
|
|
object whose datum is a @tech{prefab} structure instead of a list.
|
|
The @scheme[key-datum] must correspond to a valid first argument of
|
|
@scheme[make-prefab-struct].}
|
|
|
|
@specsubform[(ellipsis stat-template)]{
|
|
|
|
Produces the same result as @scheme[stat-template], which is like a
|
|
@scheme[template], but @scheme[...] is treated like an @scheme[id]
|
|
(with no pattern binding).}
|
|
|
|
@specsubform[const]{
|
|
|
|
A @scheme[const] template is any form that does not match the
|
|
preceding cases, and it produces the result @scheme[(quote-syntax
|
|
const)].}
|
|
|
|
A @scheme[(#,(schemekeywordfont "syntax") template)] form is normally
|
|
abbreviated as @scheme[#'template]; see also
|
|
@secref["parse-quote"]. If @scheme[template] contains no pattern
|
|
variables, then @scheme[#'template] is equivalent to
|
|
@scheme[(quote-syntax template)].}
|
|
|
|
|
|
@defform[(quasisyntax template)]{
|
|
|
|
Like @scheme[syntax], but @scheme[(#,(schemekeywordfont "unsyntax")
|
|
_expr)] and @scheme[(#,(schemekeywordfont "unsyntax-splicing") _expr)]
|
|
escape to an expression within the @scheme[template].
|
|
|
|
The @scheme[_expr] must produce a syntax object (or syntax list) to be
|
|
substituted in place of the @scheme[unsyntax] or
|
|
@scheme[unsyntax-splicing] form within the quasiquoting template, just
|
|
like @scheme[unquote] and @scheme[unquote-splicing] within
|
|
@scheme[quasiquote]. (If the escaped expression does not generate a
|
|
syntax object, it is converted to one in the same way as for the
|
|
right-hand side of @scheme[with-syntax].) Nested
|
|
@scheme[quasisyntax]es introduce quasiquoting layers in the same way
|
|
as nested @scheme[quasiquote]s.
|
|
|
|
Also analogous to @scheme[quasiquote], the reader converts @litchar{#`}
|
|
to @scheme[quasisyntax], @litchar{#,} to @scheme[unsyntax], and
|
|
@litchar["#,@"] to @scheme[unsyntax-splicing]. See also
|
|
@secref["parse-quote"].}
|
|
|
|
|
|
|
|
@defform[(unsyntax expr)]{
|
|
|
|
Illegal as an expression form. The @scheme[unsyntax] form is for use
|
|
only with a @scheme[quasisyntax] template.}
|
|
|
|
|
|
@defform[(unsyntax-splicing expr)]{
|
|
|
|
Illegal as an expression form. The @scheme[unsyntax-splicing] form is
|
|
for use only with a @scheme[quasisyntax] template.}
|
|
|
|
|
|
@defform[(syntax/loc stx-expr template)]{
|
|
|
|
Like @scheme[syntax], except that the immediate resulting syntax
|
|
object takes its source-location information from the result of
|
|
@scheme[stx-expr] (which must produce a syntax object), unless the
|
|
@scheme[template] is just a pattern variable, or both the source and
|
|
position of @scheme[stx-expr] are @scheme[#f].}
|
|
|
|
|
|
@defform[(quasisyntax/loc stx-expr template)]{
|
|
|
|
Like @scheme[quasisyntax], but with source-location assignment like
|
|
@scheme[syntax/loc].}
|
|
|
|
|
|
@defform[(quote-syntax/prune id)]{
|
|
|
|
Like @scheme[quote-syntax], but the lexical context of @scheme[id] is
|
|
pruned via @scheme[identifier-prune-lexical-context] to including
|
|
binding only for the symbolic name of @scheme[id] and for
|
|
@scheme['#%top]. Use this form to quote an identifier when its lexical
|
|
information will not be transferred to other syntax objects (except
|
|
maybe to @scheme['#%top] for a top-level binding).}
|
|
|
|
|
|
@defform[(syntax-rules (literal-id ...)
|
|
[(id . pattern) template] ...)]{
|
|
|
|
Equivalent to
|
|
|
|
@schemeblock/form[
|
|
(lambda (stx)
|
|
(syntax-case stx (literal-id ...)
|
|
[(_generated-id . pattern) (syntax template)] ...))
|
|
]
|
|
|
|
where each @scheme[_generated-id] binds no identifier in the
|
|
corresponding @scheme[template].}
|
|
|
|
|
|
@defform[(syntax-id-rules (literal-id ...)
|
|
[pattern template] ...)]{
|
|
|
|
Equivalent to
|
|
|
|
@schemeblock[
|
|
(lambda (stx)
|
|
(make-set!-transformer
|
|
(syntax-case stx (literal-id ...)
|
|
[pattern (syntax template)] ...)))
|
|
]}
|
|
|
|
|
|
@defform[(define-syntax-rule (id . pattern) template)]{
|
|
|
|
Equivalent to
|
|
|
|
@schemeblock/form[
|
|
(define-syntax id
|
|
(syntax-rules ()
|
|
[(id . pattern) template]))
|
|
]
|
|
|
|
but with syntax errors potentially phrased in terms of
|
|
@racket[pattern].}
|
|
|
|
|
|
@defidform[...]{
|
|
|
|
The @scheme[...] transformer binding prohibits @scheme[...] from
|
|
being used as an expression. This binding is useful only in syntax
|
|
patterns and templates, where it indicates repetitions of a pattern or
|
|
template. See @scheme[syntax-case] and @scheme[syntax].}
|
|
|
|
@defidform[_]{
|
|
|
|
The @scheme[_] transformer binding prohibits @scheme[_] from being
|
|
used as an expression. This binding is useful only in syntax patterns,
|
|
where it indicates a pattern that matches any syntax object. See
|
|
@scheme[syntax-case].}
|
|
|
|
|
|
@defproc[(syntax-pattern-variable? [v any/c]) boolean?]{
|
|
|
|
Returns @scheme[#t] if @scheme[v] is a value that, as a
|
|
transformer-binding value, makes the bound variable as pattern
|
|
variable in @scheme[syntax] and other forms. To check whether an
|
|
identifier is a pattern variable, use @scheme[syntax-local-value] to
|
|
get the identifier's transformer value, and then test the value with
|
|
@scheme[syntax-pattern-variable?].
|
|
|
|
The @scheme[syntax-pattern-variable?] procedure is provided
|
|
@scheme[for-syntax] by @schememodname[racket/base].}
|