The Whole Caboodle

    package Your::Module;

    use Badger::Debug
        default => 0;

The default option imports the debug() and debugging() methods, the $DEBUG package variable (set to the default value you specified unless it's already defined to be something else), and the DEBUG constant subroutine (defined to have the same value as the $DEBUG variable).

In your module's methods you can call the debug() method to generate debugging messages. You can use the DEBUG constant or the $DEBUG variable as a condition so that messages only get displayed when debugging is enbled.

    sub some_method {
        my $self = shift;

        # DEBUG is a compile-time constant, so very efficient
        $self->debug("First Message") if DEBUG;

        # $DEBUG is a runtime variable, so more flexible
        $self->debug("Second Message") if $DEBUG;
    }

The DEBUG constant is resolved at compile time so it results in more efficient code. When debugging is off, Perl will completely eliminate the first call to the debug() method in the above example. The end result is that there's no performance overhead incurred by including debugging statements like these.

The $DEBUG package variable is a little more flexible because you can change the value at any point during the execution of your program. You might want to do this from inside the module (say to enable debugging in one particular method that's causing problems), or outside the module from a calling program or another module. The debugging() method is provided as a convenient way to change the $DEBUG package variable for a module.

    Your::Module->debugging(0);     # turn runtime debugging off
    Your::Module->debugging(1);     # turn runtime debugging on

The downside is that checking the $DEBUG variable at runtime is less efficient than using the DEBUG compile time constant. Unless you're working on performance critical code, it's probably not something that you should worry about.

However, if you are the worrying type then you can use "Badger::Debug" to get some of the best bits of both worlds. When your module is loaded, both DEBUG and $DEBUG will be set to the default value you specified unless $DEBUG is already defined. If it is defined then the DEBUG constant will be set to whatever value it has. So if you define the $DEBUG package variable before loading the module then you'll be able to enable both run time and compile time debugging messages without having to go and edit the source code of your module.

    $Your::Module::DEBUG = 1;
    require Your::Module;

Alternately, you can let "Badger::Debug" do it for you. The modules import option allows you to specify one or more modules that you want debugging enabled for.

    use Badger::Debug
        modules => 'My::Module::One My::Module::Two';

    use My::Module::One;        # both runtime and compile time
    use My::Module::Two;        # debugging enabled in both modules

The benefit of this approach is that it happens at compile time. If you do it before you "use" your modules, then you'll get both compile time and run time debugging enabled. If you do it after then you'll get just runtime debugging enabled. Best of all - you don't need to change any of your existing code to load modules via "require" instead of "use"

Picky Picky Picky

In the simplest case, you can import the debug() method into your own module for generating debugging messages.

    package Your::Module;
    use Badger::Debug 'debug';

    sub some_method {
        my $self = shift;
        $self->debug("Hello from some_method()");
    }

In most cases you'll want to be able to turn debugging messages on and off. You could do something like this:

    # initialise $DEBUG if it's not already set
    our $DEBUG = 0 unless defined $DEBUG;

    sub some_method {
        my $self = shift;
        $self->debug("Hello from some_method()") if $DEBUG;
    }

If you use the "unless defined $DEBUG" idiom shown in the example shown above then it will also allow you to set the $DEBUG flag before your module is loaded. This is particularly useful if the module is auto-loaded on demand by another module or your own code.

    # set $DEBUG flag for your module
    $Your::Module::DEBUG = 1;

    # later...
    require Your::Module;       # debugging is enabled

You can also achieve the same effect at compile time using the "Badger::Debug" modules export option.

    use Badger::Debug
        modules => 'Your::Module';  # sets $Your::Module::DEBUG = 1
    use Your::Module;               # debugging is enabled

The advantage of using the $DEBUG package variable is that you can change the value at any point to turn debugging on or off. For example, if you've got a section of code that requires debugging enabled to track down a particular bug then you can write something like this:

    sub gnarly_method {
        my $self = shift;

        local $DEBUG = 1;
        $self->debug("Trying to track down the cause bug 666");

        # the rest of your code...
        $self->some_method;
    }

Making the change to $DEBUG "local" means that it'll only stay set to 1 until the end of the "gnarly_method()". It's a good idea to add a debugging message any time you make temporary changes like this. The message generated will contain the file and line number so that you can easily find it later when the bug has been squashed and either comment it out (for next time) or remove it.

The "Badger::Debug" module has a $DEBUG export hook which will define the the $DEBUG variable for you. The value you provide will be used as the default for $DEBUG if it isn't already defined.

    package Your::Module;

    use Badger::Debug
        'debug',
        '$DEBUG' => 0;

    sub some_method {
        my $self = shift;
        $self->debug("Hello from some_method()") if $DEBUG;
    }

The debugging() method can also be imported from "Badger::Debug". This provides a simple way to set the $DEBUG variable.

    Your::Module->debugging(1);     # debugging on
    Your::Module->debugging(0);     # debugging off

The downside to using a package variable is that it slows your code down every time you check the $DEBUG flag. In all but the most extreme cases, this should be of no concern to you whatsoever. Write your code in the way that is most convenient for you, not the machine.

WARNING: Do not even begin to consider entertaining the merest thought of optimising your code to make it run faster until your company is on the verge of financial ruin due to your poorly performing application and your boss has told you (with confirmation in writing, countersigned by at least 3 members of the board of directors) that you will be fired first thing tomorrow morning unless you make the code run faster RIGHT NOW.

Another approach is to define a constant DEBUG value.

    package Your::Module;

    use Badger::Debug 'debug';
    use constant DEBUG => 0;

    sub some_method {
        my $self = shift;
        $self->debug("Hello from some_method()") if DEBUG;
    }

This is an all-or-nothing approach. Debugging is on or off and there's nothing you can do about it except for changing the constant definition in the source code and running the program again. The benefit of this approach is that DEBUG is defined as a compile time constant. When DEBUG is set to 0, Perl will effectively remove the entire debugging line at compile time because it's based on a premise ("if DEBUG") that is known to be false. The end result is that there's no runtime performance penalty whatsoever.

"Badger::Debug" also provides the DEBUG hook if this is the kind of thing you want.

    package Your::Module;

    use Badger::Debug
        'debug',
        'DEBUG' => 0;

    sub some_method {
        my $self = shift;
        $self->debug("Hello from some_method()") if DEBUG;
    }

What makes this extra-special is that you're only specifying the default value for the "DEBUG" constant. If the $DEBUG package variable is defined when the module is loaded then that value will be used instead. So although it's not possible to enable or disable debugging for different parts of a module, you can still enable debugging for the whole module by setting the $DEBUG package variable before loading it.

    # set $DEBUG flag for your module
    $Your::Module::DEBUG = 1;

    # later...
    require Your::Module;       # debugging is enabled

Here's a reminder of the other way to achieve the same thing at compile time using the "Badger::Debug" modules export option.

    use Badger::Debug
        modules => 'Your::Module';  # sets $Your::Module::DEBUG = 1
    use Your::Module;               # debugging is enabled

You can combine the use of both $DEBUG and DEBUG in your code, for a two-level approach to debugging. The DEBUG tests will always be resolved at compile time so they're suitable for low-level debugging that either has a performance impact or is rarely required. The $DEBUG tests will be resolved at run time, so they can be enabled or disabled at any time or place.

    sub some_method {
        my $self = shift;
        $self->debug("Hello from some_method()") if DEBUG;
        $self->debug("Goodbye from some_method()") if $DEBUG;
    }

default

    use Badger::Debug
        default => 0;           # debugging off by default

It imports the debug() and debugging() methods along with the $DEBUG package variable and DEBUG constant.

See "The Whole Caboodle" for further discussion on using it.

$DEBUG

    use Badger::Debug
        '$DEBUG' => 0;           # debugging off by default

    print $DEBUG;                # 0

DEBUG

    use Badger::Debug
        'DEBUG' => 0;            # debugging off by default

    print DEBUG;                 # 0

modules

    use Badger::Debug
        modules => 'My::Module::One My::Module::Two';

    use My::Module::One;        # debugging enabled in both modules
    use My::Module::Two;

Modules that haven't yet been loaded will have both compile time (DEBUG) and run time ($DEBUG) debugging enabled. Modules that have already been loaded will only have run time debugging enabled.

dumps

    package Your::Module;
    use Badger::Debug dumps => 'foo bar baz';
    # ...more code...

    package main;
    my $object = Your::Module->new;
    print $object->dump;            # dumps foo, bar and baz

colour / color

    use Badger::Debug 'colour';

Debugging messages will then appear in colour (on a terminal supporting ANSI escape sequences). See the Badger::Test module for an example of this in use.

:debug

:dump

debug($msg1, $msg2, ...)

    $object->debug("Hello ", "World\n");

It prints all argument to STDERR with a prefix indicating the class name, file name and line number from where the "debug()" method was called.

    [Badger::Example line 42] Hello World

At some point in the future this will be extended to allow you to tie in debug hooks, e.g. to forward to a logging module.

debugf($format, $arg1, $arg2, ...)

    $object->debugf('%s is %s', e => 2.718);    # e is 2.718

debug_up($n, $msg1, $msg2, ...)

    sub parse {
        my $self = shift;

        while (my ($foo, $bar) = $self->get_foo_bar) {
            $self->trace($foo, $bar);               # report line here
            # do something
        }
    }

    sub trace {
        my ($self, $foo, $bar) = @_;
        $self->debug_up(2, "foo: $foo  bar: $bar"); # not here
    }

The "trace()" method calls the debug_up() method telling it to look two levels up in the caller stack instead of the usual one (thus "debug_up(1,...)" has the same effect as "debug(...)"). So instead of reporting the line number in the "trace()" subroutine (which would be the case if we called "debug(...)" or "debug_up(1,...)"), it will correctly reporting the line number of the call to "trace()" in the "parse()" method.

debug_at($info, $message)

    $at->debug_at(
        {
            where => 'At the edge of time',
            line  => 420
        },
        'Flying sideways'
    );

This generates the following debug message:

    [At the edge of time line 420] Flying sideways

Far out, man!

You can change the $FORMAT package variable to define a different message structure. As well as the pre-defined placeholders (see the $FORMAT documentation) you can also define your own custom placeholders like "<server>" in the following example.

    $Badger::Debug::FORMAT = '<server>: <msg> at line <line> of <file>';

You must then provide values for the additional placeholder in the $info hash array when you call the debug_at() method.

    $at->debug_at(
        { server => 'Alpha' },
        'Normality is resumed'
    );

You can also specify a custom format in the $info hash array.

    $at->debug_at(
        { format => '<msg> at line <line> of <file>' },
        'Normality is resumed'
    );

debug_caller()

    sub wibble {
        my $self = shift;
        $self->debug_caller;
    }

debug_callers()

    sub wibble {
        my $self = shift;
        $self->debug_callers;
    }

debug_args()

    sub wibble {
        my $self = shift;
        $self->debug_args(@_);
    }

debugging($flag)

    Your::Module->debugging(1);     # turn debugging on
    Your::Module->debugging(0);     # turn debugging off

debug_modules(@modules)

    Badger::Debug->debug_modules('Your::Module::One Your::Module::Two');

The method is also accessible via the modules import option.

dump()

    print STDERR $object->dump();

You can define your own "dump()" for an object and this will be called whenever your object is dumped. The dumps import option can be used to generate a custom "dump()" method.

dump_ref($ref)

dump_hash(\%hash)

    print STDERR $object->dump_hash(\%hash);

dump_list(\@list)

    print STDERR $object->dump_list(\@list);

dump_text($text)

    print STDERR $object->dump_text($text);

The string will be truncated to $MAX_TEXT characters and any newlines will be converted to "\n" representations.

dump_data($item)

    print STDERR $object->dump_data($item);

dump_data_inline($item)

    print STDERR $object->dump_data_inline($item);

enable_colour()

    Badger::Debug->enable_colour;

$FORMAT

    [<where> line <line>] <msg>

The "<where<gt">, "<line>" and "<msg>" markers denote the positions where the class name, line number and debugging message are inserted. You can embed any of the following placeholders into the message format:

    msg     The debugging message
    file    The name of the file where the debug() method was called from
    line    The line number that it was called from
    pkg     The package that it was called from
    class   The class name of the object that the method was called against
    where   A summary of the package and class
    date    The current date
    time    The current time

If the "class" is the same as the "pkg" then "where" will contain the same value. If they are different then "where" will be set equivalent to "<pkg> (<class>)". This is the case when the debug() method is called from a base class method ("pkg" will be the base class name from where the call was made) against a subclass object ("class" will be the subclass name).

See also the debug_at() method which allows you to specify a custom format and/or additional placeholder values.

$MAX_DEPTH

$MAX_TEXT