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

src/macros.x

Compile-time macro definitions and expression expansion.

Functions

Functions

macro_library_defer

void macro_library_defer(void)

Records that this process builds the shared compile-time parent between units rather than before the first one. A unit that needs a session while the parent is still pending raises <lisp-late>; its driver must catch that, call Frontend.preload_macro_libraries, and translate the same unit again.

Source: src/macros.x:1114

macro_library_pending

int macro_library_pending(void)

Answers whether a unit started now may still raise <lisp-late>.

Source: src/macros.x:1119

Compiler

Compiler.evaluate_declaration_effect

void Compiler.evaluate_declaration_effect( Compiler compiler, String form, Token invocation)

Evaluates a queued source Lisp form with its original diagnostic site.

Source: src/macros.x:1412

Compiler.evaluate_declaration_recipe

Var Compiler.evaluate_declaration_recipe( Compiler compiler, Atom callback, List arguments)

Evaluates a declaration recipe after its owning source is collected. The callback is a Lisp name and arguments are retained canonical values.

Source: src/macros.x:1668

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:1745

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:1710

Compiler.expand_macro_invocation_node

List Compiler.expand_macro_invocation_node( Compiler c, 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:2833

Compiler.install_builtin_macros

void Compiler.install_builtin_macros(Compiler compiler)

Installs the compiler-shipped source macros into compiler once.

Source: src/macros.x:113

Compiler.install_meta_function

void Compiler.install_meta_function(Compiler c, List fn, Token marker)

Installs a meta function in the macro session under its own name. A function whose two forms agree is foldable. One that reaches a compiler operation has no runtime form, and neither do its callers. File-scope state is refused because the compile-time session cannot read the program’s variables. Lowering failures are reported at the marker.

Source: src/macros.x:1426

Compiler.keyword_form_is_definition

int Compiler.keyword_form_is_definition(Compiler c)

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

Source: src/macros.x:568

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:1500

Compiler.local_macro_form_is_definition

int Compiler.local_macro_form_is_definition(Compiler c)

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

Source: src/macros.x:560

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:548

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:1790

Compiler.macro_invocation_needs_shallow_expansion

int Compiler.macro_invocation_needs_shallow_expansion(Compiler c)

Returns whether the macro invocation at the cursor 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:659

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:2810

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:2166

Compiler.macro_starts_target_at

int Compiler.macro_starts_target_at(Compiler c, AstPos position)

Returns whether the parser claims the macro invocation at the cursor for position. A bare keyword alias is claimed only where its result fits. This query does not consume tokens.

Source: src/macros.x:710

Compiler.macro_targets_unit

int Compiler.macro_targets_unit(Compiler c)

Reports whether the macro invocation at the cursor produces file-scope syntax, directly or through the target it decorates. A script unit keeps such an invocation at file scope. This query does not consume tokens.

Source: src/macros.x:2635

Compiler.open_macro_library

Lisp Compiler.open_macro_library(Compiler compiler)

Builds the shared compile-time session, leaving it open for the caller to fill and then publish. Returns the session, or null when this home cannot preload, in which case every unit falls back to its own load, which reports against the unit that needed it.

The session is not published until Compiler.publish_macro_library, so a unit opened in between still builds its own.

Source: src/macros.x:1047

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:2601

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:2300

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:1521

Compiler.parse_macro_lisp_shallow

void Compiler.parse_macro_lisp_shallow(Compiler compiler)

Imports immediate dependencies and queues other source Lisp effects. Declaration projection forces preceding effects exactly once; otherwise full parsing keeps the ordinary source-order evaluation.

Source: src/macros.x:1462

Compiler.parse_macro_lisp_top_level

List 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. Returns a %(seq ...) of the runtime meta definitions a macro import contributed, or NULL when the import declared no meta function at all. The consuming unit retains them and emits the ones it reaches. An import whose meta functions are all compile-time only answers an empty seq, because the next pass still has to read it to install them.

Source: src/macros.x:1390

Compiler.parse_source_lisp

List Compiler.parse_source_lisp(Compiler compiler)

Retains one source Lisp form as text without evaluating it again.

Source: src/macros.x:1406

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:2095

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:2579

Compiler.publish_macro_library

void Compiler.publish_macro_library(Compiler compiler, Lisp shared)

Prepares and freezes the shared session and makes it every unit’s parent. shared must be the session Compiler.open_macro_library returned.

Source: src/macros.x:1074

Compiler.shared_definition

int Compiler.shared_definition(Compiler compiler, String key)

Records or reports one compile-time definition of the shared session. The answer is whether that session already holds key, which is a file and a name, and while the session is being filled the key is recorded as well. A reader that reads the same file again therefore installs nothing, whether it is a later unit or the filling itself reaching the file twice: the definition it would install is the one it already has.

Source: src/macros.x:1099

Compiler.shared_definitions

Map Compiler.shared_definitions(Compiler compiler)

Returns the published definition keys, or null before publication. The borrowed map is the shared session’s source identity table.

Source: src/macros.x:1124

Compiler.skip_macro_invocation

void Compiler.skip_macro_invocation(Compiler c)

Consumes a macro invocation name and its balanced argument list. The invocation terminator or following decorator target remains current.

Source: src/macros.x:634

Compiler.skip_named_type_declaration

int Compiler.skip_named_type_declaration(Compiler c)

Consumes a NamedType target already projected by owning-source collection. CPP scanning does not produce the declaration or parse its fields again.

Source: src/macros.x:2645

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:3027

Compiler.try_parse_macro_slot

List Compiler.try_parse_macro_slot(Compiler c, 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:2183

Compiler.try_parse_macro_target_at

List Compiler.try_parse_macro_target_at(Compiler c, AstPos position)

Parses a direct or keyword-alias macro at the requested syntax position. Returns NULL without consuming a macro hole or an invocation that macro_starts_target_at does not claim; template parsing returns a deferred (seq (macro-invoke ...)), and ordinary parsing returns the bound expansion.

Source: src/macros.x:3175

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.