Log::Report::Exception(3)                  User Contributed Perl Documentation


NAME
       Log::Report::Exception - a single generated event

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.

OVERLOADED
       overload: "" stringification
           Produces "reason: message" via toString().

       overload: bool boolean condition
           Always returns "true": the exception object exists.

METHODS
   Constructors
       $class->new(%options)
           Create a new exception object, which is basically a "message" which
           was produced for a "reason".

            -Option     --Default
             message      <required>
             reason       <required>
             report_opts  +{ }

           message => Log::Report::Message
           reason => $reason
           report_opts => \%opts

   Accessors
       $obj->isFatal()
           Returns whether this exception has a severity which makes it fatal
           when thrown. [1.34] This can have been overruled with the
           "is_fatal" attribute.  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 {xyz}", xyz => $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" as method 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.

           Returned is the LIST of dispatchers which have accepted the
           forwarded exception.

           >> example: overrule defaults to report

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

             my ($syslog) = $exception->throw(to => 'syslog');
             my @disps = $@->wasFatal->throw(reason => 'WARNING');

       $obj->toHTML( [$locale] )
           [1.11] Calls toString() and then escapes 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

SEE ALSO
       This module is part of Log-Report version 1.43, built on December 05,
       2025. Website: http://perl.overmeer.net/CPAN/

LICENSE
       For contributors see file ChangeLog.

       This software is copyright (c) 2007-2025 by Mark Overmeer.

       This is free software; you can redistribute it and/or modify it under
       the same terms as the Perl 5 programming language system itself.

perl v5.42.0                      2025-12-12         Log::Report::Exception(3)