1autodie::exception(3) User Contributed Perl Documentationautodie::exception(3)
2
6 autodie::exception - Exceptions from autodying functions.
7
9 eval {
10 use autodie;
11 open(my $fh, '<', 'some_file.txt');
13 ...
15 };
16 if (my $E = $@) {
18 say "Ooops! ",$E->caller," had problems: $@";
19 }
20
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 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 Common Methods
31 These methods are intended to be used in the everyday dealing of
32 exceptions.
33 The following assume that the error has been copied into a separate
35 scalar:
36 if ($E = $@) {
38 ...
39 }
40 This is not required, but is recommended in case any code is called
42 which may reset or alter $@.
43 args
45 my $array_ref = $E->args;
47 Provides a reference to the arguments passed to the subroutine that
49 died.
50 function
52 my $sub = $E->function;
54 The subroutine (including package) that threw the exception.
56 file
58 my $file = $E->file;
60 The file in which the error occurred (eg, "myscript.pl" or
62 "MyTest.pm").
63 package
65 my $package = $E->package;
67 The package from which the exceptional subroutine was called.
69 caller
71 my $caller = $E->caller;
73 The subroutine that called the exceptional code.
75 line
77 my $line = $E->line;
79 The line in "$E->file" where the exceptional code was called.
81 context
83 my $context = $E->context;
85 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 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 return
97 my $return_value = $E->return;
99 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 errno
106 my $errno = $E->errno;
108 The value of $! at the time when the exception occurred.
110 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 eval_error
116 my $old_eval_error = $E->eval_error;
118 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 matches
124 if ( $e->matches('open') ) { ... }
126 if ( 'open' ~~ $e ) { ... }
128 "matches" is used to determine whether a given exception matches a
130 particular role.
131 An exception is considered to match a string if:
133 • 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 • 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 See "CATEGORIES" in autodie for further information.
144 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 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 register
164 autodie::exception->register( 'CORE::open' => \&mysub );
166 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 Registered message handlers will receive the "autodie::exception"
172 object as the first parameter.
173 add_file_and_line
175 say "Problem occurred",$@->add_file_and_line;
177 Returns the string " at %s line %d", where %s is replaced with the
179 filename, and %d is replaced with the line number.
180 Primarily intended for use by format handlers.
182 stringify
184 say "The error was: ",$@->stringify;
186 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 Child classes can override this method to change how they're
192 stringified.
193 format_default
195 my $error_string = $E->format_default;
197 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 Child classes can override this method to change how default messages
204 are formatted.
205 new
207 my $error = autodie::exception->new(
209 args => \@_,
210 function => "CORE::open",
211 errno => $!,
212 context => 'scalar',
213 return => undef,
214 );
215 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 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 Atrributes such as package, file, and caller are determined
226 automatically, and cannot be specified.
227
229 autodie, autodie::exception::system
230
232 Copyright (C)2008 Paul Fenwick
233 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
239 Paul Fenwick <pjf@perltraining.com.au>
240perl v5.32.1 2021-01-27 autodie::exception(3)