8.4 Syntax Classes
Syntax classes provide an abstraction mechanism for the specification
of syntax. Built-in syntax classes are supplied that recognize basic
classes such as identifier and keyword.
Programmers can compose basic syntax classes to build specifications
of more complex syntax, such as lists of distinct identifiers and
formal arguments with keywords. Macros that manipulate the same
syntactic structures can share syntax class definitions. The structure
of syntax classes and patterns also allows syntax-parse to
automatically generate error messages for syntax errors.
When a syntax class accepts (matches) a syntax object, it computes and
provides attributes based on the contents of the matched syntax. While
the values of the attributes depend on the matched syntax, the set of
attributes and each attribute’s ellipsis nesting depth is fixed for
each syntax class.
|
|
| |
| stxclass-option | | = | | #:attributes (attr-arity-decl ...) | | | | | | | #:description description | | | | | | | #:transparent | | | | | | | #:literals (literal-entry ...) | | | | | | | #:literal-sets (literal-set ...) | | | | | | | #:conventions (convention-id ...) | | | | | | | | attr-arity-decl | | = | | attr-name-id | | | | | | | (attr-name-id depth) | | | | | | | | stxclass-variant | | = | | (pattern syntax-pattern stxclass-pattern-directive ...) |
|
Defines
name-id as a syntax class. When the
arg-ids
are present, they are bound as variables (not pattern variables) in
the body. The body of the syntax-class definition contains a non-empty
sequence of
pattern variants.
| #:attributes (attr-arity-decl ...) |
Declares the attributes of the syntax class. An attribute arity
declaration consists of the attribute name and optionally its ellipsis
depth (zero if not explicitly specified).
If the attributes are not explicitly listed, they are inferred as the
set of all pattern variables occurring in every variant of the syntax
class. Pattern variables that occur at different ellipsis depths are
not included. Only nested attributes from previously declared syntax
classes are included.
| #:description description |
The description argument is an expression (evaluated in a
scope containing the syntax class’s parameters) that should evaluate
to a string. It is used in error messages involving the syntax
class. For example, if a term is rejected by the syntax class, an
error of the form "expected description" may
be synthesized.
If absent, the name of the syntax class is used instead.
Indicates that errors may be reported with respect to the internal
structure of the syntax class.
| #:literals (literal-entry) |
| #:literal-sets (literal-set ...) |
| #:conventions (convention-id ...) |
Declares the literals and conventions that apply to the syntax class’s
variant patterns and their immediate #:with clauses. Patterns
occuring within subexpressions of the syntax class (for example, on
the right-hand side of a #:fail-when clause) are not
affected.
These options have the same meaning as under syntax-parse.
| (pattern syntax-pattern stxclass-pattern-directive ...) |
| |
| stxclass-pattern-directive | | = | | pattern-directive | | | | | | | #:rename internal-id external-id |
|
Accepts syntax matching the given syntax pattern with the accompanying
pattern directives as in syntax-parse.
The attributes of the variant are the attributes of the pattern
together with all attributes bound by #:with clauses,
including nested attributes produced by syntax classes associated with
the pattern variables.
Defines
name-id as a splicing syntax class. A splicing syntax
class encapsulates
H-patterns as an ordinary syntax class
encapsulates
S-patterns.
8.4.1 Attributes
A syntax class has a set of attributes. Each attribute has a
name, an ellipsis depth, and a set of nested attributes. When an
instance of the syntax class is parsed and bound to a pattern
variable, additional pattern variables are bound for each of the
syntax class’s attributes. The name of these additional pattern
variables is the dotted concatenation of the primary pattern
variable with the name of the attribute.
For example, if pattern variable p is bound to an instance of
a syntax class with attribute a, then the pattern variable
p.a is bound to the value of that attribute. The ellipsis
depth of p.a is the sum of the depths of p and
attribute a.
The attributes of a syntax class are either given explicitly with an
#:attributes option or inferred from the pattern variables of
the syntax class’s variants.
8.4.2 Inspection tools
The following special forms are for debugging syntax classes.
Returns a list of the syntax class’s attributes in flattened
form. Each attribute is listed by its name and ellipsis depth.
Runs the parser for the syntax class (parameterized by the
arg-exprs) on the syntax object produced by
stx-expr. On success, the result is a list of vectors
representing the attribute bindings of the syntax class. Each vector
contains the attribute name, depth, and associated value. On failure,
the result is some internal representation of the failure.