A single observation about the input.
Diagnostics do not interrupt processing. Every stage accepts and returns an accumulator of them, so a result is available even where it is partial, and success carries diagnostics alongside it.
Codes
Codes are stable and the tier is determined by the number, so an editor can filter by code and a consumer can suppress a rule without matching on message text.
| Range | Tier |
|---|---|
TPTP00xx | input and resource limits — Tptp |
TPTP01xx | lexical — Tptp.Lexer |
TPTP02xx | statement structure — Tptp.Splitter |
TPTP03xx | grammar — Tptp.Parser |
TPTP04xx | :== well-formedness — Tptp.Lint |
TPTP05xx | cross-statement — Tptp.Lint |
TPTP06xx | include — Tptp.Include |
TPTP08xx | analyzer infrastructure — Tptp.Analyzer |
A code is never reassigned, so the numbering contains gaps: TPTP0103,
TPTP0108, TPTP0403, TPTP0502, TPTP0505 and TPTP0604 are unassigned.
TPTP0505 was withdrawn when the rule raising it was found to contradict the
TPTP.
There is no TPTP07xx tier. It was reserved for dialect findings, of which there
are none: the BNF gives each language its own nonterminals, so a construct used
in a language that does not provide it fails to parse rather than reaching a
rule. Tptp.Lint sets this out, and Tptp.Query.dialect/1 derives the dialect
instead.
related carries the accompanying positions of a finding, such as the first
declaration alongside a redeclaration.
Summary
Functions
Whether any diagnostic is severe enough to call the result a failure.
Render one diagnostic as a single line, resolving the span against a line index.
Build a diagnostic.
Sort diagnostics into reading order: by file, then by offset, then by code.
Types
@type severity() :: :error | :warning | :info | :hint
How much a diagnostic matters.
Only :error means no result was produced. A :warning accompanies a CST that
is perfectly usable, which is why every entry point returns diagnostics alongside
success rather than instead of it.
@type t() :: %Tptp.Diagnostic{ code: binary(), hint: binary() | nil, message: binary(), related: [{Tptp.Span.t(), binary()}], severity: severity(), span: Tptp.Span.t() }
One thing the library has to say about a span of input.
Functions
Whether any diagnostic is severe enough to call the result a failure.
@spec format(t(), Tptp.Span.line_index(), Path.t() | nil) :: binary()
Render one diagnostic as a single line, resolving the span against a line index.
iex> span = Tptp.Span.new(0, 4, 1)
iex> diagnostic = Tptp.Diagnostic.new("TPTP0101", :error, span, "illegal character")
iex> index = Tptp.Span.line_index("fof(\0)")
iex> Tptp.Diagnostic.format(diagnostic, index)
"1:5: error: illegal character [TPTP0101]"Build a diagnostic.
message is copied with :binary.copy/1 when it is a sub-binary of the source,
because a diagnostic outlives the file it describes far more often than a token
does.
Sort diagnostics into reading order: by file, then by offset, then by code.