NAME

PTools::Verbose - A light-weight class to provide verbose output levels

VERSION

This document describes version 0.01, released October, 2004

SYNOPSIS

 use PTools::Verbose;

 $verbose = new PTools::Verbose( $verboseLevel );
 $verbose = new PTools::Verbose( $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.

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

DESCRIPTION

Constructor

new ( VerboseLevel [, IndentLevel ] )

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

VerboseLevel

The required VerboseLevel is used to establish the overall level of output text 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 output text.

When using this parameter, the character indent is calculated by multiplying the Level (passed via the verbose 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

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

This method is designed to be used in various situations.

 .  to generate verbose output on STDERR
 .  to test if a verbose flag was enabled
 .  to determine what level of verbose 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 verbose 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 verbose 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 output text. The level of endent is calculated as a function of the IndentLevel setting and the Verbose Level passed to the verbose method by the calling script/module.

setLevel ( VerboseLevel )

Use the setLevel method to determine the amount of output text 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

is

isSet

isTrue

level

lvl

only

print

prn

put

set

test

true

warn

These method names are all aliases for the above 'verbose' 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::Verbose;

 my $verbose      = new PTools::Verbose( @ARGV );
 my $verboseLevel = $verbose->getLevel;    # passed from cmd-line
 my $indentLevel  = $verbose->getIndent ||0;

 print "\n";
 if (defined $verboseLevel) {
     print "Verbose level  = '$verboseLevel'\n";
 } else {
     print "Verbose 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 ($verbose->isSet) {
    print "Indent level = '$indentLevel'\n";
    print "\n";
 }

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

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

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

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

INHERITANCE

This class inherits from the Debug class.

SEE ALSO

See Debug.

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.