Paranoid::Debug - Trace message support for paranoid programs
$Id: lib/Paranoid/Debug.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $
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");
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.
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
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.
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.
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 = 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 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("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.
Paranoid
Carp
pderror (and by extension, pdebug) will generate errors if STDERR is closed elsewhere in the program.
Arthur Corliss (corliss@digitalmages.com)
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)
To install Paranoid, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Paranoid
CPAN shell
perl -MCPAN -e shell install Paranoid
For more information on module installation, please visit the detailed CPAN module installation guide.