1autodie::exception(3) User Contributed Perl Documentationautodie::exception(3)
2
3
4

NAME

6       autodie::exception - Exceptions from autodying functions.
7

SYNOPSIS

9           eval {
10               use autodie;
11
12               open(my $fh, '<', 'some_file.txt');
13
14               ...
15           };
16
17           if (my $E = $@) {
18               say "Ooops!  ",$E->caller," had problems: $@";
19           }
20

DESCRIPTION

22       When an autodie enabled function fails, it generates an
23       "autodie::exception" object.  This can be interrogated to determine
24       further information about the error that occurred.
25
26       This document is broken into two sections; those methods that are most
27       useful to the end-developer, and those methods for anyone wishing to
28       subclass or get very familiar with "autodie::exception".
29
30   Common Methods
31       These methods are intended to be used in the everyday dealing of
32       exceptions.
33
34       The following assume that the error has been copied into a separate
35       scalar:
36
37           if ($E = $@) {
38               ...
39           }
40
41       This is not required, but is recommended in case any code is called
42       which may reset or alter $@.
43
44       args
45
46           my $array_ref = $E->args;
47
48       Provides a reference to the arguments passed to the subroutine that
49       died.
50
51       function
52
53           my $sub = $E->function;
54
55       The subroutine (including package) that threw the exception.
56
57       file
58
59           my $file = $E->file;
60
61       The file in which the error occurred (eg, "myscript.pl" or
62       "MyTest.pm").
63
64       package
65
66           my $package = $E->package;
67
68       The package from which the exceptional subroutine was called.
69
70       caller
71
72           my $caller = $E->caller;
73
74       The subroutine that called the exceptional code.
75
76       line
77
78           my $line = $E->line;
79
80       The line in "$E->file" where the exceptional code was called.
81
82       context
83
84           my $context = $E->context;
85
86       The context in which the subroutine was called by autodie; usually the
87       same as the context in which you called the autodying subroutine.  This
88       can be 'list', 'scalar', or undefined (unknown).  It will never be
89       'void', as "autodie" always captures the return value in one way or
90       another.
91
92       For some core functions that always return a scalar value regardless of
93       their context (eg, "chown"), this may be 'scalar', even if you used a
94       list context.
95
96       return
97
98           my $return_value = $E->return;
99
100       The value(s) returned by the failed subroutine.  When the subroutine
101       was called in a list context, this will always be a reference to an
102       array containing the results.  When the subroutine was called in a
103       scalar context, this will be the actual scalar returned.
104
105       errno
106
107           my $errno = $E->errno;
108
109       The value of $! at the time when the exception occurred.
110
111       NOTE: This method will leave the main "autodie::exception" class and
112       become part of a role in the future.  You should only call "errno" for
113       exceptions where $! would reasonably have been set on failure.
114
115       eval_error
116
117           my $old_eval_error = $E->eval_error;
118
119       The contents of $@ immediately after autodie triggered an exception.
120       This may be useful when dealing with modules such as Text::Balanced
121       that set (but do not throw) $@ on error.
122
123       matches
124
125           if ( $e->matches('open') ) { ... }
126
127           if ( 'open' ~~ $e ) { ... }
128
129       "matches" is used to determine whether a given exception matches a
130       particular role.
131
132       An exception is considered to match a string if:
133
134       •   For a string not starting with a colon, the string exactly matches
135           the package and subroutine that threw the exception.  For example,
136           "MyModule::log".  If the string does not contain a package name,
137           "CORE::" is assumed.
138
139       •   For a string that does start with a colon, if the subroutine
140           throwing the exception does that behaviour.  For example, the
141           "CORE::open" subroutine does ":file", ":io" and ":all".
142
143           See "CATEGORIES" in autodie for further information.
144
145           On Perl 5.10 and above, using smart-match ("~~") with an
146           "autodie::exception" object will use "matches" underneath.  This
147           module used to recommend using smart-match with the exception
148           object on the left hand side, but in future Perls that is likely to
149           stop working.  The smart-match facility of this class should only
150           be used with the exception object on the right hand side.  Having
151           the exception object on the right is both future-proof and portable
152           to older Perls, back to 5.10.  Beware that this facility can only
153           be relied upon when it is certain that the exception object
154           actually is an "autodie::exception" object; it is no more capable
155           than an explicit call to the "matches" method.
156
157   Advanced methods
158       The following methods, while usable from anywhere, are primarily
159       intended for developers wishing to subclass "autodie::exception", write
160       code that registers custom error messages, or otherwise work closely
161       with the "autodie::exception" model.
162
163       register
164
165           autodie::exception->register( 'CORE::open' => \&mysub );
166
167       The "register" method allows for the registration of a message handler
168       for a given subroutine.  The full subroutine name including the package
169       should be used.
170
171       Registered message handlers will receive the "autodie::exception"
172       object as the first parameter.
173
174       add_file_and_line
175
176           say "Problem occurred",$@->add_file_and_line;
177
178       Returns the string " at %s line %d", where %s is replaced with the
179       filename, and %d is replaced with the line number.
180
181       Primarily intended for use by format handlers.
182
183       stringify
184
185           say "The error was: ",$@->stringify;
186
187       Formats the error as a human readable string.  Usually there's no
188       reason to call this directly, as it is used automatically if an
189       "autodie::exception" object is ever used as a string.
190
191       Child classes can override this method to change how they're
192       stringified.
193
194       format_default
195
196           my $error_string = $E->format_default;
197
198       This produces the default error string for the given exception, without
199       using any registered message handlers.  It is primarily intended to be
200       called from a message handler when they have been passed an exception
201       they don't want to format.
202
203       Child classes can override this method to change how default messages
204       are formatted.
205
206       new
207
208           my $error = autodie::exception->new(
209               args => \@_,
210               function => "CORE::open",
211               errno => $!,
212               context => 'scalar',
213               return => undef,
214           );
215
216       Creates a new "autodie::exception" object.  Normally called directly
217       from an autodying function.  The "function" argument is required, its
218       the function we were trying to call that generated the exception.  The
219       "args" parameter is optional.
220
221       The "errno" value is optional.  In versions of "autodie::exception"
222       1.99 and earlier the code would try to automatically use the current
223       value of $!, but this was unreliable and is no longer supported.
224
225       Atrributes such as package, file, and caller are determined
226       automatically, and cannot be specified.
227

SEE ALSO

229       autodie, autodie::exception::system
230

LICENSE

232       Copyright (C)2008 Paul Fenwick
233
234       This is free software.  You may modify and/or redistribute this code
235       under the same terms as Perl 5.10 itself, or, at your option, any later
236       version of Perl 5.
237

AUTHOR

239       Paul Fenwick <pjf@perltraining.com.au>
240
241
242
243perl v5.36.0                      2023-01-30             autodie::exception(3)
Impressum