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

src/symbols.x

The compiler’s semantic symbol table.

Functions

Compiler

Compiler.aggregate_name

Var Compiler.aggregate_name( Compiler c, Symbol kind, Var name, int definition)

Binds a local aggregate tag before its fields, preserving native spelling. A reference reuses the nearest visible tag; a definition or standalone forward declaration introduces the tag in the current lexical scope. A macro template names its tags as template locals.

Source: src/symbols.x:682

Compiler.begin_semantic_transaction

SymTxn Compiler.begin_semantic_transaction(Compiler c)

Begins a reversible transaction over the current semantic scope.

The transaction restores 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/symbols.x:1246

Compiler.drop_fact

void Compiler.drop_fact(Compiler c, Var key)

Deletes one semantic binding fact.

Source: src/symbols.x:433

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/symbols.x:830

Compiler.imported_spelling

String Compiler.imported_spelling(Compiler c, String name)

Returns an unambiguous imported spelling for name, or NULL.

Source: src/symbols.x:842

Compiler.macro_definition_locals

Map Compiler.macro_definition_locals(Compiler c)

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

Source: src/symbols.x:877

Compiler.macro_template_local

int Compiler.macro_template_local(Compiler c, List binding)

Reports whether binding is a local of the active macro definition or of a template that encloses it; a nested definition’s literal names share the enclosing template’s names.

Source: src/symbols.x:885

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/symbols.x:815

Compiler.package_spelling

String Compiler.package_spelling(Compiler c, String name)

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

Idempotence lets parsing and declaration rewrites share this operation.

Source: src/symbols.x:752

Compiler.record_declaration_visibility

void Compiler.record_declaration_visibility(Compiler c, List declaration)

Records the visibility of one parsed top-level declaration. Lexical privacy and static storage mark bindings in Sym; typedef rows are retained for placing generated protocol declarations at the same boundary.

Source: src/symbols.x:709

Compiler.register_package_alias

void Compiler.register_package_alias( Compiler c, 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/symbols.x:764

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/symbols.x:777

Compiler.semantic_binding_facts

Map Compiler.semantic_binding_facts(Compiler c)

Returns the borrowed semantic-facts map indexed by binding.

Write it through set_fact and drop_fact, which a semantic transaction can restore.

Source: src/symbols.x:426

Compiler.set_fact

void Compiler.set_fact(Compiler c, Var key, Var value)

Sets one semantic binding fact.

Source: src/symbols.x:429

Sym

Sym.at_file_scope

int Sym.at_file_scope(Sym s)

Returns whether declarations currently bind at file scope.

Source: src/symbols.x:208

Sym.base_symbols

Map Sym.base_symbols(Sym s)

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/symbols.x:220

Sym.bind_identity

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

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

Source: src/symbols.x:661

Sym.binding_is_local

int Sym.binding_is_local(Sym s, List binding)

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

Source: src/symbols.x:406

Sym.binding_is_local_before

int Sym.binding_is_local_before(Sym s, 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/symbols.x:413

Sym.current_binding

List Sym.current_binding(Sym s, List key)

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

Source: src/symbols.x:392

Sym.current_symbols

Map Sym.current_symbols(Sym s)

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

Source: src/symbols.x:227

Sym.declare

List Sym.declare(Sym s, 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/symbols.x:530

Sym.declare_delegate_field

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

Marks one named aggregate field as a delegate.

Source: src/symbols.x:1215

Sym.declare_enumerator

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

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

Source: src/symbols.x:338

Sym.declare_field_order

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

Records declaration AST fields in source order after binding finishes.

Field types already use member keys. Unnamed rows retain their type and an empty name so initializer traversal preserves anonymous subobjects.

Source: src/symbols.x:1190

Sym.define

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

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

Source: src/symbols.x:291

Sym.define_global

void Sym.define_global(Sym s, List key, List type)

Defines key in the unit’s writable base scope.

The definition survives the expression scope that first resolved it. Its binding is issued at the first reference, as for a row an included file contributes, so the unit numbers its bindings the same whether it defined the row here or replayed it from an interface.

Source: src/symbols.x:331

Sym.define_macro

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

Defines or replaces a macro in the active lexical scope.

Replacing a name already defined in this scope does not increase the local macro count.

Source: src/symbols.x:855

Sym.delegate_aggregate

Type Sym.delegate_aggregate(Sym s, Type type)

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

Source: src/symbols.x:1220

Sym.drop

void Sym.drop(Sym s, Map map, Var key)

Deletes key from map so that an active transaction can restore it.

Source: src/symbols.x:135

Sym.enumerator_owner

Symbol Sym.enumerator_owner(Sym s, List key)

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

Source: src/symbols.x:399

Sym.field_order

List Sym.field_order(Sym s, Type type)

Returns recorded fields in source order, or NULL.

Source: src/symbols.x:1212

Sym.file_statics

Map Sym.file_statics(Sym s)

Returns the borrowed set of file-static declaration keys.

Source: src/symbols.x:241

Sym.get

List Sym.get(Sym s, List key)

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

Source: src/symbols.x:439

Sym.get_exact

List Sym.get_exact(Sym s, List key)

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

Source: src/symbols.x:447

Sym.global_symbols

Map Sym.global_symbols(Sym s)

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

Source: src/symbols.x:213

Sym.has_local_macros

int Sym.has_local_macros(Sym s)

Returns whether any lexical scope contains a local macro definition.

Source: src/symbols.x:863

Sym.introduce

List Sym.introduce(Sym s, String spelling)

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

Source: src/symbols.x:389

Sym.is_array_type

int Sym.is_array_type(Sym s, Type type)

Reports whether type reaches the named Array value type.

Source: src/symbols.x:1148

Sym.is_map_type

int Sym.is_map_type(Sym s, Type type)

Reports whether type reaches the named Map value type.

Source: src/symbols.x:1152

Sym.is_named_value_type

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

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

Source: src/symbols.x:1155

Sym.is_string_type

int Sym.is_string_type(Sym s, Type type)

Reports whether type reaches the named String value type.

Source: src/symbols.x:1144

Sym.is_var_type

int Sym.is_var_type(Sym s, Type type)

Reports whether type reaches the named Var value type.

Source: src/symbols.x:1141

Sym.local_type

Type Sym.local_type(Sym s, 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/symbols.x:1024

Sym.lookup

List Sym.lookup(Sym s, List key, Type &?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/symbols.x:474

Sym.lookup_field

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

Returns an aggregate field’s declared type, or NULL. A member of an anonymous struct or union belongs to its enclosing aggregate in C, so unnamed rows are searched the way a designated initializer already reaches them.

Source: src/symbols.x:1170

Sym.lookup_macro

List Sym.lookup_macro(Sym s, Atom name)

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

Source: src/symbols.x:866

Sym.mark_static

void Sym.mark_static(Sym s, List key)

Marks a declaration key as file-static.

Source: src/symbols.x:244

Sym.new

Sym Sym.new(Compiler c)

Creates the empty symbol table that compiler c owns.

Source: src/symbols.x:116

Sym.next_typedef

Type Sym.next_typedef(Sym s, 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/symbols.x:960

Sym.normalize_declared_type

Type Sym.normalize_declared_type(Sym s, Type type)

Resolves typedef bases while retaining every declarator qualifier.

Source: src/symbols.x:993

Sym.pop_scope

SymScope Sym.pop_scope(Sym s)

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

Source: src/symbols.x:197

Sym.push_new_scope

void Sym.push_new_scope(Sym s)

Pushes a new empty lexical scope.

Source: src/symbols.x:191

Sym.push_scope

void Sym.push_scope(Sym s, SymScope scope)

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

Source: src/symbols.x:194

Sym.put

void Sym.put(Sym s, Map map, Var key, Var value)

Sets map[key] so that an active semantic transaction can restore it. Semantic writes to scope, file-static, and binding-fact maps use this.

Source: src/symbols.x:129

Sym.reference

List Sym.reference(Sym s, List key, Type &?type)

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

Stores NULL through type when no declaration supplies a type.

Source: src/symbols.x:481

Sym.reference_global

List Sym.reference_global(Sym s, List key)

Resolves a global name or creates its forward binding in the base scope. Local declarations cannot capture a retained macro’s global reference.

Source: src/symbols.x:494

Sym.reset

void Sym.reset(Sym s, Map globals)

Resets symbol state to one base scope backed by globals.

Later definitions mutate that caller-supplied map.

Source: src/symbols.x:160

Sym.reset_overlay

void Sym.reset_overlay(Sym s, Map base, Map overlay)

Resets symbol state to read base below the writable scope overlay.

Later definitions mutate overlay; base is only read.

Source: src/symbols.x:169

Sym.resolve_base_type

Type Sym.resolve_base_type(Sym s, Type key)

Resolves a typedef name through the base scopes only, ignoring local typedefs, or returns NULL when the base scopes do not declare it.

Source: src/symbols.x:968

Sym.resolve_global

List Sym.resolve_global(Sym s, List key, Type &?type)

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

Returns NULL when no base scope contains the key.

Source: src/symbols.x:488

Sym.resolve_key

Type Sym.resolve_key(Sym s, Type key)

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

Source: src/symbols.x:913

Sym.resolve_numeric_type

Type Sym.resolve_numeric_type(Sym s, 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/symbols.x:1062

Sym.scope_count

int Sym.scope_count(Sym s)

Returns the number of semantic scopes, including base scopes.

Source: src/symbols.x:205

Sym.seed_var_tags

void Sym.seed_var_tags(Sym s, Map symbols)

Registers declared T_var converters in the active Type unit.

Source: src/symbols.x:318

Sym.set

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

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

Source: src/symbols.x:279

Sym.sole_typedef

Type Sym.sole_typedef(Sym s, Type type)

Returns the name of the one file-scope typedef declared directly as type, or NULL when no typedef or several typedefs are.

Source: src/symbols.x:980

Sym.unit_symbols

Map Sym.unit_symbols(Sym s)

Returns a fresh map of the base symbols with the current scope’s rows merged in.

Source: src/symbols.x:234

Sym.var_tag_for_type

Symbol Sym.var_tag_for_type(Sym s, 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/symbols.x:1120

Sym.visible_symbols

List Sym.visible_symbols(Sym s)

Returns the visible one-part source names and their semantic types. Inner scopes win. The result is a fresh List; types remain borrowed.

Source: src/symbols.x:248

SymTxn

SymTxn.commit

void SymTxn.commit(SymTxn &?s)

Publishes an active semantic transaction and makes rollback a no-op. Its writes are already in the scope maps, so code holding a borrowed map observes a committed expansion. An absent or inactive transaction has no effect.

Source: src/symbols.x:1332

SymTxn.commit_transient

void SymTxn.commit_transient(SymTxn &s)

Commits an active transaction, retaining the original counters map. The caller may then release the transaction’s construction scope. Parsing and evaluation must allocate outside that temporary scope.

Source: src/symbols.x:1356

SymTxn.local_macros_changed

int SymTxn.local_macros_changed(SymTxn &s)

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

Source: src/symbols.x:1309

SymTxn.rollback

void SymTxn.rollback(SymTxn &?s)

Restores every semantic value captured by an active transaction. An absent or inactive transaction has no effect.

Source: src/symbols.x:1376

Design notes

Sym holds one compiler’s declarations as a stack of scopes searched from inner to outer; its lowest scopes hold file-scope declarations. It issues the binding identity of each declared name, resolves typedef chains and aggregate fields, and records which file-scope names are private. A SymTxn stages the rows a macro binds, so a failed expansion leaves the table as it was.