Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Badger::Debug(3)      User Contributed Perl Documentation     Badger::Debug(3)

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.

perl v5.24.1			  2010-06-22		      Badger::Debug(3)

NAME | SYNOPSIS | DESCRIPTION | IMPORT OPTIONS | DEBUGGING METHODS | DATA INSPECTION METHODS | MISCELLANEOUS METHODS | PACKAGE VARIABLES | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Badger::Debug&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help