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.

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

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

#: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.

#:disable-colon-notation

Suppresses the “colon notation” for annotated pattern variables.

Examples:

> (syntax-parse #'(a b c)     [(x:y ...) 'ok]) syntax-parse: not defined as syntax class at: y > (syntax-parse #'(a b c) #:disable-colon-notation     [(x:y ...) 'ok]) 'ok

Examples:

> (define/syntax-parse ((~seq kw:keyword arg:expr) ...)     #'(#:a 1 #:b 2 #:c 3)) > #'(kw ...) #<syntax:123:0 (#:a #:b #:c)>

Compare with define/with-syntax, a similar definition form that uses the simpler syntax-case patterns.