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

src/diagnostics.x

Structured compiler diagnostics collection.

Functions

Compiler

Compiler.diagnostics

List Compiler.diagnostics(Compiler compiler)

Returns a report-order snapshot of all collected diagnostics. Snapshot cells are canonicalized through the active pool hierarchy and share entry values; each retains its actual producing-pool lifetime.

Source: src/diagnostics.x:357

Compiler.display_path

String Compiler.display_path(Compiler compiler, String path)

Returns path relative to the compiler root when it lies beneath it. Other paths, including NULL, are returned unchanged.

Source: src/diagnostics.x:238

Compiler.dump_cache

void Compiler.dump_cache(Compiler compiler)

Prints each cached numeric identifier and its key to stdout.

Source: src/diagnostics.x:393

Compiler.dump_symbol_table

void Compiler.dump_symbol_table(Compiler compiler, Map map)

Prints every entry in map to stdout in Map iteration order.

Source: src/diagnostics.x:388

Compiler.dump_tokens

void Compiler.dump_tokens(Compiler compiler)

Prints every non-EOF token with its position and visible content. Compiler.tokenize must have populated the compiler’s tokenizer.

Source: src/diagnostics.x:378

Compiler.error_count

int Compiler.error_count(Compiler compiler)

Returns the number of counted diagnostics accepted since the last reset. Warnings and the generated limit notice are excluded.

Source: src/diagnostics.x:351

Compiler.origin_location

List Compiler.origin_location(Compiler compiler, int occurrence)

Resolves a recorded occurrence through generated ancestry to its source. Returns NULL when occurrence is outside the origin table. The occurrence must come from this compiler’s current parse and transform state. Returned location cells are canonicalized through the active pool hierarchy and retain their actual producing-pool lifetime. They share the recorded filename, which retains its own producing-pool lifetime.

Source: src/diagnostics.x:213

Compiler.print_diagnostic

void Compiler.print_diagnostic(Compiler compiler, List entry)

Writes one structured diagnostic entry and source context to stderr. NULL is ignored. A present location supplies file, one-based line and column, and token length; String notes are joined into one note line.

Source: src/diagnostics.x:181

Compiler.report_error

void Compiler.report_error( Compiler compiler, Symbol code, String message, Token token, List notes)

Submits a located compiler error, then transfers or exits. An explicit token wins; otherwise an active recorded origin is resolved before the current token. NULL message defaults to "compiler error".

Raises: <malformed> with the supplied category while a recovery boundary is active. Without one, exits the process with status 1.

Source: src/diagnostics.x:282

Compiler.report_warning

void Compiler.report_warning( Compiler compiler, Symbol code, String message, Token token, List notes)

Records and emits a located warning without consuming the error limit. Location selection matches Compiler.report_error; NULL code becomes <warning> and NULL message becomes "compiler warning". This operation returns without raising or changing the process exit status.

Source: src/diagnostics.x:298

Compiler.token_location

List Compiler.token_location(Compiler compiler, Token token)

Builds the diagnostic location for token or the current token. If neither exists, returns the current file at line 1, column 1, and byte position 0 with zero length. When a token is available, compiler.filename is made relative to the compiler root. Location cells and a derived path are canonicalized through the active pool hierarchy and retain their actual producing-pool lifetimes; an unchanged filename retains the compiler’s producing-pool lifetime.

Source: src/diagnostics.x:254

Diagnostics

Diagnostics.entries

List Diagnostics.entries(Diagnostics diag)

Returns an immutable List snapshot in publication order. Snapshot cells are canonicalized through the active pool hierarchy and retain their actual producing-pool lifetime. They share the stored entry Lists. The snapshot includes warnings and the limit notice; changing or resetting diag does not change it.

Source: src/diagnostics.x:88

Diagnostics.has_emitter

int Diagnostics.has_emitter(Diagnostics diag)

Returns whether diag currently has an emitter.

Source: src/diagnostics.x:94

Diagnostics.new

Diagnostics Diagnostics.new(DiagnosticEmitter emit, void *owner, int limit)

Creates an empty diagnostic store with an optional emitter. A negative limit is treated as zero; zero collects without a stopping threshold. The emitter and owner are borrowed.

Source: src/diagnostics.x:53

Diagnostics.reached_limit

int Diagnostics.reached_limit(Diagnostics diag)

Returns whether counted reports have reached the positive limit. A zero limit never reports that it has been reached.

Source: src/diagnostics.x:99

Diagnostics.report

void Diagnostics.report( Diagnostics diag, Symbol code, String message, List location, List notes)

Records and synchronously emits one diagnostic unless already limited. Entries retain publication order. NULL code becomes <driver>. Reaching a positive limit publishes one following <limit> notice, and later reports are ignored. Supplied message, location, and notes are shared; their canonical-value pools must outlive the store and its snapshots.

Source: src/diagnostics.x:138

Diagnostics.reset

void Diagnostics.reset(Diagnostics diag)

Clears stored entries and limit state while preserving configuration.

Source: src/diagnostics.x:65

Diagnostics.set_emitter

void Diagnostics.set_emitter( Diagnostics diag, DiagnosticEmitter emit, void *owner)

Replaces the borrowed emitter and owner without replaying stored entries. A NULL emitter disables streaming.

Source: src/diagnostics.x:74

Public types

DiagnosticEmitter

typedef void (*DiagnosticEmitter)(void *owner, List entry)

Receives one borrowed diagnostic entry when the store publishes it. Diagnostics retains the callback and borrowed owner, invokes the callback synchronously, and never releases owner.

Source: src/diagnostics.x:21

Diagnostics

typedef struct Diagnostics { Array entries; DiagnosticEmitter emit; void *owner; int limit; int count, limit_notified; } *Diagnostics

Collects diagnostic entries and optionally streams them. A value is valid after Diagnostics.new. The store and backing Array are Scope-owned; entry Lists and immutable children retain the lifetime of their producing canonical-value pools. A borrowed owner must remain valid while its emitter is installed.

Source: src/diagnostics.x:29

Design notes

Maintains a bounded, ordered collection of compiler diagnostics with optional streaming to one emitter.

Entries are stored chronologically and exposed as immutable List snapshots. A zero limit disables the stopping threshold without disabling collection. The store and its mutable Array belong to the caller’s active Scope; entry Lists and Strings belong to their producing canonical-value pools.