Often it is useful to be able to vary the amount and detail of text produced by a program, for example to get more detailed information when debugging. LIBATOMS makes use of a global verbosity stack to control the amount of output produced by its subroutines and functions. The possible values, in increasing order, of verbosity are: ERROR=-10, SILENT=-1, NORMAL=0, VERBOSE=1, NERD=2 and ANAL=3. Printing interfaces for objects normally print the their own structure at some level of detail, and contained substructures at a lower level of detail. Other subroutines normally print their output at some detail level, and request lower level subroutines to print at a lower detail level. You can set a verbosity minimum level that does not allow subroutines to lower the verbosity level, so that lower level routines and structures always report at the requested detail level or higher.
The initial value at the top of the verbosity stack is set by system_initialise() (the default is NORMAL but this can be overidden with an optional argument). The stack can be modified by calling push_verbosity(val), push_verbosity_increment(n), or push_verbosity_decrement(n) to place a new value on the top of the stack, and pop_verbosity() to revert to the previous value. The current value of the verbosity stack can be queried with current_verbosity(). The initial verbosity cascade status is set to false, and can be changed with verbosity_set_minimum() and revert to the previous value with verbosity_unset_minimum().
Here are some examples:
This behaviour is implemented for printing interfaces as in this example
Printing of low level entities (strings, numbers, arrays) take an optional verbosity parameter that sets the minimum verbosity level at which that print will actually occur. Functions that want to produce output at different levels of detail (e.g. the minim() function) can use this verbosity parameter to output more information when the verbosity level is high. To modify output of a structure, the verbosity stack must be used. For example:
These controls can be used from upper level programs as follows:
