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.08	2020/12/31 12:10:06 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.

IMPORT LISTS
       This module exports the following symbols by default:

	   PDEBUG pdebug pIn pOut

       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.

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	is an lvalue subroutine	that contants 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 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	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)

perl v5.32.1			  2020-12-31		    Paranoid::Debug(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | IMPORT LISTS | 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+13.0-RELEASE+and+Ports>

home | help