Standardization of sclang Output Verbosity

TL;DR: Standardization of messages posted by sclang and of controls for their verbosity.

Brian Heim, 29 jan 2017

Overview

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 sclang as well as its smaller components

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.

Verbosity levels

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.

Message formatting

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.

User controls

Command-line options

-V <level>. For instance, sclang -V 2 starts sclang and only outputs warnings, errors, and fatal errors.

sclang_config.yaml options

- verbosity: 1       # sets verbosity for sclang
- verbosity-lexer: 3 # sets verbosity for the lexer
- verbosity-scdoc: 3 # sets verbosity for SCDoc

This 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).

SC Language controls

New primitives (on LanguageConfig) to get and set the verbosity levels per component. (.getLexerVerbosity, etc.)
Setter for sclang overall 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)?

Other implementation details

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?

mossheim/sclangOutput.md