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 Log::Report::try() catches errors in	the block (CODE	reference)
       which is	just following the function name.  All dispatchers are
       temporarily disabled by "try", and messages which are reported are
       collected within	a temporary dispatcher named "try".  When the CODE has
       run, that "try" dispatcher is returned in $@, and all original
       dispatchers reinstated.

       Then, after the "try" has finished, the routine which used the "try"
       should decide what to do	with the collected reports.  These reports are
       collected as Log::Report::Exception objects.  They can be ignored, or
       thrown to a higher level	try... causing an exit of the program if there
       is none.

       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 ($@) of the eval'ed block.

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

	   format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
	   hide	=> REASON|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 message which was reported by "eval", which is used internally
	   to catch problems in	the try	block.

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

       $obj->hide(REASON|REASONS|ARRAY|'ALL'|'NONE')
	   [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 parent try blocks, if	none than to the
	   dispatchers.

	   This	option gives the opportunity to	block, for instance, trace
	   messages.  Those messages are still collected inside	the try
	   object, 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('NONE');

       $obj->hides(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.29, built on
       November	08, 2019. Website: http://perl.overmeer.net/CPAN/

LICENSE
       Copyrights 2007-2019 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			  2019-11-08   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.0-RELEASE+and+Ports>

home | help