11.2 Syntax Classes🔗ℹ

Syntax forms matched by the syntax class are described by pattern_case alternatives. Each kind of class_clause alternative can be supplied at most once.

An optional description clause provides a description of the syntax class, which is used to produce clearer error messages when a term is rejected by the syntax class. The result of the block block must be a string or #false, where #false is equivalent to not specifying a description. When error_mode is declared as ~opaque, then parsing error messages will not refer to the interior details of the pattern cases; instead, messages will use the description string.

An optional kind declaration indicates the context within a pattern where a syntax class can be used, and it determines the kind of match that each pattern specifies. See kind for details. The default is inferred from the shapes for pattern_cases as either ~term, ~sequence, or ~multi.

A fields declaration limits the set of pattern variables that are accessible from the class, where variables used in all pattern_cases are otherwise available (as described next). Each identifier in fields must be a field name that would be made available. A fields declaration can also specify the repetition depth and context kind of a field, in which case pattern_cases must be consistent with the declaration; see fields for more information. A root_swap class moves the value of one of the would-be fields to the root while moving the root to a fresh field; see root_swap for more information.

The pattern_case alternatives are the main content of a syntax class. After the class name is defined, then when a variable id is bound through a syntax pattern with $(id :: name), it matches a syntax object that matches any of the pattern_cases in the definition of stx_class_id, where the pattern_cases are tried first to last. A pattern variable that is included in all of the pattern_cases is a field of the syntax class, which is accessed from a binding id using dot notation. For example, if the pattern variable is var, its value is accessed from id using id.var. When a field is a repetition, it can only be accessed statically—that is, when the id in id.var is bound as a pattern variable annotated with stxclass_id, or via expr.var when expr has the static information of Syntax.matched_of(stxclass_id). When a syntax object with fields for a syntax class is used to produce another system object (e.g., the syntax object is used in a template to make a larger syntax object), fields are not associated with any part of the new syntax object; however, a syntax object with fields preserves its fields when bound itself as a field value in another syntax class.

A pattern_case matches when

• the syntax_pattern at the start of the pattern_case matches;

• every match_def clause within the pattern_case body also matches;

• every match_when clause within the pattern_case body has a true value for its right-hand side; and

• every match_unless clause within the pattern_case body has a false value for its right-hand side.

Every pattern variable in the initial syntax_pattern of a pattern_case as well as every variable in every match_def is a candidate field name, as long as it is also a candidate in all other syntax_patterns within the syntax class. In addition, names declared with field are also candidates. A field must have the same repetition depth across all pattern cases, unless it is excluded from the syntax class’s result through a fields declaration that does not list the field.

The body of a pattern_case can include other definitions and expressions. Those definitions and expressions can use pattern variables bound in the main syntax_pattern of the case as well as any preceding match_def clause or a field declared by a preceding field. Consecutive definitions and expressions within a pattern_case form a definition context, but separated sets of definitions and expressions can refer only to definitions in earlier sets.

A variable bound with a syntax class (within a syntax pattern) can be used without dot notation. The variable is bound to a syntax object corresponding to the entire match of a syntax_pattern.

> meta syntax_class Arithmetic   | '$x + $y'   | '$x - $y'

> expr.macro 'doubled_operands $(a :: Arithmetic)':     '$a.x * 2 + $a.y * 2'

> doubled_operands 3 + 5

16

> expr.macro 'add_one_to_expression $(a :: Arithmetic)':     '$a + 1'

> add_one_to_expression 2 + 2

5

> meta syntax_class NTerms   | '~one $a':       field b = '0'       field average = '$(a.unwrap() / 2)'   | '~two $a $b':       def sum = a.unwrap() + b.unwrap()       field average = '$(sum / 2)'

> expr.macro 'second_term $(e :: NTerms)':     e.b

> second_term ~two 1 2

2

> second_term ~one 3

0

> expr.macro 'average $(e :: NTerms)':     e.average

> average ~two 24 42

33

If a kind is not declared for a field identifier, then the context kind is inferred from patterns within the syntax class. If kind is declared, then it must match the context kind that would be inferred for the field from all patterns.

Determines the contexts where a syntax class can be used and the kinds of matches that it produces:

• ~term: each pattern case represents a single term, and the syntax class can be used in the same way at the Term syntax class.

• ~sequence: each pattern case represents a sequence of terms that is spliced within a group. This is the default mode of a syntax class when no kind is specified.

• ~group: each pattern case represents a group, and the syntax class can be used in the same places as Group (i.e., at the end of an enclosing group).

• ~multi: each pattern case represents multiple groups, and the syntax class can be used in the same way at the Multi syntax class.

• ~block: each pattern case represents a block, and the syntax class can be used in the same way at the Block syntax class

With ~term, each pattern case must match only a single term, and with ~block, each pattern case must be a block pattern.

See also syntax_class.

The result of the right-hand body sequence or expr is not required to be a syntax object or have syntax objects in nested lists. If the field is referenced so that it’s value is included in a syntax template, a non-syntax value is converted to syntax at that point. Otherwise, the field can be used directly to access non-syntax values.

See also syntax_class.

See syntax_class.

See syntax_class.

Syntax classes, all of which imply a single-term match except for Sequence, Group, Multi, Block, and IdentifierName.

The Sequence syntax class matches any number of terms, including zero terms. That is, it matches a group or a multi-group sequence that has zero groups.

The Group syntax class can be used only for a pattern identifier that has no other pattern escapes after it in the same group. The identifier is bound to a match for a non-empty sequence of term syntax objects.

The Multi syntax class can be used only for a pattern identifier that is alone within its group. The identifier is bound to a match for a sequence of groups.

The Block syntax class can be used only for a pattern escape that is along within a block. The identifier is bound to a match for the entire block as a single term (i.e., as a single-term syntax object that has a block term, and not as a multi-group syntax object).

The Name syntax class is an extension of the union of Identifier and Operator that matches dotted sequences like an op_or_id_name form.

The IdentifierName syntax class is an extension of Identifier that matches dotted sequences like an id_name form.

The Literal syntax class matches a term that is not an identifier, operator, block, or alternatives.