NAME

PTools::Debug - A light-weight class to provide debug output levels.

VERSION

This document describes version 0.04, released October, 2004

SYNOPSIS

 use PTools::Debug;

 $debug = new PTools::Debug( $verboseLevel );
 $debug = new PTools::Debug( $verboseLevel, $indentLevel );

Each of the following method names are equivalent. There are other aliases for the "level" as shown in the 'Methods' section, below This is intended to aid in semantically meaningful method calls.

 $debug->test( $level );
 $debug->warn( $level, $text );
 $debug->warn( $level, $text, $max );
 if ($debug->isSet) { ... }

Other examples provide for potentially better syntax depending on the given situation. These are equivalent to the above.

 $warn = new PTools::Debug( $verboseLevel, $indentLevel );

 $warn->ifDebug( $level, $text );
 $warn->debug and do { ... }

DESCRIPTION

Constructor

new ( VerboseLevel [, IndentLevel ] )

The new method is called to create a new object that will be used to provide various levels of debug output, based on the overall VerboseLevel set within the object combined with the Level passed into the debug method, below.

VerboseLevel

The required VerboseLevel is used to establish the overall level of debug output that will be generated during a given session or run of a particular script.

IndentLevel

An optional IndentLevel can be used to add message indents for each level of debug message.

When using this parameter, the character indent is calculated by multiplying the Level (passed via the debug method) and the IndentLevel. Therefore, use of small values for both this number and Level is recommended. See the Example section, below, for details.

Methods

debug ( [ Level ] [, Message ] [, MaxLevel ] )

This method is designed to be used in various situations.

 .  to generate debug output on STDERR
 .  to test if a Debug flag was enabled
 .  to determine what level of Debug was enabled

As such there are multiple alias names defined for this particular method. Additional method names can easily be defined by subclassing this module.

Level

When using the debug method (or any of its aliases) to emit a text Message, the Level parameter is expected to be an integer value. This value is tested against the VerboseLevel used when instantiating an object of this class (or set via the setLevel method, below). If the test passes, the specified Message is emitted.

Message

The Message, when specified, is a text string that will be emitted to STDERR. The text will be emitted when the specific Level value (passed via the debug method or one of its aliases) is tested against the overall VerboseLevel (used when instantiating an object of this class, or set via the setLevel method).

MaxLevel

The MaxLevel is an optional parameter that is used to further limit when the specified Message will be emitted. See examples, below.

setIndent ( IndentLevel )

Use the setIndent method at any time to set an IndentLevel that is used to indent debug output. The level of endent is calculated as a function of the IndentLevel setting and the Debug Level passed to the debug method by the calling script/module.

setLevel ( VerboseLevel )

Use the setLevel method to determine the amount of debug output that will be generated during a given run of a script or module that uses this class.

getLevel

Use the getLevel method to obtain the current VerboseLevel setting.

version

Use the version method to obtain the current class version.

and

at

atLevel

check

chk

dbg

if

ifDebug

is

isSet

isTrue

level

lvl

only

print

prn

put

set

test

tell

true

warn

These method names are all aliases for the above 'debug' method. They can be used interchangably to create clean syntax in the invoking script/module, depending on the given situation. Notice the various usage scenarios in the example, below.

EXAMPLE

 #!/opt/perl/bin/perl -w
 use strict;
 use PTools::Debug;

 my $debug       = new PTools::Debug( @ARGV );
 my $debugLevel  = $debug->getLevel;    # passed from cmd-line
 my $indentLevel = $debug->getIndent ||0;

 print "\n";
 if (defined $debugLevel) {
     print "Debug level  = '$debugLevel'\n";
 } else {
     print "Debug level  = <undefined>\n\n";
     print "Usage: $0  [ verboseLevel ] [, indentLevel ]\n";
     print "\n";
     print "Note that a 'verboseLevel' of [ 0 - 6 ] is good for a demo,\n";
     print "and that an 'indentLevel' of [ nul - 4 ] is also good demo.\n";
     print "\n";
 }

 if ($debug->isSet) {
    print "Indent level = '$indentLevel'\n";
    print "\n";
 }

 $debug->if   ( undef, "Level undef"  );
 $debug->and  (     0, "Level 0"      );
 $debug->prn  (     1, "Level 1"      );
 $debug->print(     2, "Level 2"      );
 $debug->print(     2, "Level 2-3", 3 );
 $debug->warn (     3, "Level 3"      );
 $debug->warn (     3, "Level 3-4", 4 );
 $debug->if   (     4, "Level 4"      );

 if ($debug->isSet) {
    if (! $debug->getIndent) {
       $indentLevel = 4;
       $debug->setIndent( $indentLevel );
       print "\nIndent level = '$indentLevel'\n";
    }
    print "\n";
 }

  is $debug( undef, "Level u-*",   2 );
  is $debug(     0, "Level 0-*",   2 );
  is $debug(     1, "Level 1-3",   3 );
  at $debug(     2, "Level 2"      );
  at $debug(     2, "Level 2-2",   2 );
  at $debug(     2, "Level 2-3",   3 );
  at $debug(     3, "Level 3"      );
 chk $debug(     3, "Level 3-4",   4 );
test $debug(     3, "Level 3-5",   5 );

 print "\n" if $debug->isSet;

AUTHOR

Chris Cobb [no dot spam at ccobb dot net]

COPYRIGHT

Copyright (c) 2004-2007 by Chris Cobb. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.