someFile.c:1:27: error: Expression is not assignable [Parser|EXPRESSION_NOT_ASSIGNABLE]
int main() {int x; (x + 2) = 5;}
~~~~~ ^
We generate `Diagnostic` instances using a simple DSL, but the error messages,
the source extracts, and the caret/tilde markers are created lazily, internally.
They are only computed when (or if) the diagnostic gets printed. This is useful,
because it makes creating a `Diagnostic` instance relatively cheap. As a result,
we can create diagnostics even if they might be discarded later, with little
cost. One such place where diagnostics are sometimes discarded is
`ConstantExprParser#evaluateExpr`.
An example of the `IDebugHandler.diagnostic` DSL, used in the parser:
.. code-block:: kotlin
// ...
diagnostic {
id = DiagnosticId.INVALID_ARGUMENT_UNARY
formatArgs(expr.type, op.op.s)
errorOn(c..expr)
}
// ...
The range passed to `errorOn` in the example above, is an implementor of the `SourcedRange` interface.
The `rangeTo` operator is overloaded on `SourcedRange` to easily combine multiple ranges into one, like in this example
from the parser:
.. code-block:: kotlin
sizeOf..tokenAt(rParenIdx)
The `sizeOf` token and the token returned by `tokenAt(rParenIdx)` are not
adjacent (think of `sizeof(int)`), but this overload allows the parser to
trivially create a compound `SourcedRange` to cover the entire sizeof
expression.
Since `LexicalToken` and `ASTNode` are implementations of `SourcedRange`,
compound ranges can be created by mixing and matching tokens and AST pieces
(`tok..node` and `node..tok` are both valid syntax).
Another example, used in `sequentialize`:
.. code-block:: kotlin
// ...
diagnostic {
id = DiagnosticId.UNSEQUENCED_MODS
formatArgs(variable.name)
for (mod in modList) when (mod) {
is BinaryExpression -> errorOn(mod.lhs)
is IncDecOperation -> errorOn(mod)
else -> logger.throwICE("Modification doesn't modify anything") { mod }
}
}
// ...
This illustrates the utility provided by using a lambda + builder DSL. Arbitrary
code can run in the construction of the diagnostic, so the same diagnostic can
be tailored to different situations.
Finally, an example from the preprocessor:
.. code-block:: kotlin
// ...
diagnostic {
id = if (ignoreTrigraphs) DiagnosticId.TRIGRAPH_IGNORED else DiagnosticId.TRIGRAPH_PROCESSED
if (!ignoreTrigraphs) formatArgs(replacement)
columns(matchResult.start() until matchResult.end())
}
// ...
Even the kind of diagnostic can be dynamically selected based on arbitrary
logic, which makes it easy to support feature flags like `-fno-trigraphs` in
diagnostics.
Compiler Errors
^^^^^^^^^^^^^^^
For actual issues in the compiler, we use logging, the
`InternalCompilerError` class, the `throwICE` extension methods on logger
instances, and Kotlin's stdlib functions from `Preconditions.kt`.
We use `a Kotlin wrapper