TL;DR: Standardization of messages posted by sclang and of controls for their verbosity.
Brian Heim, 29 jan 2017
This document sketches a specification for the standardization and elaboration
of the diagnostic message logging done by the SuperCollider language
executable (sclang). This specification consists of three main features:
- A small, fixed set of logging verbosity/priority levels
- Standard formatting of messages
- User controls for setting the verbosity levels of
sclangas well as its smaller components
In addition to being able to set the verbosity level of sclang as a whole,
being able to individually set the verbosity level of major components may
also be desirable. Such components might include:
- Lexer (
yylex()) - Bison Parser (
yyparse()) - Interpreter/Compiler (PyrParseNode &
interpret()in PyrInterpreter3) - SCDoc and/or HelpBrowser
- Execution of primitives
Probably best to keep this on the C++ side as much as possible to avoid slowdown.
0 is the least verbose,
9 the most verbose. Each level implicitly includes the message types of all
the levels of lesser verbosity:
| Name | Level | Description |
|---|---|---|
| FATAL_ERROR | 0 | Errors which halt the interpreter |
| ERROR | 1 | Errors posted when a request cannot be completed due to exceptional input |
| WARNING | 2 | Warnings posted to warn the user of unexpected input which may lead to unpredictable or undefined behavior |
| INFO | 3 | Low-frequency system events; asynchronous commands received or sent; terse reports of control flow and data transfers |
| VERBOSE | 4 | Low-frequency debugging info: important method entries and exits; detailed dumps of data transfers and control flow; other low-frequency events |
| DEBUG | 9 | Thorough reports of method entries, exits, and parameters; detailed dumps of most events |
Codes 5-8 are left open for now to permit future expansion if necessary.
TBD: The default verbosity level is 2 or 3.
| Level Name | Message Format |
|---|---|
| FATAL_ERROR | FATAL ERROR: %component: %description |
| ERROR | ERROR: %component: (%method:) %description |
| WARNING | WARNING: %component: (%method:) %description |
| INFO | %component: %method/event-type: %description |
| VERBOSE (event) | %component: %method/event-type: %description(\n\tdata: %data) |
| VERBOSE (method entry/exit) | %component: [-> or <-]%method |
| DEBUG | (same as VERBOSE) |
TBD: whether lower levels gain "extended descriptions" with higher levels of verbosity, or whether that would come naturally as a result of the other debugging info posted at higher levels.
-V <level>. For instance,sclang -V 2starts sclang and only outputs warnings, errors, and fatal errors.
- verbosity: 1 # sets verbosity for sclang
- verbosity-lexer: 3 # sets verbosity for the lexer
- verbosity-scdoc: 3 # sets verbosity for SCDocThis configuration would be read as: first set all the components' verbosity levels to 1 (ERROR), then set the verbosity level of the lexer to 3 (INFO) and that of scdoc to 3 (INFO).
- New primitives (on
LanguageConfig) to get and set the verbosity levels per component. (.getLexerVerbosity, etc.) - Setter for
sclangoverall verbosity. - TBD: How to handle getting the overall verbosity when the levels don't all
match? Print a message? Take the min/max? Add another method for
isVerbosityAllTheSame(not the real method name)?
TBD: put enum constants in both C++ and SC? Or make SC getter primitives that just refer to the C++ enum?
TBD: any cases where numbers can't be exchanged for the names? i.e., can you
do -V ERROR? verbosity: INFO?
TBD: does SC post any fatal error messages right now? Other than the IDE's "Interpreter crashed or stopped forcefully"? Is there any infrastructure for this at all?
TBD: expand to scsynth?
Note: server already has verbosity settings 0, -1, -2. Should probably not touch these. Not very into the negative numbers (first time I've run across it in looking at logger verbosity implementations).