17.4 Definition Macros

Defines defined_name as a macro in the expr space. The macro can be used in a definition context, where the compile-time body block returns the expansion result. The macro pattern is matched to an entire group in a definition context.

The expansion result must be a sequence of groups that are inlined in place of the definition-macro use.

The options in the macro body must be distinct. The ~op_stx option, if present, binds an identifier for a use of the macro (which cannot be matched directly in the pattern, since that position is used for the name that defn.macro binds). The ~all_stx option binds an identifier to the input that is matched by the prefix_macro_pattern, which includes the identifier or operator that ~op_stx would capture. The ~name_prefix option binds an identifier to a symbol or #false for a name prefix created by an enclosing namespace; this prefix should not be used for the binding, but it should be used for run-time reports, such as as naming the origin of a run-time error.

Using | alternatives, a single definition can have any number of patterns, which are tried in order. The defined_name must be the same across all cases.

> defn.macro 'enumerate:
                $lhs
                ...':
    let [n, ...] = List.iota([lhs, ...].length())
    'def $lhs = $n
     ...'
> enumerate:
    a
    b
    c
> b
1

definition

defn.sequence_macro 'defined_name pattern ...

pattern

...':

option; ...

body

...

Similar to defn.macro, but defines a macro for a definition context that is matched against all of the remaining groups in the context, so the pattern is a multi-group pattern.

The macro result is two values: a sequence of groups to splice in place of the sequence-macro use, and a sequence of groups that represent the tail of the definition context that was not consumed.

> defn.sequence_macro 'reverse_defns
                       $defn1
                       $defn2
                       $tail
                       ...':
    values('$defn2; $defn1', '$tail; ...')
> reverse_defns
  def seq_x = seq_y+1
  def seq_y = 10
  seq_x
11

syntax class

syntax_class defn_meta.Group:

kind: ~group

Provided as meta.

Syntax class that matches only groups that start with an identifier that is bound as a definition form.

Unlike expr_meta.Parsed, defn_meta.Group does not parse the definition form, because the form normally needs to be parsed within a definition context. This syntax class can be used to distinguish definitions from other forms that need to be treated differently in some context.

syntax class

syntax_class defn_meta.SequenceStartGroup:

kind: ~group

Provided as meta.

Syntax class that matches only groups that starts with an identifier that is bound as a definition-sequence form.

function

fun defn_meta.pack_s_exp(tree :: Any) :: Syntax

Provided as meta.

Similar to expr_meta.pack_s_exp, but for definitions.

1	Notation and Conventions
2	Implicits and Context
3	Names and Definitions
4	Functions and Operators
5	Comparison and Branching
6	Objects and Annotations
7	Basic Data
8	Collections and Iteration
9	Object Protocols
10	Higher-Order Control
11	Code as Data
12	String Formatting and Matching
13	Input and Output
14	Operating System
15	Threads and Concurrency
16	Runtime System
17	Meta and Macros

17.1	Meta Definitions and Expressions
17.2	Spaces
17.3	Namespace Space
17.4	Definition Macros
17.5	Declaration Macros
17.6	Expression Macros
17.7	Assignment Macros
17.8	Binding Macros
17.9	Annotation Macros
17.10	Static Information
17.11	Dot Providers
17.12	Repetition Macros
17.13	Operator Orders
17.14	Form-Specific Macros
17.15	Syntax Objects in Macros
17.16	Syntax Parameters
17.17	Syntax Object Maps
17.18	Documentation Metadata