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

src/macros/macros.x

Source macros and the compile-time Lisp they run.

Functions

Functions

x2c_template_call

List x2c_template_call(Var stored, List values)

Returns the syntax that invokes the template stored, a macro name spelled as a String or a local definition, with values: what a template call in a staged meta body evaluates to.

Source: src/macros/templates.x:261

Compiler

Compiler.add_library_dependencies

void Compiler.add_library_dependencies(Compiler c)

Records the compile-time Lisp libraries as dependencies of c, as each use of its session does.

Source: src/macros/lisp.x:410

Compiler.after_hole

Token Compiler.after_hole(Compiler c)

Returns the token after the named or expression hole at the cursor. Consumes neither its $ or @ prefix nor its optional braces.

Source: src/macros/definitions/slots.x:109

Compiler.applying_shipped

int Compiler.applying_shipped(Compiler c)

Whether the rule whose meta function now runs is shipped, so that the names it calls resolve to the copies the compiler links.

Source: src/macros/rewrites.x:443

Compiler.bind_code_value

List Compiler.bind_code_value( Compiler c, List carrier, Symbol position, Type return_type)

Binds a code-value carrier that a meta call returned outside a macro value application as an application binds it, under a transaction that also covers its effects.

Source: src/macros/values.x:340

Compiler.bind_macro_lisp_statement

List Compiler.bind_macro_lisp_statement( Compiler c, List value, Symbol context)

Binds a compile-time Lisp code value returned to a statement at context.

Source: src/macros/lisp.x:153

Compiler.bind_meta_operation

void Compiler.bind_meta_operation(Lisp lisp, String name, Var function)

Binds function, the operation lib/meta.x declares as name, under its Lisp name in lisp. A definition the compile-time libraries already give that name wins, because it adapts the arguments.

Source: src/macros/lisp.x:602

Compiler.capture_macro_value

List Compiler.capture_macro_value(Compiler c, List definition)

Returns an anonymous macro definition as a Macro value. Macro values the body applies are captured where the literal is written, so a later application applies the same children.

Source: src/macros/values.x:217

Compiler.ensure_macro_lisp

void Compiler.ensure_macro_lisp(Compiler c)

Opens the unit’s compile-time Lisp session when it has none. An Each use records the library files as dependencies, and a session loads them once.

Source: src/macros/lisp.x:13

Compiler.evaluate_declaration_effect

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

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

Source: src/macros/lisp.x:103

Compiler.evaluate_declaration_recipe

Var Compiler.evaluate_declaration_recipe( Compiler c, 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/templates.x:243

Compiler.evaluate_macro_rows

List Compiler.evaluate_macro_rows(Compiler c, 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/templates.x:91

Compiler.evaluate_macro_slot

Var Compiler.evaluate_macro_slot(Compiler c, Var value)

Evaluates an active template’s (macro-slot ...) value, or a pending Macro value application into the invocation that expands it. 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/templates.x:32

Compiler.evaluate_meta_value

Var Compiler.evaluate_meta_value( Compiler c, List expression, Token site, int slot)

Evaluates the explicit meta call expression at site with the active expansion’s captures visible to the SDK. A nonzero slot marks a template slot, which reports a call the project meta build leaves.

Source: src/macros/templates.x:130

Compiler.expand_macro_invocation_node

List Compiler.expand_macro_invocation_node( Compiler c, Var stored, List arguments, Token invocation, Symbol 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/expansion.x:22

Compiler.has_rewrites

int Compiler.has_rewrites(Compiler c, Symbol point, Var kind)

Tests one operation’s registry without invoking a translator.

Source: src/macros/rewrites.x:230

Compiler.inherit_library_comptime

void Compiler.inherit_library_comptime(Compiler c)

Marks the shared session’s compile-time-only definitions in a fresh compiler pass, which reads them without defining them.

Source: src/macros/lisp.x:465

Compiler.inherits_import

int Compiler.inherits_import(String path)

Whether the shared session evaluated the file at path. A unit that is that file, as when a library is linted, inherits its Lisp forms.

Source: src/macros/lisp.x:448

Compiler.install_builtin_macros

void Compiler.install_builtin_macros(Compiler c)

Installs the compiler-shipped source macros into c once.

Source: src/macros/lisp.x:513

Compiler.install_compile_time_effects

void Compiler.install_compile_time_effects(Compiler c, List rows)

Installs included compile-time definitions in their source order. Keyword aliases retain the definition visible when their source declared them, even if a later macro definition uses the same name.

Source: src/macros/invocations/recognition.x:41

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/invocations/recognition.x:105

Compiler.land_quotation

List Compiler.land_quotation( Compiler c, List fresh, Var syntax, Symbol position, Type return_type)

Binds quoted syntax with its fresh rows at position, as the expansion of its quotation would.

Source: src/macros/templates.x:433

Compiler.library_filling

int Compiler.library_filling(void)

Answers whether the shared compile-time session is still being filled, before lib/meta.x has defined the syntax builders.

Source: src/macros/lisp.x:472

Compiler.lift_macro_lisp_expression

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

Converts a compile-time Lisp value into a bound expression AST. Scalars, immutable values, representable Array/Map roots, compiler-issued identifiers, and nonempty code Lists are accepted; invocation locates an unsupported result.

Source: src/macros/lisp.x:139

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/invocations/recognition.x:95

Compiler.lower_replacement

List Compiler.lower_replacement(Compiler c, List replacement, List source)

Lowers replacement, which Compiler.rewrite_lowered bound for the lowered statement source, and keeps each part of source it holds as it is, so no statement rule is offered that part again.

Source: src/macros/rewrites.x:255

Compiler.lower_rewrite

List Compiler.lower_rewrite( Compiler c, Symbol point, Var kind, List source, Symbol position, Type expected, Token site)

Binds and lowers a replacement while its rule remains active. The source expressions the replacement holds lower outside the rule, so a nested use of the rule applies again. A statement replacement, or a lowered one, also lowers the statements its source held outside the rule, and lowers once, so a new statement it writes stays outside the rule. Code a shipped rule’s replacement writes, such as the support call an interpolated String or a collection literal lowers to, is not source, so only shipped rules see it. An expression retains the result type already established for its parent. A replacement whose template and slot signatures an earlier use in the unit prepared lowers only its captured values.

Source: src/macros/rewrites.x:286

Compiler.macro_form_is_definition

int Compiler.macro_form_is_definition(Compiler c)

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

Source: src/macros/invocations/recognition.x:81

Compiler.macro_introduced_name

List Compiler.macro_introduced_name(Compiler c, String spelling)

Returns the current declaration’s definition-local identity. An active macro-definition locals map is required.

Source: src/macros/definitions/templates.x:264

Compiler.macro_invocation_collection

Symbol Compiler.macro_invocation_collection(Compiler c)

Returns how collection treats the macro invocation at the cursor. <required> covers every file-scope Unit macro, declaration-unit macro, named-type decorator, and local Unit macro whose template contains protocol or adoption rows. <tried> covers Unit decorators and other local Unit macros. Other invocations return zero.

Source: src/macros/invocations/recognition.x:358

Compiler.macro_invocation_site

Token Compiler.macro_invocation_site(Compiler c, 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/expansion.x:235

Compiler.macro_lisp_starts_declaration

int Compiler.macro_lisp_starts_declaration(Compiler c)

Returns whether tokens after a Lisp form or explicit meta call continue a declaration. The balanced argument group is inspected without moving the compiler cursor; a visible source macro retains its own grammar.

Source: src/macros/definitions/slots.x:181

Compiler.macro_pattern_at

Token Compiler.macro_pattern_at( Compiler c, Token at, String &spelling, Var &stored)

Returns the ( after a visible macro’s $NAME at at, storing its spelling and definition, or NULL. The cursor does not move.

Source: src/macros/values.x:106

Compiler.macro_starts_target_at

int Compiler.macro_starts_target_at(Compiler c, Symbol 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/invocations/recognition.x:172

Compiler.macro_tag_name

List Compiler.macro_tag_name( Compiler c, Symbol kind, String name, int definition)

Returns a template’s local binding for tag name of kind, or NULL when it names a visible public tag. A tag the template defines or declares is a template local, apart from ordinary names of the same spelling. A tag it only references keeps its public spelling unless the template later defines or declares it.

Source: src/macros/definitions/templates.x:277

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/invocations/recognition.x:402

Compiler.macro_value_literal

List Compiler.macro_value_literal(Compiler c, List value)

Returns the literal expression that carries value, a macro definition or one of its references, as run-time data.

Source: src/macros/values.x:12

Compiler.marked_rewrite

List Compiler.marked_rewrite( Compiler c, Type aggregate, List source, Token site)

Matches the member rules registered for each field keyword that aggregate declares a field with, as Compiler.rewrite matches those keyed by a receiver type.

Source: src/macros/rewrites.x:216

Compiler.open_macro_library

Lisp Compiler.open_macro_library(Compiler c)

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/lisp.x:358

Compiler.parse_keyword_definition

Atom 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. Returns the alias.

Source: src/macros/invocations/recognition.x:117

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/definitions/reading.x:20

Compiler.parse_macro_lisp_expression

List Compiler.parse_macro_lisp_expression(Compiler c)

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/lisp.x:124

Compiler.parse_macro_lisp_shallow

void Compiler.parse_macro_lisp_shallow(Compiler c)

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

Source: src/macros/lisp.x:69

Compiler.parse_macro_lisp_top_level

List Compiler.parse_macro_lisp_top_level(Compiler c)

Evaluates one source Lisp form or imports an .xlisp dependency.

Source: src/macros/lisp.x:52

Compiler.parse_macro_quotation

List Compiler.parse_macro_quotation(Compiler c)

Parses a quotation at $! into the code it builds from the locals its body names.

Source: src/macros/definitions/quotations.x:19

Compiler.peek_macro_hole

List Compiler.peek_macro_hole(Compiler c)

Returns the registered hole descriptor for a named or expression hole. $NAME and ${expression} insert one value; @NAME and @{expression} splice a sequence. Returns NULL without consuming a non-hole spelling.

Source: src/macros/definitions/slots.x:95

Compiler.place

void Compiler.place(Compiler c, List where, Var code)

Places code where where says, under the active expansion’s transaction: (after-statement) after the enclosing block item or initialized declarator; (block-exit) on every exit from the enclosing block from that point on, as a defer placed after it; (function-entry) at the entry of the enclosing function, at parse or transform time, in placement order before its first statement; (unit-support) among the unit’s support declarations, once per KEY with (unit-support KEY); or (unit-init) in the unit’s file initialization, in AREA with (unit-init AREA).

Source: src/macros/values.x:305

Compiler.publish_macro_definition_node

List Compiler.publish_macro_definition_node(Compiler c, 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/invocations/recognition.x:14

Compiler.publish_macro_library

void Compiler.publish_macro_library(Compiler c, 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/lisp.x:430

Compiler.rebound

void Compiler.rebound(Compiler c, Var source, List bound)

Records that binding built the statement bound again from source, a value the active lowering watches, so it watches bound as well. A statement without an origin, such as an unbraced body, keeps nothing else that identifies it when a binder it uses binds again.

Source: src/macros/rewrites.x:694

Compiler.rebuild_expression

List Compiler.rebuild_expression(Compiler c, Type type, List application)

Rebuilds an expression from a pending Macro value application, preserving its established root type, child stage, and source wrappers. Binding, capture collection, hygiene, and effects do not run, and a statement expression’s template-origin wrappers are omitted.

Source: src/macros/templates.x:347

Compiler.rebuild_function

List Compiler.rebuild_function(Compiler c, List target, List application)

Rebuilds a bound function through a Function decorator without binding it again. The template keeps the target’s return type and declarator.

Source: src/macros/templates.x:369

Compiler.rebuild_statement

List Compiler.rebuild_statement(Compiler c, List application)

Rebuilds a statement template as a canonical unbraced seq. Bound children keep their identities and origins; template-origin wrappers are omitted because this path does not open an invocation.

Source: src/macros/templates.x:355

Compiler.rebuild_unit_function

List Compiler.rebuild_unit_function(Compiler c, List application)

Constructs a fresh function from a Unit template after lowering. The caller supplies its bound name and lowered children; binding does not run.

Source: src/macros/templates.x:361

Compiler.record_compile_time_effect

void Compiler.record_compile_time_effect( Compiler c, List row, Token start)

Records a public source effect where its completed definition stands.

Source: src/macros/invocations/recognition.x:24

Compiler.record_comptime

void Compiler.record_comptime(Compiler c, String name)

Records that name is compile-time only in c, and in the shared session when it is being filled.

Source: src/macros/lisp.x:456

Compiler.report_lisp_failure

void Compiler.report_lisp_failure( Compiler c, Token invocation, List error, String source)

Reports that the compile-time Lisp source failed with error at invocation.

Source: src/macros/diagnostics.x:357

Compiler.reset_macro_library

void Compiler.reset_macro_library(void)

Ends the shared compile-time library before its build-target Context is reclaimed. A later target creates a fresh session in its own Context.

Source: src/macros/lisp.x:629

Compiler.rewrite

List Compiler.rewrite( Compiler c, Symbol point, Var kind, List source, Symbol position, Type expected, Token site)

Matches registered patterns for one operation, then binds the first replacement. A translator declines with void, null, or its input itself. Active rules cannot re-enter. A statement of the same kind that a statement replacement writes or copies, such as its source, takes the rules after the one that replaced it.

Source: src/macros/rewrites.x:238

Compiler.rewrite_lowered

List Compiler.rewrite_lowered( Compiler c, Symbol point, Var kind, List source, Symbol position, Type expected, Token site)

Matches registered patterns for the statement source, which the transform has lowered, then binds the first replacement as Compiler.rewrite does. Binding keeps the source, and each part of it the replacement holds, as lowered.

Source: src/macros/rewrites.x:247

Compiler.rewrite_written

List Compiler.rewrite_written( Compiler c, Symbol kind, List source, Type expected)

Binds the replacement a shipped rule gives the lowered statement source of kind, which the kernel wrote while lowering, as Compiler.rewrite_lowered does. A statement the kernel writes is not source, so no program rule sees it.

Source: src/macros/rewrites.x:267

Compiler.shared_definitions

Map Compiler.shared_definitions(Compiler c)

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

Source: src/macros/lisp.x:477

Compiler.shares_meta_definition

int Compiler.shares_meta_definition(Compiler c, String name)

Answers whether the published shared session already holds the definition of name from this file, which a unit reading the file again leaves alone.

Source: src/macros/lisp.x:485

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/invocations/recognition.x:378

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/invocations/recognition.x:389

Compiler.source_path

String Compiler.source_path(Compiler c, String file)

Returns the canonical path of the source file. A relative name that is not a file resolves against the home.

Source: src/macros/lisp.x:292

Compiler.take_code_value

int Compiler.take_code_value( Compiler c, Var input, Var &value, int &retained)

Consumes a (code-value STAGE CODE EFFECTS) carrier a producer returned into a macro value application, or that Compiler.bind_code_value binds as one. Effects are applied in order under the application’s transaction, and their tokens are replaced in the code. retained reports a bound or lowered stage, which ordinary binding leaves untouched. Lowered code is not searched for a leftover binder. Returns 0 for any other value.

Source: src/macros/values.x:255

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/invocations/expressions.x:15

Compiler.try_parse_macro_member

List Compiler.try_parse_macro_member(Compiler c)

Parses a member name in a template. A singular Name hole there supplies the spelling it captured, without hygienic renaming.

Source: src/macros/definitions/slots.x:197

Compiler.try_parse_macro_pattern

List Compiler.try_parse_macro_pattern(Compiler c)

Parses case NAME(?a, *b) where NAME selects a macro, as $name or as a Macro variable, into the pattern expression that recognizes code the macro builds. Returns NULL without consuming tokens for any other case.

Source: src/macros/values.x:40

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/definitions/slots.x:14

Compiler.try_parse_macro_subpattern

List Compiler.try_parse_macro_subpattern(Compiler c, int content)

Parses $NAME(P, ...) in a pattern, where each argument is a pattern, into the pattern for code NAME builds with each argument pattern in its hole. It matches the shelled expression or its bare content; content selects the content alone, for a position whose pattern already writes the (expr TYPE ...) shell. Returns NULL without consuming tokens when no macro NAME is visible.

Source: src/macros/values.x:142

Compiler.try_parse_macro_target_at

List Compiler.try_parse_macro_target_at(Compiler c, Symbol 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/invocations/targets.x:54

Compiler.watched_step

Ast Compiler.watched_step(Compiler c, Ast ast)

Lowers ast when it is a value the active lowering watches; NULL otherwise. A preparing watch also records what lowering produced. A value that an enclosing replacement’s source held as well lowers outside that replacement’s rule too, and that replacement still watches its own values within it.

Source: src/macros/rewrites.x:707

Compiler.written_support

List Compiler.written_support(Compiler c, List bound)

The bound file-scope code bound that the rule now writing gives, written as the kernel’s when that rule is shipped. A rule writes while its meta function runs, until a rule it reaches binds, and while its replacement binds and lowers. What a program writes, or a placement outside any rule, is source.

Source: src/macros/rewrites.x:434

Design notes

This module owns macro expansion. Expansion fills a definition’s template from an invocation’s captures and binds the result through the operations that bind parsed source. A definition is a compiler-only macrodef List: its holes, a Match pattern over an invocation’s capture rows, and a template of the binders that pattern captures. Template slots and $(...) forms run in the unit’s compile-time Lisp session, a child of the shared library session filled once per target.