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

FreeBSD Manual Pages

  
 
  

home | help
Religion(3)	      User Contributed Perl Documentation	   Religion(3)

NAME
       Religion	- Generate tracebacks and create and install die() and
	warn() handlers.

DESCRIPTION
       This is a second	go at a	module to simplify installing die() and	warn()
       handlers, and to	make such handlers easier to write and control.

       For most	people,	this just means	that if	use "use Religion;" then
       you'll get noticably better error reporting from	warn() and die(). This
       is especially useful if you are using eval().

       Religion	provides four classes, WarnHandler, DieHandler,
       WarnPreHandler, and DiePreHandler, that when you	construct them return
       closures	that can be stored in variables	that in	turn get invoked by
       $SIG{__DIE__} and $SIG{__WARN__}. Note that if Religion is in use, you
       should not modify $SIG{__DIE__} or $SIG{__WARN__}, unless you are
       careful about invoking chaining to the old handler.

       Religion	also provides a	TraceBack function, which is used by a
       DieHandler after	you "die()" to give a better handle on the current
       scope of	your situation,	and provide information	about where you	were,
       which might influence where you want to go next,	either returning back
       to where	you were, or going on to the very last.	[Sorry - Ed.]

       See below for usage and examples.

USAGE
       DieHandler SUB
	       Invoke like this:

		$Die::Handler =	new DieHandler sub {
		       #...
		};

	       where "#..." contains your handler code.	Your handler will
	       receive the following arguments:

		 $message, $full_message, $level, $eval,
				   $iline, $ifile, $oline, $ofile, $oscope

	       $message	is the message provided	to die(). Note that the
	       default addition	of " at	FILE line LINE.\n" will	have been
	       stripped	off if it was present.	If you want to add such	a
	       message back on,	feel free to do	so with	$iline and $ifile.

	       "$full_message) is the message with a scope message added on if
	       there was no newline at the end of $message. Currently, this is
	       not the original	message	that die() tacked on, but something
	       along the lines of " at line 3 of the eval at line 4 of
	       Foo.pl\n"."

	       $eval is	non-zero if the	die() was invoked inside an eval.

	       The rest	of the arguments are explained in the source for
	       Religion::TraceBack. Yes, I need	to document these, but not
	       just now, for they are a	pain to	explain.

	       Whenever	you install a DieHandler, it will automatically	store
	       the current value of $Die::Handler so it	can chain to it. If
	       you want	to install a handler only temporarily, use local().

	       If your handler returns data using "return" or by falling off
	       the end,	then the items returns will be used to fill back in
	       the argument list, and the next handler in the chain, if	any,
	       will be invoked.	Don't fall off the end if you don't want to
	       change the error	message.

	       If your handler exits using "last", then	no further handlers
	       will be invoked,	and the	program	will die immediatly.

	       If your handler exits using "next", then	the next handler in
	       the chain will be invoked directly, without giving you a	chance
	       to change its arguments as you could if you used	"return".

	       If your handler invokes die(), then die() will proceed as if no
	       handlers	were installed.	If you are inside an eval, then	it
	       will exit to the	scope enclosing	the eval, otherwise it will
	       exit the	program.

       WarnHandler SUB
	       Invoke like this:

		$Warn::Handler = new WarnHandler sub {
		       #...
		};

	       For the rest of its explanation,	see DieHandler,	and subsitute
	       warn() for die(). Note that once	the last DieHandler completes
	       (or "last" is invoked) then execution will return to the	code
	       that invoked warn().

       DiePreHandler SUB
	       Invoke like this:

		$Die::PreHandler = new DiePreHandler sub {
		       #...
		};

	       This works identically to $Die::Handler,	except that it forms a
	       separate	chain that is invoked before the DieHandler chain.
	       Since you can use "last"	to abort all the handlers and die
	       immediately, or change the messages or scope details, this can
	       be useful for modifying data that all future handlers will see,
	       or to dispose of	some messages from further handling.

	       This is even more useful	in $Warn::PreHandler, since you	can
	       just throw away warnings	that you know aren't needed.

       WarnPreHandler SUB
	       Invoke like this:

		$Warn::PreHandler = new	WarnPreHandler sub {
		       #...
		};

	       This works identically to $Warn::Handler, except	that it	forms
	       a separate chain	that is	invoked	before the WarnHandler chain.
	       Since you can use "last"	to abort all the handlers and return
	       to the program, or change the messages or scope details,	this
	       can be useful for modifying data	that all future	handlers will
	       see, or to dispose of some messages.

	       This is very useful, since you can just throw away warnings
	       that you	know aren't needed.

EXAMPLES
       A dialog	error message:
		$Die::Handler =	new DieHandler sub {
		   my($msg,$fmsg,$level,$eval) = @_;
		   if($eval) {
			       # if we are in an eval, skip to the next	handler
			       next;
		       } else {
			       # show a	message	box describing the error.
			       print "ShowMessageBox $fmsg";

			       # force the program to exit
			       exit 0;
			       next;
		       }
		};

       A handler that changes die() messages back to the original format
		local($Die::Handler) = new DieHandler sub {
		   my($msg,$fmsg,$level,@trace)	= @_;

		       $fmsg = $msg . ((substr($msg,-1,1) ne "\n") ?
						" at $trace[2] line $trace[1].\n"
						: "");
		       return ($msg,$fmsg);
		};

       A warn handler that does	nothing.
		$Warn::Handler = new WarnHandler sub {next;};

       A warn prehandler that throws away a warning.
		$Warn::PreHandler = new	WarnPreHandler sub {
		       my($msg,$fmsg,$level,$eval) = @_;
		       if($msg =~ /Use of uninitialized/) {
			       last;
		       }
		       next;
		};

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 287:
	   Unterminated	C<...> sequence

perl v5.24.1			  1995-10-09			   Religion(3)

NAME | DESCRIPTION | USAGE | EXAMPLES | POD ERRORS

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

home | help