Provided by: libbadger-perl_0.16-3_all 
NAME
Badger::Debug - base class mixin module implement debugging methods
SYNOPSIS
package Your::Module;
use Badger::Debug
default => 0; # default value for $DEBUG and DEBUG
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;
}
package main;
use Your::Module;
Your::Module->some_method; # no output, debugging off by default
Your::Module->debugging(1); # turns runtime debugging on
Your::Module->some_method; # [Your::Module line 13] Second Message
DESCRIPTION
This mixin module implements a number of methods for debugging. Read "The Whole Caboodle"
if you just want to get started quickly. Read "Picky Picky Picky" if you want to get all
picky about what you want to use or want more information on the individual features.
Note that all of the debugging methods described below work equally well as both object
and class methods even if we don't explicitly show them being used both ways.
# class method
Your::Module->debug('called as a class method');
# object method
my $object = Your::Module->new;
$object->debug('called as an object method');
The Whole Caboodle
The default import option is the all-in-one option that enables all debugging features.
The value you specify with it will be used as the default debugging status. Use 0 if you
want debugging off by default, or any true value if you want it on.
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
The "Badger::Debug" module allow you to be more selective about what you want to use.
This section described the individual debugging methods and the DEBUG and $DEBUG flags
that can be used to control debugging.
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;
}
IMPORT OPTIONS
All of the debugging methods can be imported selectively into your module. For example:
use Badger::Debug 'debug debugging debug_caller';
The following import options are also provided.
default
Used to set the default debugging value and import various debugging methods and flags.
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
Used to define a $DEBUG variable in your module. A default value should be specified
which will be used to set the $DEBUG value if it isn't already defined.
use Badger::Debug
'$DEBUG' => 0; # debugging off by default
print $DEBUG; # 0
DEBUG
Used to define a "DEBUG" constant in your module. If the $DEBUG package variable is
defined then the "DEBUG" constant will be set to whatever value it contains. Otherwise it
will be set to the default value you provide.
use Badger::Debug
'DEBUG' => 0; # debugging off by default
print DEBUG; # 0
modules
This option can be used to set the $DEBUG value true in one or more packages. This
ensures that any debugging will be enabled in those 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
This option can be used to construct a specialised dump() method for your module. The
method is used to display nested data in serialised text form for debugging purposes. The
default dump() method for an object will display all items stored within the object. The
"dumps" import option can be used to limit the dump to only display the fields specified.
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
Either of these (depending on your spelling preference) can be used to enable colourful
(or colorful) debugging.
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
Imports all of the debug(), debugging(), debug_up(), debug_caller(), debug_callers and
debug_args() methods.
:dump
Imports all of the dump(), dump_ref(), dump_hash(), dump_list(), dump_text(), dump_data()
and dump_data_inline() methods.
DEBUGGING METHODS
debug($msg1, $msg2, ...)
This method can be used to generate debugging messages.
$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, ...)
This method provides a "printf()"-like wrapper around debug().
$object->debugf('%s is %s', e => 2.718); # e is 2.718
debug_up($n, $msg1, $msg2, ...)
The debug() method generates a message showing the file and line number from where the
method was called. The "debug_up()" method can be used to report the error from somewhere
higher up the call stack. This is typically used when you create your own debugging
methods, as shown in the following example.
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)
This method is a wrapper around debug() that allows you to specify a different location to
be added to the message generated.
$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()
Prints debugging information about the current caller.
sub wibble {
my $self = shift;
$self->debug_caller;
}
debug_callers()
Prints debugging information about the complete call stack.
sub wibble {
my $self = shift;
$self->debug_callers;
}
debug_args()
Prints debugging information about the arguments passed.
sub wibble {
my $self = shift;
$self->debug_args(@_);
}
debugging($flag)
This method of convenience can be used to set the $DEBUG variable for a module. It can be
called as a class or object method.
Your::Module->debugging(1); # turn debugging on
Your::Module->debugging(0); # turn debugging off
debug_modules(@modules)
This method can be used to set the $DEBUG true in one or more modules. Modules can be
specified as a list of package names, a reference to a list, or a whitespace delimited
string.
Badger::Debug->debug_modules('Your::Module::One Your::Module::Two');
The method is also accessible via the modules import option.
DATA INSPECTION METHODS
These methods of convenience can be used to inspect data structures. The emphasis is on
brevity for the sake of debugging rather than full blown inspection. Use Data::Dumper or
on of the other fine modules available from CPAN if you want something more thorough.
The methods below are recursive, so dump_list(), on finding a hash reference in the list
will call dump_hash() and so on. However, this recursion is deliberately limited to no
more than $MAX_DEPTH levels deep (3 by default). Remember, the emphasis here is on being
able to see enough of the data you're dealing with, neatly formatted for debugging
purposes, rather than being overwhelmed with the big picture.
If any of the methods encounter an object then they will call its dump() method if it has
one. Otherwise they fall back on dump_ref() to expose the internals of the underlying
data type. You can create your own custom dump() method for you objects or use the dumps
import option to have a custom dump() method defined for you.
dump()
Debugging method which returns a text representation of the object internals.
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)
Does The Right Thing to call the appropriate dump method for a reference of some kind.
dump_hash(\%hash)
Debugging method which returns a text representation of the hash array passed by reference
as the first argument.
print STDERR $object->dump_hash(\%hash);
dump_list(\@list)
Debugging method which returns a text representation of the array passed by reference as
the first argument.
print STDERR $object->dump_list(\@list);
dump_text($text)
Debugging method which returns a truncated and sanitised representation of the text string
passed (directly or by reference) as the first argument.
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)
Debugging method which calls the appropriate dump method for the item passed as the first
argument. If it is an object with a dump() method then that will be called, otherwise it
will fall back on dump_ref(), as it will for any other non-object references. Non-
references are passed to the dump_text() method.
print STDERR $object->dump_data($item);
dump_data_inline($item)
Wrapper around dump_data() which strips any newlines from the generated output, suitable
for a more compact debugging output.
print STDERR $object->dump_data_inline($item);
MISCELLANEOUS METHODS
enable_colour()
Enables colourful debugging and error messages.
Badger::Debug->enable_colour;
PACKAGE VARIABLES
$FORMAT
The debug() method uses the message format in the $FORMAT package variable to generate
debugging messages. The default value is:
[<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
The maximum depth that the data inspection methods will recurse to.
$MAX_TEXT
The maximum length of text that will be returned by dump_text().
AUTHOR
Andy Wardley <http://wardley.org/>
COPYRIGHT
Copyright (C) 1996-2009 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.