/ 
Blosxom-Debug-0.001
River stage zero No dependents
/ Blosxom::Debug

NAME

Blosxom::Debug - a blosxom helper module and source filter to provide a standardised debug() logging helper to blosxom plugins

SYNOPSIS

# 'use' this module in your plugin
use Blosxom::Debug debug_level => 1;
# (for distribution, you would normally have this statement commented out)

# In your code, add commented out debug(level, message) lines
# debug(1, 'This is a level 1 message, visible if debug_level >= 1');
# debug(2, 'This is a level 2 message, visible if debug_level >= 2');
# Blosxom::Debug automatically uncomments them itself if it is enabled

# If you want to hide such a statement from Blosxom::Debug altogether,
# comment out with more than one hash e.g.
## debug(1, 'This message won't show up in your webserver log!');

DESCRIPTION

Blosxom::Debug is a perl module to provide simple standardised debug logging facilities to blosxom plugins. It exports a debug() function of the form:

debug($level, $message);

which logs $message to your webserver log if $level is greater than or equal to the debug_level specified in your 'use' statement.

So the following statement:

debug(1, 'This is a level 1 message, visible only if debug_level >= 1');

will show up in your webserver log if you do a:

use Blosxom::Debug debug_level => 1;

but not if you do:

use Blosxom::Debug debug_level => 0;

In the latter case, however, all your debug statements are still all executed, it is just that the output is suppressed because the debug_level is too low. There is therefore a small runtime overhead incurred, which you would probably prefer to avoid unless you're debugging.

For this reason, Blosxom::Debug is also a perl source filter which actively uncomments debug statements if enabled. This allows you to distribute plugins including:

# use Blosxom::Debug debug_level => 1

# and then later on in your plugin ...
# debug(1, "This is a level 1 message");

with both the use statement and all your debug statements commented out, and therefore incurring no runtime overhead in production.

When you run into a problem you need to debug, you then simply uncomment just the 'use' statement, which activates all (single-hash) commented debug statements at runtime i.e.

use Blosxom::Debug debug_level => 1

# and this debug statement will now be invoked, even though commented
# debug(1, "This is a level 1 message");

Note that your debug statements therefore must be valid perl, since they actually are executed as normal.

To actually hide debug statements from Blosxom::Debug, you must comment them out with more than one hash e.g.

## debug(1, "This message is hidden, no matter what the debug_level");

BUGS AND LIMITATIONS

Commented-out debug() lines must currently occur at the beginning of a line i.e. you can't do things like:

$foo = 1;    # debug(1, "setting \$foo");

SEE ALSO

Blosxom: http://blosxom.sourceforge.net/

AUTHOR

Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/

LICENSE

Copyright 2007, Gavin Carr.

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