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

src/compiler.x

Core x2c compiler state and operations.

Functions

Compiler

Compiler._at_function_arrow

int Compiler._at_function_arrow(Compiler compiler)

Reports whether the current two tokens are =>.

Source: src/compiler.x:522

Compiler._skip_shallow_expression

void Compiler._skip_shallow_expression( Compiler compiler, int stop_at_comma)

Skips a balanced shallow expression without consuming its terminator. A top-level comma also terminates the expression when stop_at_comma is nonzero.

Source: src/compiler.x:529

Compiler.add_early

void Compiler.add_early(Compiler compiler, List decl)

Appends a generated declaration to the early-declaration queue.

Source: src/compiler.x:1005

Compiler.add_early_init

void Compiler.add_early_init(Compiler compiler, List stmt)

Appends a statement to early file initialization order.

Source: src/compiler.x:1015

Compiler.add_late_init

void Compiler.add_late_init(Compiler compiler, List stmt)

Appends a statement to late file initialization order.

Source: src/compiler.x:1025

Compiler.add_mid_init

void Compiler.add_mid_init(Compiler compiler, List stmt)

Appends a statement to middle file initialization order.

Source: src/compiler.x:1020

Compiler.add_protocol_init

void Compiler.add_protocol_init(Compiler compiler, List stmt)

Appends a statement to protocol initialization order.

Source: src/compiler.x:1010

Compiler.add_translation_dependency

void Compiler.add_translation_dependency(Compiler compiler, String path)

Records a path dependency not embedded in generated C.

Source: src/compiler.x:134

Compiler.anchor_origin

List Compiler.anchor_origin(Compiler compiler, List node, Token token)

Wraps a parsed node in the source location of its opening token.

A null node remains null. Macro construction uses its active m-origin marker; otherwise a node without a token remains unwrapped.

Source: src/compiler.x:483

Compiler.begin_semantic_transaction

SymTxn Compiler.begin_semantic_transaction(Compiler c)

Begins a reversible transaction over the current semantic scope.

The transaction stages the current scope maps, file-static and binding facts, binding and generated-name counters, and initializer names. It does not snapshot parser position or other compiler state.

Source: src/compiler.x:1101

Compiler.cache

List Compiler.cache(Compiler c, List key)

Interns a constant key and returns its stable (cache id) reference.

Source: src/compiler.x:845

Compiler.cache_cons_cell

List Compiler.cache_cons_cell(Compiler compiler, List head, List tail)

Caches a cons cell when both parts have immutable cache forms.

Returns NULL when runtime literals are required or either part cannot be represented by the immutable cache graph.

Source: src/compiler.x:858

Compiler.cache_literal_list

List Compiler.cache_literal_list(Compiler compiler, List values)

Returns a runtime List expression for cached compiler-owned syntax.

values may contain nested Lists, Strings, and Symbols.

Source: src/compiler.x:907

Compiler.define_match_binders

void Compiler.define_match_binders(Compiler compiler, List pattern)

Defines a typed Match pattern’s definite binders in the current scope.

Source: src/compiler.x:996

Compiler.emitted_binding_name

String Compiler.emitted_binding_name(Compiler compiler, List binding)

Returns a binding’s selected emitted spelling.

A binding without an explicit emission rename uses its identity spelling.

Source: src/compiler.x:330

Compiler.expect

Symbol Compiler.expect(Compiler c, Symbol type)

Requires and consumes the current token type.

A mismatch reports a parse diagnostic. An active recovery boundary raises <malformed>; without one, diagnostic reporting exits.

Source: src/compiler.x:400

Compiler.free_lisp

void Compiler.free_lisp(Compiler c)

Unregisters a compiler and destroys its owned Lisp session, if any.

A borrowed session is left alive. Owned sessions not freed here are destroyed by the process shutdown hook. This is final compiler cleanup: it clears the diagnostic store and the compiler must not be reused.

Source: src/compiler.x:196

Compiler.fresh_name

String Compiler.fresh_name(Compiler compiler, String stem)

Allocates the next compiler-private C spelling for stem.

Related compilers increment the same per-stem counter.

Source: src/compiler.x:317

Compiler.full_parse

List Compiler.full_parse(Compiler c, Map globs)

Parses and types the positioned source against globs.

The result is a source-ordered top-level AST. This resets per-parse origins, macro state, protocol resolution, and recoverable diagnostics.

Source: src/compiler.x:759

Compiler.gensym

List Compiler.gensym(Compiler compiler)

Returns a fresh semantic identity for an anonymous aggregate.

Source: src/compiler.x:2202

Compiler.imported_providers

List Compiler.imported_providers(Compiler c, String name)

Returns sorted imported packages that publish name.

Package-owned methods use <package>__<Type>_<member> internally while consumers retain the spelling from the package header. Sorting keeps ambiguity diagnostics deterministic.

Source: src/compiler.x:1601

Compiler.imported_spelling

String Compiler.imported_spelling(Compiler compiler, String name)

Returns an unambiguous imported spelling for name, or NULL.

Source: src/compiler.x:1613

Compiler.leading_preproc

List Compiler.leading_preproc(Compiler compiler)

Returns source-ordered preprocessor nodes in the preceding trivia.

Spaces and comments remain trivia rather than becoming AST nodes.

Source: src/compiler.x:693

Compiler.macro_definition_locals

Map Compiler.macro_definition_locals(Compiler compiler)

Returns the active macro definition’s borrowed local map, or NULL.

Source: src/compiler.x:308

Compiler.match_pattern_binders

List Compiler.match_pattern_binders( Compiler compiler, List pattern, List *possible)

Returns definite binders from a typed Match pattern AST.

When possible is non-null, stores every binder appearing on any path.

Source: src/compiler.x:985

Compiler.match_pattern_head_symbol

Symbol Compiler.match_pattern_head_symbol(Compiler compiler, List pattern)

Returns a typed Match pattern’s fixed literal head symbol, or zero.

A binder, guard, non-list value, or computed head has no fixed symbol. Other pattern elements may remain dynamic because a literal head alone constrains the first input element.

Source: src/compiler.x:971

Compiler.match_pattern_is_static

int Compiler.match_pattern_is_static(Compiler compiler, List pattern)

Reports whether a typed Match pattern has a fully static value graph.

Source: src/compiler.x:961

Compiler.merge_translation_dependencies

void Compiler.merge_translation_dependencies( Compiler compiler, Map dependencies)

Merges another translation’s dependency rows into this compiler.

Source: src/compiler.x:139

Compiler.new

Compiler Compiler.new(void)

Creates a compiler with independent package and generated-name state.

Source: src/compiler.x:290

Compiler.new_shared

Compiler Compiler.new_shared(Compiler owner)

Creates a compiler sharing its owner’s package and generated-name state.

Source: src/compiler.x:293

Compiler.next

void Compiler.next(Compiler compiler)

Consumes the current token and advances past following trivia.

This updates the unmatched-brace stack. An unmatched } reports a parse diagnostic, which raises <malformed> under recovery and otherwise exits.

Source: src/compiler.x:429

Compiler.own_diagnostics

void Compiler.own_diagnostics(Compiler compiler)

Routes this compiler’s diagnostic store through its own printer.

Compilers that share a store call this when taking the diagnostic stream back from another compiler.

Source: src/compiler.x:225

Compiler.package_member_spelling

String Compiler.package_member_spelling(Compiler c, String name)

Returns a visible with name’s package-prefixed spelling, or NULL.

An ordinary declaration of the local spelling shadows the with name.

Source: src/compiler.x:1586

Compiler.package_spelling

String Compiler.package_spelling(Compiler compiler, String name)

Returns a name in the current package namespace, preserving prefixes.

Idempotence lets parsing and declaration rewrites share this operation.

Source: src/compiler.x:1517

Compiler.peek

Symbol Compiler.peek(Compiler compiler, int steps)

Returns the non-trivia token type steps from parser position.

Zero reads the current token; positive and negative steps count forward and backward through non-trivia tokens. The parser cursor is unchanged.

Source: src/compiler.x:382

Compiler.record_origin

int Compiler.record_origin(Compiler c, Token token)

Records a token’s location and returns its one-based occurrence.

A null token returns zero. Callers pass the token that opened a construct, so an (at N node) wrapper retains its start for transform diagnostics after compiler.token has reached end of file.

Source: src/compiler.x:470

Compiler.register_package_alias

void Compiler.register_package_alias( Compiler compiler, String name, String alias, Token token)

Registers one local package alias.

Shallow collection and full parsing both see an import, so repeating the same package and alias is a no-op. Another binding of the local spelling is a parse error.

Source: src/compiler.x:1552

Compiler.register_package_member

void Compiler.register_package_member( Compiler c, String name, String member, String local, Token member_token, Token local_token)

Registers one package member under a bare local spelling.

The package member must already exist in the symbol table. Repeating the same binding is a no-op; any conflicting local binding is an error.

Source: src/compiler.x:1565

Compiler.semantic_binding_facts

Map Compiler.semantic_binding_facts(Compiler compiler)

Returns the current borrowed semantic-facts map indexed by binding.

A semantic transaction may replace this map, so reacquire it afterwards.

Source: src/compiler.x:304

Compiler.set_gensym

void Compiler.set_gensym(Compiler compiler, int count)

Sets the shared anonymous-aggregate counter used before the next result.

Source: src/compiler.x:2208

Compiler.shallow_parse

void Compiler.shallow_parse(Compiler c, Map globals)

Collects file-scope declarations into globals without parsing bodies.

Source: src/compiler.x:658

Compiler.shallow_parse_overlay

void Compiler.shallow_parse_overlay(Compiler c, Map base, Map overlay)

Collects declarations with reads over base then overlay.

Writes go to overlay, which captures exactly what this translation contributes above base.

Source: src/compiler.x:674

Compiler.skip_trivia_from

Token Compiler.skip_trivia_from(Compiler compiler, Token token)

Returns the first non-trivia token at or after token.

Source: src/compiler.x:374

Compiler.test

inline int Compiler.test(Compiler compiler, Symbol type)

Consumes type when current and reports whether it matched.

Source: src/compiler.x:437

Compiler.tokenize

void Compiler.tokenize(Compiler c, char *text)

Scans source and positions the compiler at its first non-trivia token.

The compiler borrows text for diagnostics and macro source capture until translation finishes.

Source: src/compiler.x:343

Compiler.update_source_visibility

void Compiler.update_source_visibility(Compiler c, List directives)

Applies public and private pragma directives to source visibility state.

A negative visibility state disables pragma tracking for this token stream.

Source: src/compiler.x:713

Compiler.var

Var Compiler.var(Compiler compiler)

Boxes the compiler’s pointer; the caller keeps the compiler.

Source: src/compiler.x:106

Map

Map.merge_translation_dependency

void Map.merge_translation_dependency( Map dependencies, String path, Var content_hash)

Merges one translation dependency, preserving an existing content hash.

Source: src/compiler.x:125

Sym

Sym.base_symbols

Map Sym.base_symbols(Sym sym)

Copies all base-scope symbols into a fresh map in source order.

Package collection uses this so it resolves against the prelude and the importing unit’s already-visible includes without mutating either.

Source: src/compiler.x:1227

Sym.bind_identity

List Sym.bind_identity(Sym sym, List context, List binding, List ast)

Installs an existing binding with ast’s qualifier-preserving type.

Source: src/compiler.x:1709

Sym.binding_is_local

int Sym.binding_is_local(Sym sym, List binding)

Reports whether binding belongs to a scope inside the base scopes.

Source: src/compiler.x:1470

Sym.binding_is_local_before

int Sym.binding_is_local_before(Sym sym, List binding, int scope_count)

Reports whether binding belongs to a local scope below scope_count.

Counts beyond the current scope depth are clamped to that depth.

Source: src/compiler.x:1477

Sym.current_binding

List Sym.current_binding(Sym sym, List key)

Returns key’s binding in the current scope, or NULL.

Source: src/compiler.x:1252

Sym.current_symbols

Map Sym.current_symbols(Sym sym)

Returns the current scope’s mutable symbol map, or NULL.

Source: src/compiler.x:1246

Sym.declare

List Sym.declare(Sym sym, List context, List key, List ast)

Analyzes a complete declaration type and installs its stored declared type.

Returns the declared binding. At file scope this also records static visibility; local declarations record automatic-storage and declared-type facts. Stored types discard storage and inline while retaining const, restrict, and volatile.

Source: src/compiler.x:1657

Sym.declare_delegate_field

void Sym.declare_delegate_field(Sym sym, Type aggregate, String name)

Marks one named aggregate field as a delegate.

Source: src/compiler.x:2183

Sym.declare_enumerator

void Sym.declare_enumerator(Sym sym, List key, Symbol owner)

Associates an enumerator key with its owner in the active scope.

Source: src/compiler.x:1268

Sym.declare_field_order

void Sym.declare_field_order(Sym sym, Type type, List fields)

Records declaration AST fields in source order after binding finishes.

Field types already use member keys; this adds only order and omits unnamed fields.

Source: src/compiler.x:2164

Sym.define

List Sym.define(Sym sym, List key, List type)

Defines key and returns its stable binding in the active scope.

Source: src/compiler.x:1377

Sym.define_global

List Sym.define_global(Sym sym, List key, List type)

Defines key in the unit’s writable base scope and returns its binding.

The definition survives the expression scope that first resolved it.

Source: src/compiler.x:1388

Sym.define_macro

void Sym.define_macro(Sym sym, Atom name, List definition)

Defines or replaces a macro in the active lexical scope.

Captured bindings are recorded for later shadow handling. Replacing a name already defined in this scope does not increase the local macro count.

Source: src/compiler.x:1279

Sym.delegate_aggregate

Type Sym.delegate_aggregate(Sym sym, Type type)

Resolves typedefs or one pointer layer to an aggregate tag, or NULL.

Source: src/compiler.x:2188

Sym.enumerator_owner

Symbol Sym.enumerator_owner(Sym sym, List key)

Returns the current scope’s enum owner for key, or zero.

Source: src/compiler.x:1260

Sym.field_order

List Sym.field_order(Sym sym, Type type)

Returns recorded named fields in source order, or NULL.

Source: src/compiler.x:2180

Sym.file_statics

Map Sym.file_statics(Sym sym)

Returns the current borrowed set of file-static declaration keys.

A semantic transaction may replace this map, so reacquire it afterwards.

Source: src/compiler.x:1238

Sym.get

List Sym.get(Sym sym, List key)

Returns key’s type, retrying a bare key in package space, or NULL.

Source: src/compiler.x:1417

Sym.get_exact

List Sym.get_exact(Sym sym, List key)

Returns key’s type without package fallback, or NULL.

Source: src/compiler.x:1396

Sym.global_symbols

Map Sym.global_symbols(Sym sym)

Returns the mutable global symbol map supplied to the latest reset.

Source: src/compiler.x:1220

Sym.has_local_macros

int Sym.has_local_macros(Sym sym)

Returns whether any lexical scope contains a local macro definition.

Source: src/compiler.x:1291

Sym.introduce

List Sym.introduce(Sym sym, String spelling)

Allocates a fresh binding identity for a compiler-introduced spelling.

Source: src/compiler.x:1487

Sym.is_array_type

int Sym.is_array_type(Sym sym, Type type)

Reports whether type reaches the named Array value type.

Source: src/compiler.x:2135

Sym.is_map_type

int Sym.is_map_type(Sym sym, Type type)

Reports whether type reaches the named Map value type.

Source: src/compiler.x:2139

Sym.is_named_value_type

int Sym.is_named_value_type(Sym sym, Type type, String name)

Reports whether type reaches a named value type before its definition.

Source: src/compiler.x:2143

Sym.is_string_type

int Sym.is_string_type(Sym sym, Type type)

Reports whether type reaches the named String value type.

Source: src/compiler.x:2131

Sym.is_var_type

int Sym.is_var_type(Sym sym, Type type)

Reports whether type reaches the named Var value type.

Source: src/compiler.x:2127

Sym.local_type

Type Sym.local_type(Sym sym, Type type)

Resolves a block-local typedef to the type saved at its declaration. File-scope names retain their semantic identity. Local alias definitions are resolved before they are installed, so one lookup crosses the whole local chain without consulting names shadowed since its declaration.

Source: src/compiler.x:2044

Sym.lookup

List Sym.lookup(Sym sym, List key, List *type)

Resolves an existing key and optionally stores its semantic type.

A symbol row without a binding receives a stable binding identity. A total miss returns NULL and stores NULL through type when provided.

Source: src/compiler.x:1452

Sym.lookup_field

Type Sym.lookup_field(Sym sym, Type type, List field)

Returns an aggregate field’s declared type, or NULL.

Source: src/compiler.x:2152

Sym.lookup_macro

List Sym.lookup_macro(Sym sym, Atom name)

Returns the innermost visible local macro named name, or NULL.

Source: src/compiler.x:1297

Sym.mark_static

void Sym.mark_static(Sym sym, List key)

Marks a declaration key as file-static.

Source: src/compiler.x:1241

Sym.next_typedef

Type Sym.next_typedef(Sym sym, Type type, int *hops)

Resolves one typedef hop and counts against the shared cycle budget.

hops is an in-out counter initialized by the caller for the whole walk. Returns NULL for an unresolved link. The shared budget turns a cycle into the same diagnostic as full-chain resolution.

Source: src/compiler.x:1976

Sym.normalize_declared_type

Type Sym.normalize_declared_type(Sym sym, Type type)

Resolves typedef bases while retaining every declarator qualifier.

Source: src/compiler.x:2086

Sym.pop_scope

SymScope Sym.pop_scope(Sym sym)

Pops the innermost scope, or returns an empty scope when none exists.

Source: src/compiler.x:2227

Sym.push_new_scope

void Sym.push_new_scope(Sym sym)

Pushes a new empty lexical scope.

Source: src/compiler.x:2212

Sym.push_scope

void Sym.push_scope(Sym sym, SymScope scope)

Pushes a caller-supplied lexical scope while retaining its map objects.

Source: src/compiler.x:2222

Sym.reference

List Sym.reference(Sym sym, List key, List *type)

Resolves key or creates a forward binding in the current scope.

Stores NULL through type when no declaration supplies a type.

Source: src/compiler.x:1459

Sym.reset

void Sym.reset(Sym sym, Map globals)

Resets symbol state to one base scope backed by globals.

Later definitions mutate that caller-supplied map.

Source: src/compiler.x:1211

Sym.resolve_global

List Sym.resolve_global(Sym sym, List key, List *type)

Resolves a binding through base scopes and optionally stores its type.

Returns NULL when no base scope contains the key.

Source: src/compiler.x:1466

Sym.resolve_key

Type Sym.resolve_key(Sym sym, Type key)

Resolves a canonical typedef key to the end of its declared chain.

Source: src/compiler.x:1964

Sym.resolve_numeric_type

Type Sym.resolve_numeric_type(Sym sym, Type type)

Resolves a numeric typedef without reducing semantic object types.

Returns NULL when resolution yields neither a numeric type nor a recognized builtin numeric typedef.

Source: src/compiler.x:2025

Sym.scope_count

int Sym.scope_count(Sym sym)

Returns the number of semantic scopes, including base scopes.

Source: src/compiler.x:1294

Sym.seed_var_tags

void Sym.seed_var_tags(Sym sym, Map symbols)

Registers declared T_var converters in the active Type unit.

Source: src/compiler.x:1370

Sym.set

void Sym.set(Sym sym, List key, List type)

Sets a semantic type for key in the required active scope.

Source: src/compiler.x:1310

Sym.var_tag_for_type

Symbol Sym.var_tag_for_type(Sym sym, Type type, Type *resolved)

Returns a type’s Var tag and optionally stores its resolved type.

resolved receives the final type even when the result is zero because no Var tag is registered. A null input stores NULL and returns zero.

Source: src/compiler.x:2117

SymTxn

SymTxn.commit

void SymTxn.commit(SymTxn s)

Publishes an active semantic transaction and makes rollback a no-op.

Source: src/compiler.x:1135

SymTxn.local_macros_changed

int SymTxn.local_macros_changed(SymTxn transaction)

Returns whether the transaction’s active scope changed its macro map.

Source: src/compiler.x:1155

SymTxn.rollback

void SymTxn.rollback(SymTxn transaction)

Restores every semantic value captured by an active transaction.

Source: src/compiler.x:1165

Var

Var.compiler

Compiler Var.compiler(Var value)

Recovers the compiler pointer boxed by Compiler.var.

Source: src/compiler.x:109

Public types

Compiler

typedef struct Compiler { String filename, text, root_dir; String package, List package_dirs; Map package_roots, package_aliases, package_members; Token token; Tokenizer tokenizer; List return_type, include_dirs; Map deps; List aggregate_type, macro_stack, Sym sym; SymScope params; Map key_ids, macros, kw_aliases; Map kw_seen; Map fixed; Map protocols, conforms, protocol_helpers; Map proto_cache; Map adoptions; Map macro_holes; Map local_macro_captures; List lambda_scopes; Map imports; Map init_tokens, static_init_deps, fn_defs; Array id_keys, mid_inits; String init_fn, fini_fn; Array early_decls, proto_inits, early_inits, late_inits, int prelude; int runtime_inc, runtime_hdrs, collect_protocols, shallow, source_private; int in_pattern, match_is, runtime_literals, inline_header; int builtin_defs, in_proto, macro_count, recovery_depth; int local_macro_capture_scopes; String fn_name, Diagnostics diagnostics, Array braces, import_stack; Lisp macro_lisp, String import_src, int borrowed_lisp; GenNames names; Array origins, int origin; } *Compiler

Holds mutable state for one source translation.

The structure and its state belong to the current Scope. Every new compiler is registered for shutdown cleanup, so call Compiler.free_lisp before its owning Scope ends, even when compile-time Lisp was not used.

Source: src/compiler.x:52

Diagnostics

typedef struct Diagnostics *Diagnostics

Names the positioned diagnostic store routed by a Compiler.

Source: src/compiler.x:21

GenNames

typedef struct GenNames { Map counters, adapters, int gensym_count; } *GenNames

Holds scope-owned generated-name state shared by related compilers.

Compiler.new initializes every valid instance; callers borrow it from the compiler rather than constructing or freeing it.

Source: src/compiler.x:28

Sym

typedef struct Sym *Sym

Names the scope-owned semantic table belonging to one compiler.

Source: src/compiler.x:42

SymScope

typedef struct SymScope { Map symbols, bindings, enumerators, macros; } SymScope

Holds the three mutable maps that form one lexical semantic scope.

Active scopes have initialized maps. The zero value is only the sentinel returned when an empty scope stack is popped.

Source: src/compiler.x:37

SymTxn

typedef struct SymTxn *SymTxn

Names a scope-owned, one-use semantic transaction.

Source: src/compiler.x:44

Design notes

Coordinates tokenization, shallow declaration discovery, full parsing, symbol scopes, diagnostics, and generated initialization. Shallow parsing skips function bodies; full parsing produces the AST of the source.

Symbol lookup walks the scope stack from inner to outer. Diagnostics may exit immediately or raise <malformed> while a recovery boundary is active.