This file offers a simple facility for producing "verbose logging" of internal behaviour of algorithms. This is likely to be of interest to developers; the logging messages may also please anyone curious to know what is happening "behind the scenes".
There is a global "verbosity level": a non-negative integer whose default value is 0. Verbose logging messages specify the lowest level at which they will appear: e.g. a level-2 message will not appear if the global verbosity level is 0 or 1, but will appear if the level is 2 or higher.
There is just one constructor:
VerboseLog(FnName) -- create an output stream for verbose log messages
There is just one query:
SetVerbosityLevel(n) -- set the global verbosity level to n (non-negative integer); returns value of previous verbosity level.
IsVerbosityLevel(n) -- true iff the verbose level is greater than or equal to n (positive integer).
There is just one operation: let VERBOSE be a VerboseLog object
VERBOSE(n) -- produces an ostream onto which a single-line verbose log message can be printed.
NOTE a verbose logging command will always evaluate its arguments (even if the logging
command will produce no output because the global level is too low). It is best not to perform
costly operations to produce logging output; if you must do so, then place a block of code inside
the then-part of an if (IsVerbosityLevel(...)) {...} construct!
Currently this is a very simplistic first implementation.
There are 3 globals:
DevNull is an ostream which never prints anything (it just discards everything)
VerboseLog::ourNestingDepth keeps track of nesting depth (value is indicated in log messages)
VerboseLog::ourVerbosityLevel only messages up to this level are printed
Too simple?
Ideally the prefix containing fn name (and total nesting depth) should be
printed at the start of each verbose log line; currently, it is printed
just by the call VERBOSE(n) -- this works OK provided that only a
single line is sent to that stream.
The name of DevNull is slightly misleading.
Perhaps later offer a way to suppress verbose logging messages when the nesting depth exceeds a limit?
2016