autodie::exception(3p) Perl Programmers Reference Guide #
autodie::exception(3p) Perl Programmers Reference Guide
NNAAMMEE #
autodie::exception - Exceptions from autodying functions.
SSYYNNOOPPSSIISS #
eval {
use autodie;
open(my $fh, '<', 'some_file.txt');
...
};
if (my $E = $@) {
say "Ooops! ",$E->caller," had problems: $@";
}
DDEESSCCRRIIPPTTIIOONN #
When an autodie enabled function fails, it generates an
"autodie::exception" object. This can be interrogated to determine
further information about the error that occurred.
This document is broken into two sections; those methods that are most
useful to the end-developer, and those methods for anyone wishing to
subclass or get very familiar with "autodie::exception".
CCoommmmoonn MMeetthhooddss These methods are intended to be used in the everyday dealing of exceptions.
The following assume that the error has been copied into a separate
scalar:
if ($E = $@) {
...
}
This is not required, but is recommended in case any code is called which
may reset or alter $@.
_a_r_g_s
my $array_ref = $E->args;
Provides a reference to the arguments passed to the subroutine that died.
_f_u_n_c_t_i_o_n
my $sub = $E->function;
The subroutine (including package) that threw the exception.
_f_i_l_e
my $file = $E->file;
The file in which the error occurred (eg, "myscript.pl" or "MyTest.pm").
_p_a_c_k_a_g_e
my $package = $E->package;
The package from which the exceptional subroutine was called.
_c_a_l_l_e_r
my $caller = $E->caller;
The subroutine that _c_a_l_l_e_d the exceptional code.
_l_i_n_e
my $line = $E->line;
The line in "$E->file" where the exceptional code was called.
_c_o_n_t_e_x_t
my $context = $E->context;
The context in which the subroutine was called by autodie; usually the
same as the context in which you called the autodying subroutine. This
can be 'list', 'scalar', or undefined (unknown). It will never be
'void', as "autodie" always captures the return value in one way or
another.
For some core functions that always return a scalar value regardless of
their context (eg, "chown"), this may be 'scalar', even if you used a
list context.
_r_e_t_u_r_n
my $return_value = $E->return;
The value(s) returned by the failed subroutine. When the subroutine was
called in a list context, this will always be a reference to an array
containing the results. When the subroutine was called in a scalar
context, this will be the actual scalar returned.
_e_r_r_n_o
my $errno = $E->errno;
The value of $! at the time when the exception occurred.
NNOOTTEE: This method will leave the main "autodie::exception" class and
become part of a role in the future. You should only call "errno" for
exceptions where $! would reasonably have been set on failure.
_e_v_a_l___e_r_r_o_r
my $old_eval_error = $E->eval_error;
The contents of $@ immediately after autodie triggered an exception.
This may be useful when dealing with modules such as Text::Balanced that
set (but do not throw) $@ on error.
_m_a_t_c_h_e_s
if ( $e->matches('open') ) { ... }
if ( 'open' ~~ $e ) { ... }
"matches" is used to determine whether a given exception matches a
particular role.
An exception is considered to match a string if:
• For a string not starting with a colon, the string exactly matches
the package and subroutine that threw the exception. For example,
"MyModule::log". If the string does not contain a package name,
"CORE::" is assumed.
• For a string that does start with a colon, if the subroutine throwing
the exception _d_o_e_s that behaviour. For example, the "CORE::open"
subroutine does ":file", ":io" and ":all".
See "CATEGORIES" in autodie for further information.
On Perl 5.10 and above, using smart-match ("~~") with an
"autodie::exception" object will use "matches" underneath. This
module used to recommend using smart-match with the exception object
on the left hand side, but in future Perls that is likely to stop
working. The smart-match facility of this class should only be used
with the exception object on the right hand side. Having the
exception object on the right is both future-proof and portable to
older Perls, back to 5.10. Beware that this facility can only be
relied upon when it is certain that the exception object actually is
an "autodie::exception" object; it is no more capable than an
explicit call to the "matches" method.
AAddvvaanncceedd mmeetthhooddss The following methods, while usable from anywhere, are primarily intended for developers wishing to subclass “autodie::exception”, write code that registers custom error messages, or otherwise work closely with the “autodie::exception” model.
_r_e_g_i_s_t_e_r
autodie::exception->register( 'CORE::open' => \&mysub );
The "register" method allows for the registration of a message handler
for a given subroutine. The full subroutine name including the package
should be used.
Registered message handlers will receive the "autodie::exception" object
as the first parameter.
_a_d_d___f_i_l_e___a_n_d___l_i_n_e
say "Problem occurred",$@->add_file_and_line;
Returns the string " at %s line %d", where %s is replaced with the
filename, and %d is replaced with the line number.
Primarily intended for use by format handlers.
_s_t_r_i_n_g_i_f_y
say "The error was: ",$@->stringify;
Formats the error as a human readable string. Usually there's no reason
to call this directly, as it is used automatically if an
"autodie::exception" object is ever used as a string.
Child classes can override this method to change how they're stringified.
_f_o_r_m_a_t___d_e_f_a_u_l_t
my $error_string = $E->format_default;
This produces the default error string for the given exception, _w_i_t_h_o_u_t
_u_s_i_n_g _a_n_y _r_e_g_i_s_t_e_r_e_d _m_e_s_s_a_g_e _h_a_n_d_l_e_r_s. It is primarily intended to be
called from a message handler when they have been passed an exception
they don't want to format.
Child classes can override this method to change how default messages are
formatted.
_n_e_w
my $error = autodie::exception->new(
args => \@_,
function => "CORE::open",
errno => $!,
context => 'scalar',
return => undef,
);
Creates a new "autodie::exception" object. Normally called directly from
an autodying function. The "function" argument is required, its the
function we were trying to call that generated the exception. The "args"
parameter is optional.
The "errno" value is optional. In versions of "autodie::exception" 1.99
and earlier the code would try to automatically use the current value of
$!, but this was unreliable and is no longer supported.
Atrributes such as package, file, and caller are determined
automatically, and cannot be specified.
SSEEEE AALLSSOO #
autodie, autodie::exception::system
LLIICCEENNSSEE #
Copyright (C)2008 Paul Fenwick
This is free software. You may modify and/or redistribute this code
under the same terms as Perl 5.10 itself, or, at your option, any later
version of Perl 5.
AAUUTTHHOORR #
Paul Fenwick <pjf@perltraining.com.au>
perl v5.36.3 2023-02-15 autodie::exception(3p)