view release on metacpan or  search on metacpan

Debug.pm  view on Meta::CPAN

    ## debug(1, 'This message won't show up in your webserver log!');


=head1 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");


=head1 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");


=head1 SEE ALSO

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


=head1 AUTHOR

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


=head1 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.

=cut

# vim:ft=perl