Log::Report::Exception(3)

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.41, built on September 11, 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.