Package::Debug - Add ENV/Config controlled debug tokens to your code
version 0.1.0
There is a lot of code on CPAN that has something like this in it:
CPAN
our $DEBUG = $ENV{MY_PACKAGE_NAME_DEBUG};
or something like
sub DEBUG { return if not $ENV{MY_PACKAGE_NAME_DEBUG}; <real debug code> }
or something like:
if( $ENV{MY_PACKAGE_NAME_DEBUG} ) { *DEBUG=sub{ withdebug } } else { *DEBUG=sub { noop } }
These are mostly simple and straight forward, ... however, they artificially limit what you can do, at the cost of making ugly code.
This module aims to implement the common utility, with less fuss:
$ENV{MY_BAZ_DEBUG} = 1; package My::Baz; use Package::Debug; ... sub foo { DEBUG("message"); }
And all the right things should still occur.
Additionally, this module will eventually add a bunch of features, that are by default off, but can be toggled on using environment or configuration files.
Deferrable debug mechanism
The defacto DEBUG() stub when not in a debug environment should be a no-op, or as close to a no-op as possible.
DEBUG()
However, when debugging is turned on, debugging back ends should also be controllable via env/configuaration, and proxy to things like Log::Message and friends.
Per-package debug granularity
Every package will get its own independent DEBUG key, and DEBUG for a class can be toggled with an %ENV key relevant to that class.
%ENV
Global Debugging
In addition to package level granularity, global debugging can also be enabled, while still seeing the individual packages the debug message emanates from.
For the best speed,
use Package::Debug;
This will do its best to produce a no-op sub when debugging is not requested by %ENV
no-op
However, this comes at a price, namely, if you want to turn on debugging in code, you have to either
BEGIN { $ENV{YOUR_PACKAGE_NAME_DEBUG} = 1 } use Your::Package::Name; # debugging is on
Or
BEGIN { $Your::Package::Name::DEBUG = 1 } use Your::Package::Name; # debugging is on
And this will not work:
use Your::Package::Name; $Your::Package::Name::DEBUG = 1; # Modification of Readonly value
This is because for the last example to work, the DEBUG sub would have to check that value every time it was called.
DEBUG
And this will roughly double the cost of calling DEBUG
use Package::Debug runtime_switchable => 1;
This will
$DEBUG
readonly
sub
Kent Fredric <kentfredric@gmail.com>
This software is copyright (c) 2013 by Kent Fredric <kentfredric@gmail.com>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Package::Debug, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Package::Debug
CPAN shell
perl -MCPAN -e shell install Package::Debug
For more information on module installation, please visit the detailed CPAN module installation guide.