Provided by: libparanoid-perl_2.10-1_all 
NAME
Paranoid::Debug - Trace message support for paranoid programs
VERSION
$Id: lib/Paranoid/Debug.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $
SYNOPSIS
use Paranoid::Debug;
PDEBUG = 1;
PDMAXINDENT = 40;
PDPREFIX = sub { scalar localtime };
pdebug("starting program", PDEBUG1);
foo();
# New method
sub foo {
my $foo = shift;
my @bar = shift;
my $rv;
subPreamble(PDEBUG1, '$@', $foo, @bar);
# Miscellaneous code...
pdebug("someting happened!", PDEBUG2);
# More miscellaneous code...
subPostamble(PDEBUG1, '$', $rv);
return $rv;
}
# Old method
sub foo {
my $foo = shift;
my @bar = shift;
my $rv;
pdebug('entering w/(%s)(%s)', PDEBUG1, $foo, @bar);
pIn();
# Miscellaneous code...
pdebug("someting happened!", PDEBUG2);
# More miscellaneous code...
pOut();
pdebug('leaving w/rv: %s', PDEBUG1, $rv);
return $rv;
}
pderror("error msg");
DESCRIPTION
The purpose of this module is to provide a useful framework to produce debugging output.
With this module you can assign a level of detail to pdebug statements, and they'll only
be displayed to STDERR when PDEBUG is set to that level or higher. This allows you to
have your program produce varying levels of debugging output.
Using the subPreamble and subPostamble functions at the beginning and end of each function
will cause debugging output to be indented appropriately so you can visually see the level
of recursion.
NOTE: All modules within the Paranoid framework use this module. Their debug levels range
from 9 and up. You should use 1 - 8 for your own modules or code. PDEBUG1 - PDEBUG8
exists for those purposes.
IMPORT LISTS
This module exports the following symbols by default:
PDEBUG pdebug pIn pOut subPreamble subPostamble PDEBUG1 .. PDEBUG8
The following specialized import lists also exist:
List Members
--------------------------------------------------------
constants PDEBUG1 PDEBUG2 PDEBUG3 PDEBUG4 PDEBUG5
PDEBUG6 PDEBUG7 PDEBUG8
all @defaults @constants
pderror PDPREFIX PDLEVEL1 PDLEVEL2
PDLEVEL3 PDLEVEL4 PDMAXINDENT
CONSTANTS
PDEBUG1 .. PDEBUG8
There are eight constants exported by default for use by developers that allow for up to
eight levels of diagnostic output. None of these levels are used by internal Paranoid
code, they are reserved for use by third parties.
PDLEVEL1 .. PDLEVEL4
These constants are not intended for use by other modules, rather the exist for the
internal debug levels used by all Paranoid::* modules. These levels are all higher than
what PDEBUG* to allow the developer to have as much control over their verbosity as
possible, but without the Paranoid diagnostics adding unwanted noise.
SUBROUTINES/METHODS
PDEBUG
PDEBUG is an lvalue subroutine which is initially set to 0, but can be set to any positive
integer. The higher the number the more pdebug statements are printed.
PDPREFIX
PDPREFIX = sub {
# Old default Prefix to use with debug messages looks like:
#
# [PID - $dlevel] Subroutine:
#
my $caller = shift;
my $indentation = shift;
my $oi = $indentation;
my $maxLevel = PDMAXINDENT;
my $prefix;
# Cap indentation
$indentation = $maxLevel if $indentation > $maxLevel;
# Construct the prefix
$prefix = ' ' x $indentation . "[$$-$oi] $caller: ";
return $prefix;
};
PDPREFIX is an lvalue subroutine that contains a code reference to a subroutine that
returns an appropriate prefix for debug messages. The default subroutine prints an
indented string (indented according to depth on the call stack) that prints the process
PID, debug level, and the current routine/or method that pdebug was called in.
PDMAXINDENT
PDMAXINDENT is an lvalue subroutine which is initially set to 40, but can be set to any
integer. This controls the max indentation of the debug messages. Obviously, it wouldn't
help to indent a debug message by a hundred columns on an eighty column terminal just
because your stack depth gets that deep.
pderror
pderror("error msg");
This function prints the passed message to STDERR.
pdebug
pdebug("debug statement", PDEBUG3);
pdebug("debug statement: %s %2d %.3f", PDEBUG3, @values);
This function is called with one mandatory argument (the string to be printed), and an
optional integer. This integer is compared against PDEBUG and the debug statement is
printed if PDEBUG is equal to it or higher.
The return value is always the debug statement itself. This allows for a single statement
to produce debug output and set variables. For instance:
Paranoid::ERROR = pdebug("Something bad happened!", PDEBUG3);
As an added benefit you can pass a printf template along with their values and they will
be handled appropriately. String values passed as undef will be replaced with the literal
string "undef".
One deviation from printf allows you to specify a placeholder which can gobble up any
number of extra arguments while still performing the "undef" substitution:
pdebug("I was passed these values: %s", 3, @values);
pIn
pIn();
This function causes all subsequent pdebug messages to be indented by one additional
space.
pOut
pOut();
This function causes all subsequent pdebug messages to be indented by one less space.
subPreamble
subPreamble(PDEBUG1, '$@', @_);
This function combines the functionality of pdebug and pIn to mark the entry point into a
given function. It also provides a convenient summarization function to prevent logging
overly long arguments to diagnostic output.
The second argument to this function would be essentially whatever a valid subroutine
prototype would be for your function (see Prototypes in perlsub(3) for more examples). In
addition to the standard prototypes, we also support p as a prototype. This is
essentially the same as a scalar prototype, but instead of printing a summarized excerpt
of its contents, it replaces all characters with * characters. Any argument containing
sensitive information, such as passwords, etc, should use p instead of $.
Summarization is performed in the following manner: any scalar value (excluding
references of any kind) that exceeds 20 characters gets truncated to 20 characters, and
appended with the full number of bytes. Lists merely report how many elements in the
array, and hashes list the number if key/value pairs in the hash. All other types are
passed as-is.
Indentation is adjusted after the initial summarized message.
subPostamble
subPostamble(PDEBUG1, '$', $rv);
This function works the same as subPreamble, but with indentation happening in reverse
order. The prototype should reflect the prototype of the returned value, not the function
arguments. Indentation is set back prior to the the summarized message is printed.
DEPENDENCIES
o Paranoid
o Carp
BUGS AND LIMITATIONS
pderror (and by extension, pdebug) will generate errors if STDERR is closed elsewhere in
the program.
AUTHOR
Arthur Corliss (corliss@digitalmages.com)
LICENSE AND COPYRIGHT
This software is free software. Similar to Perl, you can redistribute it and/or modify it
under the terms of either:
a) the GNU General Public License
<https://www.gnu.org/licenses/gpl-1.0.html> as published by the
Free Software Foundation <http://www.fsf.org/>; either version 1
<https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
<https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
b) the Artistic License 2.0
<https://opensource.org/licenses/Artistic-2.0>,
subject to the following additional term: No trademark rights to "Paranoid" have been or
are conveyed under any of the above licenses. However, "Paranoid" may be used fairly to
describe this unmodified software, in good faith, but not as a trademark.
(c) 2005 - 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 - 2020, Paranoid Inc.
(www.paranoid.com)