---
name: "Log::Report::Exception"
section: "3pm"
platform: "linux"
package: "perl-log-report"
version: "1.46-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Log::Report::Exception"
---

# Log::Report::Exception(3pm)

a single generated event

## 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->taggedWith('die')) ...
  if($exception->taggedWith('die')) ...   # same
  if($@->wasFatal(tag => '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

    ### Attributes

- $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**($tag\|Regexp)

  Deprecated name for **taggedWith()**.

- $obj-\>**print**( \[$fh\] )

  The default filehandle is STDOUT.

  » example:

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

- $obj-\>**taggedWith**($tag\|Regexp)

  \[1.44\] Check whether any of the classes listed in the message match `$tag` (string) or the Regexp.  This uses **Log::Report::Message::taggedWith()**.

- $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
  ```

## DIAGNOSTICS

- Error: **message()** of exception expects Log::Report::Message, got $what.

  Cast by `message()`

## SEE ALSO

This module is part of Log-Report version 1.46, built on June 16, 2026. Website: *http://perl.overmeer.net/CPAN/*

## LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2007-2026 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.