8.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.

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   :   syntax?

When present, context-expr is used in reporting parse failures; otherwise stx-expr is used.

Examples:

> (syntax-parse #'(a b 3)       [(x:id ...) 'ok])

a: expected identifier at: 3

> (syntax-parse #'(a b 3)       #:context #'(lambda (a b 3) (+ a b))       [(x:id ...) 'ok])

lambda: expected identifier at: 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 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.

#:literal-sets (literal-set ...)

literal-set   =   literal-set-id     |   (literal-set-id literal-set-option ...)           literal-set-option   =   #:at context-id     |   #: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.

#:conventions (conventions-id ...)

Imports conventions 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.

Each clause consists of a syntax pattern, an optional sequence of pattern directives, and a non-empty sequence of body expressions.