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");
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.
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
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.
pderror("error msg");
This function prints the passed message to STDERR.
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();
This function causes all subsequent pdebug messages to be indented by one additional space.
pOut();
This function causes all subsequent pdebug messages to be indented by one less space.
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(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.
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)
Copyright © 1997 - 2019, Arthur Corliss, all rights reserved.