=head1 NAME

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

=head1 INHERITANCE

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

=head1 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-';

 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
       report {to => 'stderr'}, FAILURE => 'no network';
     };
 $@->reportFatal(to => 'syslog');  # overrule destination

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

=head1 DESCRIPTION

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

Then, after the C<try> has finished, the routine which used
the "try" should decide what to do with the collected reports.
These reports are collected as L<Log::Report::Exception|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.

=head1 METHODS

=head2 Constructors

=over 4

=item $obj-E<gt>B<close>()

Only when initiated with a FILENAME, the file will be closed.  In any
other case, nothing will be done.

=item Log::Report::Dispatcher::Try-E<gt>B<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'
  locale         Log::Report::Dispatcher  <system locale>
  mode           Log::Report::Dispatcher  'NORMAL'

=over 2

=item accept => REASONS

=item charset => CHARSET

=item died => STRING

The exit string ($@) of the eval'ed block.

=item exceptions => ARRAY-of-EXCEPTIONS

=item format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE

=item locale => LOCALE

=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3

=back

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<died>([STRING])

The message which was reported by C<eval>, which is used internally
to catch problems in the try block.

=item $obj-E<gt>B<exceptions>()

Returns all collected C<Log::Report::Exceptions>.  The last of
them may be a fatal one.  The other are non-fatal.

=item $obj-E<gt>B<isDisabled>()

See L<Log::Report::Dispatcher/"Accessors">

=item $obj-E<gt>B<mode>()

See L<Log::Report::Dispatcher/"Accessors">

=item $obj-E<gt>B<name>()

See L<Log::Report::Dispatcher/"Accessors">

=item $obj-E<gt>B<needs>()

See L<Log::Report::Dispatcher/"Accessors">

=item $obj-E<gt>B<type>()

See L<Log::Report::Dispatcher/"Accessors">

=back

=head2 Logging

=over 4

=item $obj-E<gt>B<collectLocation>()

=item Log::Report::Dispatcher::Try-E<gt>B<collectLocation>()

See L<Log::Report::Dispatcher/"Logging">

=item $obj-E<gt>B<collectStack>([MAXDEPTH])

=item Log::Report::Dispatcher::Try-E<gt>B<collectStack>([MAXDEPTH])

See L<Log::Report::Dispatcher/"Logging">

=item $obj-E<gt>B<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 L<Log::Report::Message|Log::Report::Message>.

=item $obj-E<gt>B<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 L<Log::Report::report()|Log::Report/"Report Production and Configuration">; see
L<Log::Report::Exception::throw()|Log::Report::Exception/"Processing"> which does the job.

=item $obj-E<gt>B<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 L<Log::Report::report()|Log::Report/"Report Production and Configuration">; see
L<Log::Report::Exception::throw()|Log::Report::Exception/"Processing"> which does the job.

=item $obj-E<gt>B<stackTraceLine>(OPTIONS)

=item Log::Report::Dispatcher::Try-E<gt>B<stackTraceLine>(OPTIONS)

See L<Log::Report::Dispatcher/"Logging">

=item $obj-E<gt>B<translate>(HASH-of-OPTIONS, REASON, MESSAGE)

See L<Log::Report::Dispatcher/"Logging">

=back

=head2 Status

=over 4

=item $obj-E<gt>B<failed>()

Returns true if the block was left with an fatal message.

=item $obj-E<gt>B<showStatus>()

If this object is kept in C<$@>, 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 C<$@>, but wish for a re-cast of the message
using L<reportAll()|Log::Report::Dispatcher::Try/"Logging"> or L<reportFatal()|Log::Report::Dispatcher::Try/"Logging">.

=item $obj-E<gt>B<success>()

Returns true if the block exited normally.

=item $obj-E<gt>B<wasFatal>(OPTIONS)

Returns the L<Log::Report::Exception|Log::Report::Exception> which caused the "try" block to
die, otherwise an empty LIST (undef).

 -Option--Default
  class   undef

=over 2

=item 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 L<Log::Report::Message::inClass()|Log::Report::Message/"Processing">

=back

=back

=head1 OVERLOADING

=over 4

=item overload: B<boolean>()

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

=item overload: B<stringify>()

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

=back

=head1 SEE ALSO

This module is part of Log-Report distribution version 0.97,
built on September 03, 2012. Website: F<http://perl.overmeer.net/log-report/>

=head1 LICENSE

Copyrights 2007-2012 by [Mark Overmeer]. 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 F<http://www.perl.com/perl/misc/Artistic.html>