NAME

Logging::Debug - debugging help

VERSION

This document refers to version 0.1.2 of Logging::Debug, released 2005-06-22.

v0.1.1: in SYNOPSIS, added output example. v0.1.2: corrected code in SYNOPSIS.

SYNOPSIS

Within a module or script:

  use Logging::Debug;

  SetLogfile("MyScript.log", truncate => 1);

  SetDebug(2); # include MsgDebug
  MsgDebug("this is logged");
  MsgInfo ("this is logged");
  MsgError("this is logged");

  SetDebug(1); # exclude MsgDebug (= the default)
  MsgDebug("this is suppressed");
  MsgInfo ("this is logged");
  MsgError("this is logged");

  SetDebug(0); # exclude MsgInfo and MsgDebug
  MsgDebug("this is suppressed");
  MsgInfo ("this is suppressed");
  MsgError("this is logged");

File MyScript.log will contain lines like:

  ----------------------------------------
  2004-12-24 07:34:41
  ----------------------------------------
  D: 2004-12-24 07:34:41 this is logged
  I: 2004-12-24 07:34:41 this is logged
  E: 2004-12-24 07:34:41 this is logged

Within a test script:

  use Logging::Debug;
  ProcessDebugOption();
  SetLogfile("MyScript.log", truncate => 1);

Then interactively call your script like

  perl -w MyScript.t -v 2

and MsgError, MsgInfo and MsgDebug data of all your modules involved will be printed to STDERR.

You may trap the messages for your own processing:

  my $Listener = sub 
  { 
    my ($level, $msg) = @_;
    # process $level and $msg as you like (Error=0, Info=1, Debug=2)
  }
  SetListener($Listener);

You may direct all messages to STDERR:

  SetStdErrListener();

DESCRIPTION

The module supports debugging messages of three levels. To emit a message of a given level, call the respective routine: MsgError (level 0), MsgInfo (level 1) and MsgDebug (level 2).

The module keeps a numeric filter value and suppresses all messages that have a level greater than the filter value. The filter (``debug level'') is set with SetDebug() and retrieved with GetDebug().

Messages that are not suppressed are written to a file (if you called SetLogfile) and passed to a callback (``Listener'') routine (if you called SetListener).

Messages in the file additionally get a prefix character indicating the level (E, I, D), and a time stamp.

The routines are:

GetDebugDefault()

Returns the default level (which is in effect if you did not call SetDebug).

GetDebug()

Returns the current debug level.

SetDebug($level)

Sets the current debug level.

SetListener($Listener)

Sets the listener. $Listener (if non-0) must be a routine which will be called with the level (first argument) and the message (second argument).

SetStdErrListener()

Installs a listener that writes messages to STDERR, prefixed by a character indicating the level (E, I, D), terminated by a linefeed.

ProcessDebugOption()

Processes a ``verbose:i'' command line argument using Getopt::Long. If the argument is non-0, it is set as debug level (SetDebug), and SetStdErrListener() is called.

ProcessDebugOption() is the easy way to control logging output of scripts.

Use like:

  perl -w <script> [-v (1|2)]

SetLogfile($logfilename[, truncate => 1])

Remembers the $logfilename for use in subsequent calls to MsgError etc. If truncate is given and non-0, the file is immediately deleted.

_Msg($level, $msg)

Internal routine that processes messages.

If $level is greater than the current debug level, no action.

If listener has been installed, passes arguments to the listener.

Then, if the logfile name has been set, appends the message to the logfile, including a character prefix for the level and a time-stamp.

For the first message since SetLogfile, writes a header with the time of SetLogfile.

_Msg opens and closes the file for each message - to avoid loss of message if there is a crash.

TODO achieve this more efficiently by forcing output flushing?

If _Msg cannot open the file, it prints a diagnostic message to STDERR and resets the remembered logfile name. Thereafter - as long as you do not call SetLogfile again - _Msg will not try to write subsequent messages to a file.

MsgError($msg)

Processes $msg with level 0.

MsgInfo($msg)

Processes $msg with level 1.

MsgDebug($msg)

Processes $msg with level 2.

LIMITATIONS

The current implementation of this package opens and closes the output file for each message.

The implementation has not been optimized for performance.

The package does not meet a requirement I consider very helpful: being able to completely disable logging output for some modules (the use-case is to enable logging output while programming or testing some ``low-level'' module, but disable noisy MsgDebug output when the module is used in higher level modules).

AUTHOR

  Helmut Steeb
  mailto: helmut(AT)jsteeb.de
  http://www.jsteeb.de/

COPYRIGHT

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.