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.

cpanm Blosxom::Debug

perl -MCPAN -e shell
install Blosxom::Debug