1.3 Parsing Syntax
Syntax:
Meta-
Programming Helpers
Parsing and Specifying Syntax
Syntax Object Helpers
Datum Pattern Matching
Module-
Processing Helpers
Macro Transformer Helpers
Reader Helpers
Parsing
for
Bodies
Unsafe
for
Clause Transforms
Source Locations
10
Preserving Source Locations
11
Non-
Module Compilation And Expansion
12
Trusting Standard Recertifying Transformers
13
Attaching Documentation to Exports
14
Contracts for Macro Subexpressions
15
Macro Testing
16
Internal-
Definition Context Helpers
Index
Parsing and Specifying Syntax
1.1
Introduction
1.2
Examples
1.3
Parsing Syntax
1.4
Specifying Syntax with Syntax Classes
1.5
Syntax Patterns
1.6
Defining Simple Macros
1.7
Literal Sets and Conventions
1.8
Library Syntax Classes and Literal Sets
1.9
Unwindable State
1.10
Configuring Error Reporting
1.11
Debugging and Inspection Tools
1.12
Experimental
1.13
Minimal Library
On this page:
syntax-
parse
syntax-
parser
define/
syntax-
parse
Racket
top
contents
← prev
up
next →
1.3
Parsing Syntax
This section describes
syntax-parse
, the
syntax/parse
library’s facility for parsing
syntax. Both
syntax-parse
and the specification facility,
syntax classes
, use a common language
of
syntax patterns
, which is described in detail in
Syntax Patterns
Two parsing forms are provided:
syntax-parse
and
syntax-parser
syntax
syntax-parse
stx-expr
parse-option
...
clause
...+
parse-option
#:context
context-expr
#:literals
literal
...
#:datum-literals
datum-literal
...
#:literal-sets
literal-set
...
#:track-literals
#:conventions
convention-id
...
#:local-conventions
convention-rule
...
#:disable-colon-notation
literal
literal-id
pattern-id
literal-id
pattern-id
literal-id
#:phase
phase-expr
datum-literal
literal-id
pattern-id
literal-id
literal-set
literal-set-id
literal-set-id
literal-set-option
...
literal-set-option
#:at
context-id
#:phase
phase-expr
clause
syntax-pattern
pattern-directive
...
body
...+
stx-expr
syntax?
context-expr
or/c
syntax?
symbol?
#f
list/c
symbol?
syntax?
phase-expr
or/c
exact-integer?
#f
Evaluates
stx-expr
, which should produce a syntax object, and
matches it against the
clause
s in order. If some clause’s
pattern matches, its attributes are bound to the corresponding
subterms of the syntax object and that clause’s side conditions and
expr
is evaluated. The result is the result of
expr
Each clause consists of a
syntax pattern
, an optional sequence
of
pattern directives
, and a non-empty sequence of body
forms.
If the syntax object fails to match any of the patterns (or all
matches fail the corresponding clauses’ side conditions), a syntax
error is raised.
The following options are supported:
#:context
context-expr
context-expr
or/c
syntax?
symbol?
#f
list/c
symbol?
syntax?
When present,
context-expr
is used in reporting parse
failures; otherwise
stx-expr
is used. If
context-expr
evaluates to
list
who
context-stx
then
who
appears in the error message as the form raising
the error, and
context-stx
is used as the term. If
context-expr
evaluates to a symbol, it is used as
who
and
stx-expr
(the syntax to be destructured) is
used as
context-stx
. If
context-expr
evaluates to a
syntax object, it is used as
context-stx
and
who
is inferred as with
raise-syntax-error
The
current-syntax-context
parameter is also set to the
syntax object
context-stx
Examples:
syntax-parse
#'
x:id
...
ok
a: expected identifier
at: 3
in: (a b 3)
syntax-parse
#'
#:context
#'
lambda
x:id
...
ok
lambda: expected identifier
at: 3
in: (lambda (a b 3) (+ a b))
syntax-parse
#'
#:context
check-id-list
x:id
...
ok
check-id-list: expected identifier
at: 3
in: (a b 3)
#:literals
literal
...
literal
literal-id
pattern-id
literal-id
pattern-id
literal-id
#:phase
phase-expr
phase-expr
or/c
exact-integer?
#f
Unlike
syntax-case
syntax-parse
requires all
literals to have a binding. To match identifiers by their symbolic
names, use
#:datum-literals
or the
~datum
pattern
form instead.
The
#:literals
option specifies identifiers that should be
treated as
literals
rather than
pattern variables
. An
entry in the literals list has two components: the identifier used
within the pattern to signify the positions to be matched
pattern-id
), and the identifier expected to occur in those
positions (
literal-id
). If the entry is a single identifier,
that identifier is used for both purposes.
If the
#:phase
option is given, then the literal is compared
at phase
phase-expr
. Specifically, the binding of the
literal-id
at phase
phase-expr
must match the
input’s binding at phase
phase-expr
In other words, the
syntax-pattern
s are interpreted as if each
occurrence of
pattern-id
were replaced with the following pattern:
~literal
literal-id
#:phase
phase-expr
#:datum-literals
datum-literal
...
datum-literal
literal-id
pattern-id
literal-id
Like
#:literals
, but the literals are matched as symbols
instead of as identifiers.
In other words, the
syntax-pattern
s are interpreted as if each
occurrence of
pattern-id
were replaced with the following
pattern:
~datum
literal-id
#:literal-sets
literal-set
...
literal-set
literal-set-id
literal-set-id
literal-set-option
...
literal-set-option
#:at
lctx
#:phase
phase-expr
phase-expr
or/c
exact-integer?
#f
Many literals can be declared at once via one or more
literal
sets
, imported with the
#:literal-sets
option. See
literal sets
for more information.
If the
#:at
keyword is given, the lexical context of the
lctx
term is used to determine which identifiers in the
patterns are treated as literals; this option is useful primarily for
macros that generate
syntax-parse
expressions.
#:track-literals
If specified, each final
body
expression is further constrained to
produce a single value, which must be a
syntax object
, and
its
disappeared-use
syntax property
is
automatically extended to include literals matched as part of pattern-matching.
Literals are automatically tracked from uses of
#:literals
#:literal-sets
, or
~literal
, but they can also be manually
tracked using
syntax-parse-state-cons!
. The property is added or
extended in the same way as a property added by
syntax-parse-track-literals
Due to the way the
body
forms are wrapped, specifying this option means
the final
body
form will no longer be in tail position with respect to
the enclosing
syntax-parse
form.
Added in version 6.90.0.29 of package
base
#:conventions
conventions-id
...
Imports
convention
s that give default syntax classes to pattern
variables that do not explicitly specify a syntax class.
#:local-conventions
convention-rule
...
Uses the
conventions
specified. The advantage of
#:local-conventions
over
#:conventions
is that local
conventions can be in the scope of syntax-class parameter
bindings. See the section on
conventions
for examples.
#:disable-colon-notation
Suppresses the “colon notation” for annotated pattern variables.
Examples:
syntax-parse
#'
x:y
...
ok
syntax-parse: not defined as syntax class
at: y
in: (syntax-parse (syntax (a b c)) ((x:y ...) (quote ok)))
syntax-parse
#'
#:disable-colon-notation
x:y
...
ok
'ok
syntax
syntax-parser
parse-option
...
clause
...+
Like
syntax-parse
, but produces a matching procedure. The
procedure accepts a single argument, which should be a syntax object.
syntax
define/syntax-parse
syntax-pattern
pattern-directive
...
stx-expr
stx-expr
syntax?
Definition form of
syntax-parse
. That is, it matches the
syntax object result of
stx-expr
against
syntax-pattern
and creates pattern variable definitions for
the attributes of
syntax-pattern
Examples:
define/syntax-parse
~seq
kw:keyword
arg:expr
...
#'
#:a
#:b
#:c
#'
kw
...
#
Compare with
define/with-syntax
, a similar definition form
that uses the simpler
syntax-case
patterns.
top
contents
← prev
up
next →