NAME
   Package::Debug - Add ENV/Config controlled debug tokens to your code

VERSION
   version 0.1.0

SYNOPSIS
   There is a lot of code on "CPAN" that has something like this in it:

       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.

EXPECTED FEATURES
   *   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.

       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.

   *   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.

PERFORMANCE
   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

   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.

   And this will roughly double the cost of calling "DEBUG"

 If you want run time adjustment
       use Package::Debug runtime_switchable => 1;

   This will

   a - not make $DEBUG "readonly" during import.
   b - inject a "DEBUG" "sub" that checks the value of the former.

AUTHOR
   Kent Fredric <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2013 by Kent Fredric
   <[email protected]>.

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