Error Handling Unit

Overview

Error Handling Unit is a unit for a facile creating and handling error messages. First it was motivated by the fact that creating a string containing names and current values of variables was not a single-line statement.

Second there was a motivation originating from a parser creation. We sometimes only want to store the information about the (possible) problem, but we do not want to stop the syntax analysis. Therefore we need some mechanism where to (temporarily) store a list of found errors (we would rather call such errors as 'warnings').

Third there was a need to be able to manage the messages in a different (but in enclosed parts of program in a unified) way. For example we sometimes need to flush all the error messages immediatelly to the standard error output. But in a graphical environment we would like to have a list of errors in a separate window (or more windows - each for some part of the system).

The main class that implements these features is error_vector_t. Its instances are called error vectors.

Parametrization

2 Classes of Messages
Error vector recognizes 2 classes of error messages: warnings and errors. They are maintained in a different ways. Warnings represent such errors, which do not seriously threaten the computation. Errors represent such errors, which are really fatal for the computation and a program have to jump out of such dangerous place in a code to another place where the exceptions are catched.
Error Identifiers and Types
Error messages can have identifiers. These identifiers are numbers of type ERR_id_t and they should be unique in your program (therefore you should divide carefully an identificator space between another units). There exists also constant ERR_UNKNOWN_ID, that is equal to zero (you can count on it) and represents unspecified error ID.
Error messages can also have types. Error types are numbers of type ERR_throw_t and they are the numbers passed to the catch block by a throw statement. This error handling unit sometimes throws such exceptions and you can use error types for example to divide behaviour according to the seriousness of the situation (specified when an exception was called).
Callbacks
In a error vector there exist callback functions called 'warning handling callback' and 'error handling callback' (see ERR_psh_callback_t and ERR_thr_callback_t). Their default behaviour is described in a reference manual to ERR_default_psh_callback() and ERR_default_thr_callback() functions.
When use use error_vector_t::set_push_callback() and error_vector_t::set_throw_callback() functions to change the default behaviour of 'warning/error handling callbacks', you preserve some conventions like: 'warning handling callback' will never call throw, 'error handling callback' wiil call throw and moreover it will print some messages on the output (terminal, window, ...), etc.

Usage

The basic usage is the following:
gerr << "I'm a mess" << "age" << " nbr. " << 1 << thr(3,13565);
This causes creating and storing of message "I'm a message nbr. 1" with error ID 13565 and type 3. Then the default 'error handling callback' flushes all messages stored in a memory to the standard error output, clears the memory of messages and calls throw 3;.

By the same token:

gerr << "I'm a mess" << "age" << " nbr. " << 1 << psh(3,13565);
This code causes the end of creation of an error message and message is stored into the list of errors. Then the default 'error handling callback' prints this newly created message to the standard error output and erases a printed message from a memory. Default 'error handling callback' do not use an error type.

Note:
In both - psh and thr: Parameters error type and error ID are optional. If you want to set error ID (e.g. 1777) and you do not want to set the error type, feel free to write 0 instead of error type (e.g. thr(0,1777) ). You can also use preddefined constant ERR_UNKNOWN_TYPE, that is also equal to zero.
Note 2:
Default 'warning/error handling callbacks do not use a list of errors They always store only 1 message and speedily they remove it from a list immediately after printing to the standard error output.
Catching Exceptions:
If you have set 'error handling callback' to throw exceptions (default behaviour) you should also catch these exceptions. To catch an exception produced by terr << thr(), you should use construction
try { ... } catch (ERR_throw_t & err_type) { ... }
The above code should be a wrapper for all commands of DiVinE, which you call in your program. The simplest way is:
int main(int argc, char * argv[])
{
 try
  {
   
  }
 catch (ERR_throw_t & err_type)
  { return err_type; }
 return 0;
}
But you can also create more complex hiearchy of catching exceptions and manipulate them in a various ways. You can also want to move the most of functionality to the 'error handling callback' (that you can set by error_vector_t::set_throw_callback() function). It really depends on a type of application, where you use this unit.

Advanced Usage

There are many functions to access the messages in an error vector. For detailed information about complete interface of error vector see error_vector_t class reference. Here we will discuss only some classes of these advanced methods:

Reference Manual for Library, 2006 developed in ParaDiSe laboratory, Faculty of Informatics, Masaryk University