Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Paranoid::Debug(3)    User Contributed Perl Documentation   Paranoid::Debug(3)

NAME
       Paranoid::Debug - Trace message support for paranoid programs

VERSION
       $Id: lib/Paranoid/Debug.pm, 2.07	2019/01/30 18:25:27 acorliss Exp $

SYNOPSIS
	 use Paranoid::Debug;

	 PDEBUG	       = 1;
	 PDMAXINDENT   = 40;
	 PDPREFIX      = sub { scalar localtime	};
	 pdebug("starting program", 1);
	 foo();

	 sub foo {
	   pdebug("entering foo()", 2);
	   pIn();

	   pdebug("someting happened!",	2);

	   pOut();
	   pdebug("leaving w/rv: $rv", 2):
	 }

	 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 pIn and pOut 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.

   EXPORT TARGETS
       Only PDEBUG, pdebug, pIn, and pOut are exported by default.  All	other
       functions and constants can be exported with the	:all tag set.

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.

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.

   PDMAXINDENT
       PDMAXINDENT is an lvalue	subroutine which is initially set to 60, 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.

   PDPREFIX
       PDPREFIX	is also	an lvalue subroutine and is set	by default to a	code
       reference that returns as a string the standard prefix for debug
       messages:

	 [PID -	DLEVEL]	Subroutine:

       Assigning another reference to a	subroutine or string can override this
       behavior.  The only argument that will be passed	to any such routine
       will be the name	of the calling subroutine.

   pderror
	 pderror("error	msg");

       This function prints the	passed message to STDERR.

   pdebug
	 pdebug("debug statement", 3);
	 pdebug("debug statement: %s %2d %.3f",	3, @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!", 3);

       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.

DEPENDENCIES
       Paranoid

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	licensed under the same	terms as Perl, itself.	Please
       see http://dev.perl.org/licenses/ for more information.

       (c) 2005	- 2017,	Arthur Corliss (corliss@digitalmages.com)

perl v5.32.0			  2019-02-02		    Paranoid::Debug(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONSTANTS | SUBROUTINES/METHODS | DEPENDENCIES | BUGS AND LIMITATIONS | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Paranoid::Debug&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help