Simple Logging Library Files

Simple Logging Library
======================

The simple logging library says it all really. It is a logging library for cpp that is simple to use
while being fairly small. If you are expecting an all singing, all dancing logging package then you
will need to look elsewhere, the whole idea of this package is simplicity.

It consists of two files, logging.cpp and logging.h which can be included in your application, just
copy them into your source directory and add them to your project in whatever way rocks your boat.

The logging library is released under the GPL V3.0 and a copy is included in the file you have 
downloaded. There are four downloadable files logging.zip, logging.7z, logging.tar.gz and 
logging.tar.bz. They all have the same files so download whichever you wish. All of them also
include the documentation in html format in a separate docs.(zip/7z/tar.gz/tar.bz) file. Documentation
has been created by Doxygen.

To Use
======

The Logging interface consists of a Logger and a set of Writer's. The Logger is a singleton
and as such cannot be constructed by a normal constructor. To access the logger you use
the static get() method.

Logger::get();

Users can register one or many writers for each required level. For instance a CoutWriter and a 
FileWriter can be specified for the debug level, a DailyRollingFileWriter for the error level, a 
CoutWriter for the info level etc. This gives a lot of flexibility for logging. A base severity 
level can also be set barring any writers with levels below this from receiving messages.

Writers are registered with the logger using one of the addWriter() methods.

Logger::get().addWriter(debug, IWriter);
Logger::get().addWriter("cout", debug);

There are also several 'helper' methods in Logger to enable addition of writers.

The first adds a supplied writer to the logger at errorLevel debug and the second utilises the
Writerfactory to create a writer of type 'cout', or a CoutWriter, and adds it for the debug level.
There are several predefined writers:
- CoutWriter which writes logging messages to the console.
- FileWriter which writes logging messages to a specified file.
- SizedRollingFileWriter which writes logging messages to a file, but the file rolls over
  when it reaches a specified maximum size.
- DailyRollingFileWriter which writes logging messages to a file that rolls over to a new
  file daily, at local midnight.
- RunRollingFileWriter which writes logging messages to a file that rolls over to a new
  file when a new run commences.
- BatchRollingFileWriter which writes logging messages to a file that rolls over to a new
  file when a new batch name is specified.
- DirectedWiter which send logging messages to a user specified function passed to the writer.
 *
It is possible to create your own writers by subclassing IWriter or any one of it's existing
subbclasses such as FileWriter. These can be added to the WriterFactory if required using the
WriterFactory::Register() method.

The WriterFactor class that can be used to generate writers. This utilises the
 createWriter(string) method to create new writers. Available types are
 - "cout"
 - "file"
 - "sized"
 - "daily"
 - "run"
 - "batch"
 - "directed"
 *
Messages are sent using the message() method and generally it is called using:
Logger::get()->message(errorLevel, "message");

There are seven different logging levels available, and they are defined in the @link ErrorLevel @endlink enum. Most
of these are similar to other logging classes, however there is another level, @a application, which is generally used
to pass information messages to the application. This level is higher than any other allowing the user to set a very
high severity level, while still passing messages to the application where needed. Actually when I wrote this I needed
to send state messages to a text field within the application, hence the DirectedWriter class which takes a function
as a parameter allowing the user to send messages via the function to wherever needed within the application.
The levels are:
 - trace - the lowest level, just for trace purposes.
 - debug - generally used for debugging messages.
 - info - general information
 - warning - non-fatal errors such as configuration errors that have default options.
 - error - possibly fatal errors such as configuration errors that do not have default options..
 - fatal - application is about to crash!!
 - application - used for special application messages rather than error messages.

Example code :

  // create a cout writer with WriterFactory
  WriterPtr writer = WriterFactory::get()->CreateWriter("cout");
  writer.get()->setFilename("log", "file", "test", "log");
  Logger::get()->addWriter(application, writer);
  // create writers using the Logger helper methods.
  Logger::get()->addWriter("file", debug, "log", "debug", "file", "log");
  Logger::get()->addWriter("daily", error, "log", "error", "daily", "log");
  Logger::get()->addWriter("run", error, "log", "error", "run", "log");
  Logger::get()->addSizedWriter(error, 100, "log", "error", "sized", "log");
  Logger::get()->addDirectedWriter(application, &writeMessage); // writeMessage is a function somewhere within the application software.
 *
  // send messages.
  string date;
  date += "[";
  date += IWriter::getDate();
  date += IWriter::getTime();
  date += "] ";
  Logger::get()->message(application, date + "Application level file logging");
  Logger::get()->message(application, date + "Application second line of logging");
  Logger::get()->message(debug, date + "Debug message ?");
  Logger::get()->message(error, date + "Error message 2");
 

Hope you find it useful.
Simon Meaden