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

src/diagnostics.x

Compiler diagnostic storage and rendering.

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

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

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

Compiler.dump_cache

void Compiler.dump_cache(Compiler compiler)

Prints each cached numeric identifier and its key to stdout.

Source: src/diagnostics.x:683

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

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

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

Compiler.file_prefix

String Compiler.file_prefix(Compiler c)

Returns the prefix that the statics of the module file holding the current token take, or NULL outside a module unit. A module’s first row marks the start of its text, so other units return before any scan.

Source: src/diagnostics.x:388

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

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

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

Compiler.report_problem

void Compiler.report_problem( Compiler c, Symbol code, String message, Token token, List notes)

Records and emits a located compiler error, then returns so the translation continues; it fails when it finishes. Location and the message default match Compiler.report_error.

Source: src/diagnostics.x:513

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

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

Compiler.source_token

Token Compiler.source_token(Compiler c, Token token, String &file)

Returns a copy of token at its line, column, and byte offset in the own text of the file that holds it, and sets file to that file. The host preprocessor’s rows record no offsets, so a token of its output keeps its merged offset.

Source: src/diagnostics.x:448

Compiler.take_diagnostics

void Compiler.take_diagnostics(Compiler c, Compiler child)

Moves collected child reports into the caller’s store without re-emitting. Shared stores already contain their entries. The child’s separate store remains configured and empty after its reports have been transferred.

Source: src/diagnostics.x:629

Compiler.text_source

String Compiler.text_source(Compiler c, int position, int &offset)

Returns the file that a module’s line markers give byte position of the compiler’s text, and sets offset to that byte’s offset in the file. Without such a marker, the file is the compiler’s own and offset is position.

Source: src/diagnostics.x:434

Compiler.token_column

int Compiler.token_column(Compiler c, Token token)

Returns token’s column in the file that holds it. A module region that begins inside a line of its file continues that line’s columns.

Source: src/diagnostics.x:423

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

Compiler.token_source

String Compiler.token_source(Compiler c, Token token, int &?line)

Returns the file that the line markers of a merged text give token, and sets line to the token’s line in that file. A token outside the marked regions keeps the compiler’s own file and its line.

Source: src/diagnostics.x:376

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

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

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

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

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

Diagnostics.reset

void Diagnostics.reset(Diagnostics diag)

Clears stored entries and limit state while preserving configuration.

Source: src/diagnostics.x:62

Public types

Diagnostics

typedef struct Diagnostics { Array entries; Map published; 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:17

DiagnosticsHold

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

Records where Diagnostics.hold stopped streaming.

Source: src/diagnostics.x:26

Design notes

Each report has one ordered entry. The store borrows its printer, while canonical entry values retain their producing-pool lifetimes.