...
The parser runtime has a return object that captures success/failure. Whether any given runtime failure is actually a failure, or just part of speculative parsing is not something we actually know in advance, which means even if we're just backtracking as part of parsing we'll be constructing diagnostic objects just in case those errors propagate up to top level.
For example: suppose we have a choice with 3 alternatives. Suppose the data doesn't match any of the 3. The diagnostic we issue doesn't want to say that the 3rd alternative didn't match, it wants to say that no alternative matched the data, and specifically may want to say that the first alternative didn't match because of reason(s) X, the second due to reason(s) Y, and the third due to reason(s) Z. That is, imagine we are parsing along attempting the first alternative of this choice. We encounter an error. Now this error might be suppressed because one of the subsequent alternatives might succeed, and in that case we can discard the failure reason for the first alternative. Or, this error might still be needed because if all 3 alternatives result in errors, it might be helpful as a diagnostic to see why each alternative failed.
We'll want to design this so that most of the work associated with diagnostics (constructing message strings for example, and substituting toString representations of various pieces of errant data into them) all happens at the time the diagnostic is actually issued at top level, and not at the time the diagnostic object is created. Aka,
- we will want to do lazy message construction.
Conveniently, this goal lines up perfectly with internationalization requirements, where the software should not contain message strings at all, but should just construct objects of the right type. Message strings are created at the point where messages are displayed to a user, or printed out. While log files may want to contain English, they also want to contain all the components to enable internationalized presentation, so they don't want to contain the formatted English messages, but rather a message identifier, the string representations of the things to be substituted into the message, and possible the English (in case someone is trying to make sense of the log, outside of an environment where they have the internationalization available, in which case they must understand English.)
In addition, since the JVM will throw some exceptions (like divide by zero), we will surround the runtime with a try-catch, and catch exceptions coming from the JVM to include in our returned list of errors/diagnostics/warnings.
...
- turn on/off this tracing, without having to restart, and similarly control the verbosity of detail in the traces/log, and control any selectivity features of the tracing.
- supply the streams to which the trace/logs are written. These may or may not be streams leading to a file system.
- avoid full-disk situations by being notified about the volume of data written to the streams and being able to change the streams without loss of any traces/log records.
- run forever with tracing/logging turned on, albeit with some performance degradation proportional to the amount of trace/log information being generated.
...