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->toString()

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.02, built on March 10, 2014. Website: http://perl.overmeer.net/log-report/

LICENSE

Copyrights 2007-2014 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://www.perl.com/perl/misc/Artistic.html