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

src/diagnostics.x

Structured compiler diagnostics collection.

Functions

Functions

diagnostics_write_json

int diagnostics_write_json(String path)

Sends every later printed diagnostic to path as JSON Lines. The file is created or truncated. Each diagnostic is one append write, so forked translation workers sharing the descriptor never interleave lines, and a line is complete before any exit. Returns zero when path cannot be opened.

Source: src/diagnostics.x:212

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

Compiler.display_path

String Compiler.display_path(Compiler compiler, String path)

Returns a physical source path for semantic facts, otherwise a path relative to the compiler root. Pseudo paths and NULL stay unchanged.

Source: src/diagnostics.x:318

Compiler.dump_cache

void Compiler.dump_cache(Compiler compiler)

Prints each cached numeric identifier and its key to stdout.

Source: src/diagnostics.x:495

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

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

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

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

Compiler.print_diagnostic

void Compiler.print_diagnostic(Compiler compiler, List entry)

Writes one structured diagnostic entry and source context to stderr, or one JSON line after diagnostics_write_json. 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:256

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

Compiler.report_warning

void Compiler.report_warning( Compiler c, 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:386

Compiler.report_warning_at

void Compiler.report_warning_at( Compiler compiler, Symbol code, String message, List location, List notes)

Records and emits a warning at a location built earlier by Compiler.token_location, for a report raised after its token has been consumed. Defaults match Compiler.report_warning.

Source: src/diagnostics.x:395

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. Semantic facts use physical paths; ordinary token locations use Compiler.display_path. 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:337

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

Diagnostics.hold

DiagnosticsHold Diagnostics.hold(Diagnostics diag)

Stops streaming until Diagnostics.release and records the current entries, count, and limit state.

Source: src/diagnostics.x:77

Diagnostics.new

Diagnostics Diagnostics.new(Compiler printer, int limit)

Creates an empty diagnostic store that streams through printer. A NULL printer does not stream. A negative limit is treated as zero; zero collects without a stopping threshold. The printer is borrowed.

Source: src/diagnostics.x:60

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

Diagnostics.release

void Diagnostics.release(Diagnostics diag, DiagnosticsHold hold, int keep)

Restores the streaming saved by hold. When keep is set, entries published since the hold remain and stream now; otherwise they are discarded with the count and limit state they changed.

Source: src/diagnostics.x:89

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>. A report equal to a stored entry is ignored. Reaching a limit greater than one publishes a following <limit> notice; a limit of one stops after the first error. 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:171

Diagnostics.reset

void Diagnostics.reset(Diagnostics diag)

Clears stored entries and limit state while preserving configuration.

Source: src/diagnostics.x:68

Public types

Diagnostics

typedef struct Diagnostics { Array entries; Compiler printer; 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 printer must remain valid while it is installed.

Source: src/diagnostics.x:24

DiagnosticsHold

typedef struct DiagnosticsHold { Compiler printer; int entries, count, limit_notified; } DiagnosticsHold

Records where Diagnostics.hold stopped streaming.

Source: src/diagnostics.x:32

Design notes

Maintains a bounded, ordered collection of compiler diagnostics with optional streaming to one compiler’s printer.

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.