Log::R...r::Try(3pm)

📦
version 1.46 · 10 versions
, in ubuntu stonking

💖 NAME 💖

Log::Report::Dispatcher::Try — the dispatcher that catches, like, ALL the reports and turns them into exceptions. Bestie it's a giant safety net under your code. 🥅✨

🦋 INHERITANCE 🦋

Log::Report::Dispatcher::Try
  is a Log::Report::Dispatcher

so yeah, it inherits everything from Log::Report::Dispatcher, no cap 💅

✨ SYNOPSIS ✨

okay so here's how we do it, read every line because every line is doing something:

try { ... };       # mind the ';' !!
if($@) {           # signals something went wrong

if(try {...}) {    # block ended normally

my $x = try { read_temperature() };
my @x = try { read_lines_from_file() };

try { ... }        # no comma!!
   mode => 'DEBUG', accept => 'ERROR-';

try sub { ... },   # with comma
   mode => 'DEBUG', accept => 'ALL';

try \&myhandler, accept => 'ERROR-';
try { ... } hide => 'TRACE';

print ref $@;      # Log::Report::Dispatcher::Try

$@->reportFatal;   # re-dispatch result of try block
$@->reportAll;     # ... also warnings etc
if($@) {...}       # if errors
if($@->failed) {   # same       # }
if($@->success) {  # no errors  # }

try { # something causes an error report, which is caught
      failure 'no network';
    };
$@->reportFatal(to => 'syslog');  # overrule destination

print $@->exceptions; # no re-cast, just print

ngl the comments in there are load-bearing. read them. 🙈

🌸 DESCRIPTION 🌸

try does what Perl's built-in eval() does but like... actually correct. It gives you real exception handling, which Perl core was frankly not serving. 💀

The Log::Report::try() function makes this ::Try dispatcher object, and its name is 'try' ✨. Once the try() is over, the object is sitting right there in $@. And that $@ as a ::Try object behaves exactly like the $@ that eval produced — it just has a million extra features. main character energy fr fr 👑

The try() function catches fatal errors that happen inside the BLOCK (the CODE reference that just follows the function name) and shoves them into the ::Try object $@. Those errors are not automatically passed on to active dispatchers. BUT — and this is the plot twist — non-fatal exceptions (like info or notice) also get collected (unless they aren't accepted, check new(accept)), and those do immediately get passed to the active dispatchers (unless the reason is hidden, check new(hide)).

After the try() has run, you get to snoop through the collected exceptions. Typically you use wasFatal() to grab the exception that ended the BLOCK's run. 🕵️♀️

Extends "DESCRIPTION" in Log::Report::Dispatcher.

👑 OVERLOADED 👑

  • overload: "" stringify — when $@ is used the old-school way, it gets checked for string content. In that case it stringifies into the fatal error, or nothing at all. 💅
  • overload: bool boolean — returns "true" if the previous try block produced a terminal error. This "try" object is what's sitting in $@, and the usual perl syntax is if($@) {...error-handler...}. So yes, the check you already know just works. slay.

💅 METHODS 💅

Extends "METHODS" in Log::Report::Dispatcher.

🎀 Constructors 🎀

Extends "Constructors" in Log::Report::Dispatcher.

$class->new($type, $name, %options)

Inherited, see "Constructors" in Log::Report::Dispatcher.

here's the option menu, defaults included, don't skip any:

  • accept — defined in Log::Report::Dispatcher, default depend on mode
  • charset — defined in Log::Report::Dispatcher, default undef
  • died — default undef
  • exceptions — default []
  • format_reason — defined in Log::Report::Dispatcher, default 'LOWERCASE'
  • hide — default 'NONE'
  • locale — defined in Log::Report::Dispatcher, default <system locale>
  • mode — defined in Log::Report::Dispatcher, default 'NORMAL'
  • on_die — default 'ERROR'

and now the deets on each one:

  • accept => $reasons|\@reasons — the reasons you're willing to accept, one or a list.
  • charset => CHARSET — the charset, you know the vibe.
  • died => $text — the exit string or object ($@) of the eval'ed block, in its unprocessed state. Raw. Untouched. 🫣
  • exceptions => \@objects — an ARRAY of Log::Report::Exception objects.
  • format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE — pick your formatting era.
  • hide => $reasons|\@reasons|'ALL'|'NONE' — [1.09] see hide()
  • locale => LOCALE — the locale.
  • mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3 — mode selection, numbers work too.
  • on_die => 'ERROR'|'PANIC' — when code running in this block exits with a die(), it gets translated into a Log::Report::Exception using Log::Report::Die::die_decode(). So the question is: how serious are we about these errors? pick your level of drama. 🎭

🌈 Attributes 🌈

Extends "Attributes" in Log::Report::Dispatcher.

  • $obj->die2reason() — returns the value of new(on_die).
  • $obj->died( [$text] ) — the exit $text or object ($@) of the eval'ed block, in its unprocessed state. These will always return "true" when they were deadly, and it always stringifies into something useful. reliable queen ✨
  • $obj->exceptions() — returns all the collected Log::Report::Exception objects. The last one may be a fatal one. The others are non-fatal. the last one is the dramatic one 💀
  • $obj->hide(@reasons) — [1.09] by default the try only catches messages that stop the execution of the block (errors and such, internally a 'die'). Other messages get passed up to the parent dispatchers.

This option lets you stop, say, trace messages. Those messages are still collected inside the try object (unless excluded by new(accept)), so they may get passed on later via reportAll() if you feel like it. 💖

⚠️ Be warned bestie: using this method will reset the whole 'hide' configuration. It's a set, not an add. so don't be surprised.

» example: change the setting of the running block

my $parent_try = dispatcher 'active-try';
$parent_try->hide('ALL');
  • $obj->hides($reason) — checks whether the try stops messages that were produced for $reason.
  • $obj->isDisabled() — inherited, see "Attributes" in Log::Report::Dispatcher.
  • $obj->mode() — inherited, see "Attributes" in Log::Report::Dispatcher.
  • $obj->name() — inherited, see "Attributes" in Log::Report::Dispatcher.
  • $obj->needs( [$reason] ) — inherited, see "Attributes" in Log::Report::Dispatcher.
  • $obj->type() — inherited, see "Attributes" in Log::Report::Dispatcher.

🍓 Logging 🍓

Extends "Logging" in Log::Report::Dispatcher.

  • $any->addSkipStack(@CODE) — inherited, see "Logging" in Log::Report::Dispatcher
  • $obj->close() — inherited, see "Logging" in Log::Report::Dispatcher
  • $any->collectLocation() — inherited, see "Logging" in Log::Report::Dispatcher
  • $any->collectStack( [$maxdepth] ) — inherited, see "Logging" in Log::Report::Dispatcher
  • $obj->log($opts, $reason, $message) — other dispatchers translate the message right here and let it leave the program. But messages inside a "try" block only get captured in an intermediate layer: they may never be presented to an end-user. And for sure, we do not know the language yet. The $message is either a STRING or a Log::Report::Message. Improves base, see "Logging" in Log::Report::Dispatcher.
  • $obj->reportAll(%options) — re-casts the messages in all the collected exceptions into the defined dispatchers, which were disabled during the try block. The %options end up as a HASH of %options to Log::Report::report(); see Log::Report::Exception::throw() which does the job.
  • $obj->reportFatal(%options) — re-casts only the fatal message to the defined dispatchers. If the block was left without problems, nothing happens. The %options end up as a HASH of %options to Log::Report::report(); see Log::Report::Exception::throw() which does the job.
  • $obj->skipStack() — inherited, see "Logging" in Log::Report::Dispatcher
  • $any->stackTraceLine(%options) — inherited, see "Logging" in Log::Report::Dispatcher
  • $obj->translate(\%options, $reason, $message) — inherited, see "Logging" in Log::Report::Dispatcher

⭐ Status ⭐

  • $obj->failed() — returns "true" if the block was left with a fatal message.
  • $obj->showStatus() — if this object is kept in $@ and someone uses it as a string, we want to show the fatal error message.

The message is not very informative, and that's on purpose: we do not want people to just print the $@. we want you to re-cast the message using reportAll() or reportFatal(). do it properly bestie 🫶

  • $obj->success() — returns "true" if the block exited normally. celebration time 🎉
  • $obj->wasFatal(%options) — returns the Log::Report::Exception which caused the "try" block to die, otherwise an empty LIST ("undef").

options:

  • class — default undef
  • tag — default undef

and the details:

  • class => $class|REGEX — deprecated alternative for "tag". (old era, retired era ✋)
  • tag => $tag|REGEX — [1.44] only return the exception if it was fatal, and at the same time in the specified $tag (as string) or matches the REGEX. See Log::Report::Message::taggedWith().

🔥 DETAILS 🔥

Extends "DETAILS" in Log::Report::Dispatcher.

🧚 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.

okay that's the whole page bestie, go forth and try responsibly ✨💖 this was Log::R...r::Try(3pm) from User Contributed Perl Documentation, shipped as part of perl v5.40.1 and dated 2026-07-05. ty for reading, ily, bye 👋🎀

📦 where this page comes from