6.53 Syntax Classes

8.12

6.53 Syntax Classes🔗ℹ

definition

...

| ...

maybe_args	=	(id_bind, ...)
	\|	(id_bind, ..., & rest_id)
	\|	ϵ

class_clause	=	description desc_rhs
	\|	error_mode error_mode_rhs
	\|	kind kind_rhs
	\|	fields: field_decl
	\|	root_swap: id id

pattern_case	=	syntax_pattern
	\|	syntax_pattern: pattern_body; ...

pattern_body	=	field field_decl
	\|	match_def also_decl
	\|	match_when when_rhs
	\|	match_unless unless_rhs
	\|	body

Defines a syntax class that can be used in syntax patterns with ::. A syntax class can optionally have arguments, in which case every use of the syntax class with :: must supply arguments; an id_bind is like a bind_maybe_kw_opt for fun, but each binding must be a plain id (i.e., annotations and general pattern matching are not supported). Identifiers bound as arguments are visible in class_clause bodies. Use syntax_class.together to define a syntax class that refers to itself or a group of mutually referential 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; insteda, messages will use the decsription 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 feild; 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.

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 evey variable in every match_def is a candiate field name, as long as it is also a candiate 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

definition

syntax_class.together:

syntax_class stxclass_decl

...

Declares syntax classes that can refer to themselves and each other. Unlike a syntax_class form in other contexts, each syntax_class form within syntax_class.together is required to declare its fields with fields, otherwise no fields are available from the syntax class.

syntax_class.together:
  syntax_class ModPath:
    fields: [elem, ...]
  | '$head':
      field [elem, ...]: [head]
  | '$head / $(mp :: ModPath)':
      field [elem, ...] = [head, mp.elem, ...]

> match 'a / b / c'
| '$(mp :: ModPath)':
[mp.elem, ...]
['a', 'b', 'c']

syntax class clause

fields spec ...

syntax class clause

fields: spec ...; ...

spec	=	id_maybe_rep
	\|	id_maybe_rep: kind kind_decl

id_maybe_rep	=	id
	\|	[id_maybe_rep, ellipsis]

ellipsis

...

Limits the set of fields that are provided by a syntax class to the listed ids. See syntax_class. A field’s repetition depth is declared by wrapping it within […] with ... like a repetition binding. If no spec is present at all, no fields will be provided.

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.

syntax class clause

root_swap: id id

Adjusts the match value and fields of a syntax class. The first id names a field that the syntax class would otherwise provide, but the field is removed, and its value instead becomes the main value of an identifier that is bound with the syntax class. Meanwhile, the matching terms that would otherwise be the variable’s value are associated instead with a fresh field named by the second id.

syntax_class Parenthesized:
root_swap: content group
| '($content)'

> match '(1 2 3)'
| '$(p :: Parenthesized)':
[p, p.group]
['1 2 3', '(1 2 3)']

syntax class clause

description:

body;

...

syntax class clause

description expr

Configures a syntax class’s description for error reporting. See syntax_class.

syntax class clause

error_mode: error_mode_keyword

syntax class clause

error_mode error_mode_keyword

error_mode_keyword	=	~opaque
	\|	~transparent

Configures the way that failures to match a syntax class are reported. See syntax_class.

syntax class clause

kind: kind_keyword

syntax class clause

kind kind_keyword

kind_keyword	=	~term
	\|	~sequence
	\|	~group
	\|	~multi
	\|	~block

Provided both normally and as meta.

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.

1	Rhombus Essentials
2	Collections and Iteration
3	Syntax Objects and Macros
4	Classes and Interfaces
5	Static Information and Binding
6	Core Reference
7	Meta and Macros Reference
8	Rhombus Static by Default
9	Libraries
10	Naming Conventions

6.1	General Forms
6.2	Definitions
6.3	Namespaces
6.4	Import
6.5	Export
6.6	Functions
6.7	Operators
6.8	Classes and Interfaces
6.9	Veneers
6.10	Mutable Variables and Assignment
6.11	Repetitions
6.12	Block
6.13	Conditionals
6.14	Matching
6.15	Iteration
6.16	Recursion
6.17	Context Parameters
6.18	Exceptions
6.19	Continuations
6.20	Implicit Forms
6.21	Static and Dynamic Lookup
6.22	Modules and Submodules
6.23	Booleans
6.24	Numbers
6.25	Characters
6.26	Strings
6.27	Keywords
6.28	Symbols
6.29	Byte Strings
6.30	Lists
6.31	Pairs and Pair Lists
6.32	Mutable Lists
6.33	Arrays
6.34	Maps
6.35	Sets
6.36	Boxes
6.37	Indexables
6.38	Listables
6.39	Sequences
6.40	Appendables
6.41	Comparables
6.42	Paths
6.43	Source Locations
6.44	Void
6.45	Equality
6.46	Dot
6.47	Multiple Values
6.48	Annotations
6.49	Enumerations
6.50	Input and Output
6.51	Eval
6.52	Syntax Objects
6.53	Syntax Classes
6.54	Simple Expression Macros
6.55	Unit Testing