Provisional API: This reference documents current compiler behavior. Compatibility is not yet promised.

src/macros.x

Compile-time macro definitions and expression expansion.

Functions

Compiler

Compiler.evaluate_macro_rows

List Compiler.evaluate_macro_rows(Compiler compiler, Var value)

Evaluates a macro slot and returns its syntax as a row sequence. (seq ...) contributes its children; every other result contributes one row.

Source: src/macros.x:1311

Compiler.evaluate_macro_slot

Var Compiler.evaluate_macro_slot(Compiler compiler, Var value)

Evaluates an active template’s (macro-slot ...) value. Non-slots and slots outside an expansion are returned unchanged. A splice slot’s List result is wrapped as (seq ...) for its syntax position.

Source: src/macros.x:1266

Compiler.expand_macro_invocation_node

List Compiler.expand_macro_invocation_node( Compiler compiler, Var stored, List arguments, Token invocation, AstPos position)

Expands canonical macro capture rows and binds the result at position. stored is a macrodef or visible macro name. The active expansion stack supplies Lisp bindings, source location, and recursion checks; the definition’s fresh rows allocate invocation-local names. This method does not begin a semantic transaction.

Source: src/macros.x:2438

Compiler.install_builtin_macros

void Compiler.install_builtin_macros(Compiler compiler)

Installs the compiler-shipped source macros into compiler once.

Source: src/macros.x:97

Compiler.keyword_alias_needs_shallow_expansion

int Compiler.keyword_alias_needs_shallow_expansion(Compiler compiler)

Returns whether the current keyword alias needs shallow expansion. A visible invocation qualifies when its captured Unit definition is imported, or when its local template contains protocol or adoption rows.

Source: src/macros.x:2242

Compiler.keyword_alias_starts_target_at

int Compiler.keyword_alias_starts_target_at( Compiler compiler, AstPos position)

Returns whether the parser should claim the current alias at position. An argument-taking invocation may be claimed before result-kind validation so target parsing can report a wrong-position diagnostic. Bare forms must already fit the position. This query does not consume tokens.

Source: src/macros.x:2234

Compiler.keyword_form_is_definition

int Compiler.keyword_form_is_definition(Compiler compiler)

Returns whether the current tokens begin a keyword NAME $macro alias. This query does not consume tokens.

Source: src/macros.x:522

Compiler.lift_macro_lisp_expression

List Compiler.lift_macro_lisp_expression( Compiler compiler, Var value, Token invocation)

Converts a compile-time Lisp value into a bound expression AST. Integers, Strings, Symbols, compiler-issued identifiers, and nonempty syntax Lists are accepted; invocation locates an unsupported result.

Source: src/macros.x:1082

Compiler.local_macro_form_is_definition

int Compiler.local_macro_form_is_definition(Compiler compiler)

Returns whether the current tokens begin a local macro definition. This query does not consume tokens.

Source: src/macros.x:511

Compiler.macro_form_is_definition

int Compiler.macro_form_is_definition(Compiler compiler)

Returns whether the current tokens have macro-definition introducer form. This query does not consume tokens.

Source: src/macros.x:502

Compiler.macro_introduced_name

List Compiler.macro_introduced_name(Compiler compiler, String spelling)

Returns the definition-local binding identity for spelling. Repeated uses share one identity while the template is parsed. An active macro-definition locals map is required.

Source: src/macros.x:1357

Compiler.macro_invocation_needs_shallow_expansion

int Compiler.macro_invocation_needs_shallow_expansion(Compiler compiler)

Returns whether the current direct invocation needs shallow expansion. Every imported Unit macro qualifies. A local Unit macro qualifies only when its template contains protocol or adoption rows that collection must retain.

Source: src/macros.x:600

Compiler.macro_invocation_site

Token Compiler.macro_invocation_site(Compiler compiler, Var site)

Resolves a stored macro invocation marker to its source token. Nested template markers use the active expansion’s invocation; unresolved markers return NULL.

Source: src/macros.x:2414

Compiler.macro_lisp_starts_declaration

int Compiler.macro_lisp_starts_declaration(Compiler compiler)

Returns whether tokens after the current Lisp form continue a declaration. The balanced form and following trivia are inspected without moving the compiler cursor.

Source: src/macros.x:1731

Compiler.macro_starts_target_at

int Compiler.macro_starts_target_at(Compiler compiler, AstPos position)

Returns whether the current direct macro can start at position. The current definition and any decorator target kind determine the result; this query does not consume tokens.

Source: src/macros.x:632

Compiler.parse_keyword_definition

void Compiler.parse_keyword_definition(Compiler c)

Parses and installs one source-local keyword alias. The named macro must already be visible; the alias captures that definition and consumes its terminating semicolon.

Source: src/macros.x:2169

Compiler.parse_macro_definition

List Compiler.parse_macro_definition(Compiler c)

Parses the macro definition at the current token into a macrodef List. A source-level definition is published immediately; a definition inside a template remains syntax for later binding at its expansion site.

Source: src/macros.x:1857

Compiler.parse_macro_lisp_expression

List Compiler.parse_macro_lisp_expression(Compiler compiler)

Parses a compile-time Lisp form in an expression position. Macro-definition parsing records a deferred slot; ordinary parsing evaluates the form in the translation unit’s Lisp session and lifts it.

Source: src/macros.x:1103

Compiler.parse_macro_lisp_shallow

void Compiler.parse_macro_lisp_shallow(Compiler compiler)

Processes a top-level Lisp form during shallow collection. Imports run so their definitions and Lisp effects are available; every other form is only consumed.

Source: src/macros.x:1048

Compiler.parse_macro_lisp_top_level

void Compiler.parse_macro_lisp_top_level(Compiler compiler)

Consumes and evaluates one top-level compile-time Lisp form. $(import ...) loads a tracked .xlisp or .xmacro dependency; other results are discarded in the translation unit’s Lisp session.

Source: src/macros.x:1031

Compiler.peek_macro_hole

List Compiler.peek_macro_hole(Compiler compiler)

Returns the registered hole descriptor at the current $NAME. Returns NULL without consuming tokens when the spelling is not a hole.

Source: src/macros.x:1654

Compiler.publish_macro_definition_node

List Compiler.publish_macro_definition_node(Compiler compiler, List node)

Publishes a canonical macrodef in source order and returns node. A later definition with the same name affects only later invocations.

Source: src/macros.x:2127

Compiler.skip_keyword_alias

void Compiler.skip_keyword_alias(Compiler compiler)

Consumes the current keyword alias and any required argument list. Its terminator or following decorator target remains current.

Source: src/macros.x:2251

Compiler.skip_macro_invocation

void Compiler.skip_macro_invocation(Compiler compiler)

Consumes a direct macro name and its balanced argument list. The invocation terminator remains current for the shallow parser.

Source: src/macros.x:545

Compiler.skip_macro_lisp

void Compiler.skip_macro_lisp(Compiler compiler)

Consumes one balanced compile-time Lisp form without evaluating it.

Source: src/macros.x:914

Compiler.try_parse_macro_expression

List Compiler.try_parse_macro_expression(Compiler c)

Parses and resolves a direct or keyword-alias expression macro. Returns NULL without consuming an identifier that is not an applicable alias; a direct $ invocation must resolve to a visible expression form.

Source: src/macros.x:2613

Compiler.try_parse_macro_slot

List Compiler.try_parse_macro_slot(Compiler compiler, Symbol role)

Parses a macro hole or Lisp slot for role while reading a template. Returns role-shaped syntax containing (macro-bind ...) or (macro-slot ...), or NULL when ordinary grammar owns the current tokens; successful parsing advances the cursor.

Source: src/macros.x:1742

Compiler.try_parse_macro_target_at

List Compiler.try_parse_macro_target_at(Compiler compiler, AstPos position)

Parses a direct or keyword-alias macro at the requested syntax position. Returns NULL without consuming a macro hole or inapplicable identifier; template parsing returns a deferred (seq (macro-invoke ...)), and ordinary parsing returns the bound expansion.

Source: src/macros.x:2760

Design notes

Macro definitions are compiler-only records. Their patterns and replacements are canonical Lists. Expansion uses the same List operations that parsed source uses.