USAGE HINT

NAME

Util::Logger - write messages to screen or file

SYNOPSIS

  use Util::Logger;

  # simple example using default options
  my $log = Util::Logger->new();
  $log->print('INFO',
              'You will see this as well as WARN, ERROR and FATAL messages');

  # let´s play with the log levels...
  my $log_less = Util::Logger->new({ loglevel => 'WARN' });
  $log_less->print('INFO', 'This message won´t be logged.');
  $log_less->print('WARN', 'This message will be logged.');
  $log_less->print('ERROR', 'This message will be logged.');

  # write log file and disable line wrapping that is mainly for screen display
  my $log_to_file = Util::Logger->new({ loglevel => 'ERROR',
                                        file => '/tmp/stuff.log',
                                        wrap => 0 });

DESCRIPTION

This class allows you to print messages to the screen or into a file. With each call to the print method you will (besides the actual message) pass a category name. The categories have a certain order of severity and by adjusting the log level you can easily control the verbosity of your program without touching your code.

The log level categories in descending severity:

  FATAL
  ERROR
  WARN
  INFO
  MORE
  DEBUG

USAGE HINT

All methods of this class (except of the constructor new) are meant to be called on an instance only (see SYNOPSIS). Do NOT call them as class methods. Perl gives you the freedom to do so, but don´t blame me for the result; you have been warned.

ATTRIBUTES

ERR: methods that fail and therefore return undef will put an error message into this variable which can be accessed via $instance-{ERR}>.

METHODS

new([<hashRef>])

Constructor. You can pass a hash refernece to customize the logger´s behaviour. Supported hash keys:

loglevel => <string>: Default: 'INFO'. Only messages of this category or a more severe one will be printed.
file => <string>: Default: undef. If the given filename exists and is writable, messages will be appended. Otherwise a new file is created at the given location. If that fails, messages are printed to the screen.
wrap => <number>: Default: 80. Defines the number of columns that can be printed into a line before a newline character is inserted; this is useful when writing to the screen. If set to 0 then lines won´t be wrapped at all, which is recommended for logging to a file.
print_category => <boolean>: Default: 1. Toggles printing of the category name in front of the actual message.
print_timestamp => <boolean>: Default: 0. Toggles printing of a timestamp in front of the actual message, which is recommended for logging to a file.
seperator => <string>: Default: ' | '. Sets the string that is used to seperate a log enty´s components (timestamp, category, message text) from each other.

flushWarnings

Returns an array containing the warnings produced by methods of this class. These warnings do not indicate that something is wrong with the program but rather are informative messages that something happended that the user might not have expected. Thus, you're free to ignore these warnings but maybe you should keep an eye on them while developing a program based on this logger. The internal list of warnings will be erased (`flushed') after calling this method.

print(<string> category, <string> message)

Logs the message if its category is high enough for the current loglevel. If not, the message will be discarded. If the given category is not valid, a warning will be issued and the current loglevel will be used instead. Newline characters in message are not allowed and will be replaced by tabs.

Returns undef if an error occured, true otherwise.

TODO

- use existing namespace, e.g. Log::Dual Log::Levels

- add convenience methods like info($text) as shortcut for print('INFO', $text)

- add setLevel() for readjustment of logging level

- allow logging to screen _and_ file simultaneously

- dto. and allow different settings, loglevels etc.

AUTHOR

Joachim Jautz

http://www.jay-jay.net/contact.html