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.

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.