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()