NAME

       Log::Report::Exception - a collected report

SYNOPSIS

        # created within a try block
        try { error "help!" };
        my $exception = $@->wasFatal;
        $exception->throw if $exception;

        $@->reportFatal;  # combination of above two lines

        my $message = $exception->message;   # the Log::Report::Message

        if($message->inClass('die')) ...
        if($exception->inClass('die')) ...   # same
        if($@->wasFatal(class => 'die')) ... # same

DESCRIPTION

       In Log::Report, exceptions are not as extended as available in languages as Java: you do
       not create classes for them.  The only thing an exception object does, is capture some
       information about an (untranslated) report.

METHODS

   Constructors
       Log::Report::Exception->new(%options)
            -Option     --Default
             message      <required>
             reason       <required>
             report_opts  {}

           message => Log::Report::Message
           reason => REASON
           report_opts => HASH

   Accessors
       $obj->isFatal()
           Returns whether this exception has a severity which makes it fatal when thrown.  See
           Log::Report::Util::is_fatal().

           example:

             if($ex->isFatal) { $ex->throw(reason => 'ALERT') }
             else { $ex->throw }

       $obj->message( [$message] )
           Change the $message of the exception, must be a Log::Report::Message object.

           When you use a "Log::Report::Message" object, you will get a new one returned.
           Therefore, if you want to modify the message in an exception, you have to re-assign
           the result of the modification.

           example:

            $e->message->concat('!!')); # will not work!
            $e->message($e->message->concat('!!'));
            $e->message(__x"some message {msg}", msg => $xyz);

       $obj->reason( [$reason] )
       $obj->report_opts()

   Processing
       $obj->inClass($class|Regexp)
           Check whether any of the classes listed in the message match $class (string) or the
           Regexp.  This uses Log::Report::Message::inClass().

       $obj->print( [$fh] )
           The default filehandle is STDOUT.

           example:

            print $exception;  # via overloading
            $exception->print; # OO style

       $obj->throw(%options)
           Insert the message contained in the exception into the currently defined dispatchers.
           The "throw" name is commonly known exception related terminology for "report".

           The %options overrule the captured options to Log::Report::report().  This can be used
           to overrule a destination.  Also, the reason can be changed.

           example: overrule defaults to report

            try { print {to => 'stderr'}, ERROR => 'oops!' };
            $@->reportFatal(to => 'syslog');

            $exception->throw(to => 'syslog');

            $@->wasFatal->throw(reason => 'WARNING');

       $obj->toHTML( [$locale] )
           [1.11] as toString(), and escape HTML volatile characters.

       $obj->toString( [$locale] )
           Prints the reason and the message.  Differently from throw(), this only represents the
           textual content: it does not re-cast the exceptions to higher levels.

           example: printing exceptions

            print $_->toString for $@->exceptions;
            print $_ for $@->exceptions;   # via overloading

OVERLOADING

       overload: stringification
           Produces "reason: message".

SEE ALSO

       This module is part of Log-Report distribution version 1.26, built on January 23, 2018.
       Website: http://perl.overmeer.net/CPAN/

LICENSE

       Copyrights 2007-2018 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 http://dev.perl.org/licenses/