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

FreeBSD Manual Pages

  
 
  

home | help
Log::Report::DispatcheUserrContributed Perl DocLog::Report::Dispatcher::Try(3)

NAME
       Log::Report::Dispatcher::Try - capture all reports as exceptions

INHERITANCE
	Log::Report::Dispatcher::Try
	  is a Log::Report::Dispatcher

SYNOPSIS
	try { ... };	   # mind the ';' !!
	if($@) {	   # signals something went wrong

	if(try {...}) {	   # block ended normally

	my $x =	try { read_temperature() };
	my @x =	try { read_lines_from_file() };

	try { ... }	   # no	comma!!
	   mode	=> 'DEBUG', accept => 'ERROR-';

	try sub	{ ... },   # with comma
	   mode	=> 'DEBUG', accept => 'ALL';

	try \&myhandler, accept	=> 'ERROR-';
	try { ... } hide => 'TRACE';

	print ref $@;	   # Log::Report::Dispatcher::Try

	$@->reportFatal;   # re-dispatch result	of try block
	$@->reportAll;	   # ... also warnings etc
	if($@) {...}	   # if	errors
	if($@->failed) {   # same	# }
	if($@->success)	{  # no	errors	# }

	try { #	something causes an error report, which	is caught
	      failure 'no network';
	    };
	$@->reportFatal(to => 'syslog');  # overrule destination

	print $@->exceptions; #	no re-cast, just print

DESCRIPTION
       The try works like Perl's build-in "eval()", but	implements real
       exception handling which	Perl core lacks.

       The Log::Report::try() function creates this "::Try" dispatcher object
       with name 'try'.	 After the "try()" is over, you	can find the object in
       $@.  The	$@ as "::Try" object behaves exactly as	the $@ produced	by
       "eval", but has many added features.

       The "try()" function catches fatal errors happening inside the BLOCK
       (CODE reference which is	just following the function name) into the
       "::Try" object $@.  The errors are not automatically progressed to
       active dispatchers.  However, non-fatal exceptions (like	info or
       notice) are also	collected (unless not accepted,	see new(accept), but
       also immediately	passed to the active dispatchers (unless the reason is
       hidden, see new(hide))

       After the "try()" has run, you can introspect the collected exceptions.
       Typically, you use wasFatal() to	get the	exception which	terminated the
       run of the BLOCK.

       Extends "DESCRIPTION" in	Log::Report::Dispatcher.

METHODS
       Extends "METHODS" in Log::Report::Dispatcher.

   Constructors
       Extends "Constructors" in Log::Report::Dispatcher.

       $obj->close()
	   Inherited, see "Constructors" in Log::Report::Dispatcher

       Log::Report::Dispatcher::Try->new($type,	$name, %options)
	    -Option	  --Defined in		   --Default
	     accept	    Log::Report::Dispatcher  depend on mode
	     charset	    Log::Report::Dispatcher  <undef>
	     died				     undef
	     exceptions				     []
	     format_reason  Log::Report::Dispatcher  'LOWERCASE'
	     hide				     'NONE'
	     locale	    Log::Report::Dispatcher  <system locale>
	     mode	    Log::Report::Dispatcher  'NORMAL'
	     on_die				     'ERROR'

	   accept => REASONS
	   charset => CHARSET
	   died	=> STRING
	     The exit string or	object ($@) of the eval'ed block, in its
	     unprocessed state.

	   exceptions => ARRAY
	     ARRAY of Log::Report::Exception objects.

	   format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
	   hide	=> REASONS|ARRAY|'ALL'|'NONE'
	     [1.09] see	hide()

	   locale => LOCALE
	   mode	=> 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
	   on_die => 'ERROR'|'PANIC'
	     When code which runs in this block	exits with a die(), it will
	     get translated into a Log::Report::Exception using
	     Log::Report::Die::die_decode().  How serious are we about these
	     errors?

   Accessors
       Extends "Accessors" in Log::Report::Dispatcher.

       $obj->die2reason()
	   Returns the value of	new(on_die).

       $obj->died( [STRING] )
	   The exit string or object ($@) of the eval'ed block,	in its
	   unprocessed state.  They will always	return true when they where
	   deadly, and it always stringifies into something useful.

       $obj->exceptions()
	   Returns all collected "Log::Report::Exceptions".  The last of them
	   may be a fatal one.	The other are non-fatal.

       $obj->hide(@reasons)
	   [1.09] By default, the try will only	catch messages which stop the
	   execution of	the block (errors etc, internally a 'die').  Other
	   messages are	passed to the parent dispatchers.

	   This	option gives the opportunity to	stop, for instance, trace
	   messages.  Those messages are still collected inside	the try	object
	   (unless excluded by new(accept)), so	may get	passed-on later	via
	   reportAll() if you like.

	   Be warned: Using this method	will reset the whole 'hide'
	   configuration: it's a set not an add.

	   example: change the setting of the running block

	     my	$parent_try = dispatcher 'active-try';
	     $parent_try->hide('ALL');

       $obj->hides($reason)
	   Check whether the try stops message which were produced for
	   $reason.

       $obj->isDisabled()
	   Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->mode()
	   Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->name()
	   Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->needs( [$reason] )
	   Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->type()
	   Inherited, see "Accessors" in Log::Report::Dispatcher

   Logging
       Extends "Logging" in Log::Report::Dispatcher.

       $obj->addSkipStack(@CODE)
       Log::Report::Dispatcher::Try->addSkipStack(@CODE)
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->collectLocation()
       Log::Report::Dispatcher::Try->collectLocation()
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->collectStack( [$maxdepth] )
       Log::Report::Dispatcher::Try->collectStack( [$maxdepth] )
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->log($opts,	$reason, $message)
	   Other dispatchers translate the message here, and make it leave the
	   program.  However, messages in a "try" block	are only captured in
	   an intermediate layer: they may never be presented to an end-users.
	   And for sure, we do not know	the language yet.

	   The $message	is either a STRING or a	Log::Report::Message.

       $obj->reportAll(%options)
	   Re-cast the messages	in all collect exceptions into the defined
	   dispatchers,	which were disabled during the try block. The %options
	   will	end-up as HASH of %options to Log::Report::report(); see
	   Log::Report::Exception::throw() which does the job.

       $obj->reportFatal()
	   Re-cast only	the fatal message to the defined dispatchers.  If the
	   block was left without problems, then nothing will be done.	The
	   %options will end-up	as HASH	of %options to Log::Report::report();
	   see Log::Report::Exception::throw() which does the job.

       $obj->skipStack()
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->stackTraceLine(%options)
       Log::Report::Dispatcher::Try->stackTraceLine(%options)
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->translate(HASH-$of-%options, $reason, $message)
	   Inherited, see "Logging" in Log::Report::Dispatcher

   Status
       $obj->failed()
	   Returns true	if the block was left with an fatal message.

       $obj->showStatus()
	   If this object is kept in $@, and someone uses this as string, we
	   want	to show	the fatal error	message.

	   The message is not very informative for the good cause: we do not
	   want	people to simply print the $@, but wish	for a re-cast of the
	   message using reportAll() or	reportFatal().

       $obj->success()
	   Returns true	if the block exited normally.

       $obj->wasFatal(%options)
	   Returns the Log::Report::Exception which caused the "try" block to
	   die,	otherwise an empty LIST	(undef).

	    -Option--Default
	     class   undef

	   class => CLASS|REGEX
	     Only return the exception if it was fatal,	and in the same	time
	     in	the specified CLASS (as	string)	or matches the REGEX.  See
	     Log::Report::Message::inClass()

DETAILS
       Extends "DETAILS" in Log::Report::Dispatcher.

OVERLOADING
       overload: boolean
	   Returns true	if the previous	try block did produce a	terminal
	   error.  This	"try" object is	assigned to $@,	and the	usual perl
	   syntax is "if($@) {...error-handler...}".

       overload: stringify
	   When	$@ is used the traditional way,	it is checked to have a	string
	   content.  In	this case, stringify into the fatal error or nothing.

SEE ALSO
       This module is part of Log-Report distribution version 1.33, built on
       July 17,	2021. Website: http://perl.overmeer.net/CPAN/

LICENSE
       Copyrights 2007-2021 by [Mark Overmeer <markov@cpan.org>]. For other
       contributors see	ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See http://dev.perl.org/licenses/

perl v5.32.1			  2021-07-17   Log::Report::Dispatcher::Try(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | METHODS | DETAILS | OVERLOADING | SEE ALSO | LICENSE

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

home | help