/ 
Paranoid-2.10
River stage one • 5 direct dependents • 9 total dependents
/ Paranoid::Debug

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)