Debian Codegraph @

upstream/debian-unstable/man3/autodie::exception.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "autodie::exception 3perl"
58 .TH autodie::exception 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 autodie::exception \- Exceptions from autodying functions.
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& eval {
69 \& use autodie;
70 \&
71 \& open(my $fh, \*(Aq<\*(Aq, \*(Aqsome_file.txt\*(Aq);
72 \&
73 \& ...
74 \& };
75 \&
76 \& if (my $E = $@) {
77 \& say "Ooops! ",$E\->caller," had problems: $@";
78 \& }
79 .Ve
80 .SH DESCRIPTION
81 .IX Header "DESCRIPTION"
82 When an autodie enabled function fails, it generates an
83 \&\f(CW\*(C`autodie::exception\*(C'\fR object. This can be interrogated to
84 determine further information about the error that occurred.
85 .PP
86 This document is broken into two sections; those methods that
87 are most useful to the end-developer, and those methods for
88 anyone wishing to subclass or get very familiar with
89 \&\f(CW\*(C`autodie::exception\*(C'\fR.
90 .SS "Common Methods"
91 .IX Subsection "Common Methods"
92 These methods are intended to be used in the everyday dealing
93 of exceptions.
94 .PP
95 The following assume that the error has been copied into
96 a separate scalar:
97 .PP
98 .Vb 3
99 \& if ($E = $@) {
100 \& ...
101 \& }
102 .Ve
103 .PP
104 This is not required, but is recommended in case any code
105 is called which may reset or alter \f(CW$@\fR.
106 .PP
107 \fIargs\fR
108 .IX Subsection "args"
109 .PP
110 .Vb 1
111 \& my $array_ref = $E\->args;
112 .Ve
113 .PP
114 Provides a reference to the arguments passed to the subroutine
115 that died.
116 .PP
117 \fIfunction\fR
118 .IX Subsection "function"
119 .PP
120 .Vb 1
121 \& my $sub = $E\->function;
122 .Ve
123 .PP
124 The subroutine (including package) that threw the exception.
125 .PP
126 \fIfile\fR
127 .IX Subsection "file"
128 .PP
129 .Vb 1
130 \& my $file = $E\->file;
131 .Ve
132 .PP
133 The file in which the error occurred (eg, \f(CW\*(C`myscript.pl\*(C'\fR or
134 \&\f(CW\*(C`MyTest.pm\*(C'\fR).
135 .PP
136 \fIpackage\fR
137 .IX Subsection "package"
138 .PP
139 .Vb 1
140 \& my $package = $E\->package;
141 .Ve
142 .PP
143 The package from which the exceptional subroutine was called.
144 .PP
145 \fIcaller\fR
146 .IX Subsection "caller"
147 .PP
148 .Vb 1
149 \& my $caller = $E\->caller;
150 .Ve
151 .PP
152 The subroutine that \fIcalled\fR the exceptional code.
153 .PP
154 \fIline\fR
155 .IX Subsection "line"
156 .PP
157 .Vb 1
158 \& my $line = $E\->line;
159 .Ve
160 .PP
161 The line in \f(CW\*(C`$E\->file\*(C'\fR where the exceptional code was called.
162 .PP
163 \fIcontext\fR
164 .IX Subsection "context"
165 .PP
166 .Vb 1
167 \& my $context = $E\->context;
168 .Ve
169 .PP
170 The context in which the subroutine was called by autodie; usually
171 the same as the context in which you called the autodying subroutine.
172 This can be 'list', 'scalar', or undefined (unknown). It will never
173 be 'void', as \f(CW\*(C`autodie\*(C'\fR always captures the return value in one way
174 or another.
175 .PP
176 For some core functions that always return a scalar value regardless
177 of their context (eg, \f(CW\*(C`chown\*(C'\fR), this may be 'scalar', even if you
178 used a list context.
179 .PP
180 \fIreturn\fR
181 .IX Subsection "return"
182 .PP
183 .Vb 1
184 \& my $return_value = $E\->return;
185 .Ve
186 .PP
187 The value(s) returned by the failed subroutine. When the subroutine
188 was called in a list context, this will always be a reference to an
189 array containing the results. When the subroutine was called in
190 a scalar context, this will be the actual scalar returned.
191 .PP
192 \fIerrno\fR
193 .IX Subsection "errno"
194 .PP
195 .Vb 1
196 \& my $errno = $E\->errno;
197 .Ve
198 .PP
199 The value of \f(CW$!\fR at the time when the exception occurred.
200 .PP
201 \&\fBNOTE\fR: This method will leave the main \f(CW\*(C`autodie::exception\*(C'\fR class
202 and become part of a role in the future. You should only call
203 \&\f(CW\*(C`errno\*(C'\fR for exceptions where \f(CW$!\fR would reasonably have been
204 set on failure.
205 .PP
206 \fIeval_error\fR
207 .IX Subsection "eval_error"
208 .PP
209 .Vb 1
210 \& my $old_eval_error = $E\->eval_error;
211 .Ve
212 .PP
213 The contents of \f(CW$@\fR immediately after autodie triggered an
214 exception. This may be useful when dealing with modules such
215 as Text::Balanced that set (but do not throw) \f(CW$@\fR on error.
216 .PP
217 \fImatches\fR
218 .IX Subsection "matches"
219 .PP
220 .Vb 1
221 \& if ( $e\->matches(\*(Aqopen\*(Aq) ) { ... }
222 \&
223 \& if ( \*(Aqopen\*(Aq ~~ $e ) { ... }
224 .Ve
225 .PP
226 \&\f(CW\*(C`matches\*(C'\fR is used to determine whether a
227 given exception matches a particular role.
228 .PP
229 An exception is considered to match a string if:
230 .IP \(bu 4
231 For a string not starting with a colon, the string exactly matches the
232 package and subroutine that threw the exception. For example,
233 \&\f(CW\*(C`MyModule::log\*(C'\fR. If the string does not contain a package name,
234 \&\f(CW\*(C`CORE::\*(C'\fR is assumed.
235 .IP \(bu 4
236 For a string that does start with a colon, if the subroutine
237 throwing the exception \fIdoes\fR that behaviour. For example, the
238 \&\f(CW\*(C`CORE::open\*(C'\fR subroutine does \f(CW\*(C`:file\*(C'\fR, \f(CW\*(C`:io\*(C'\fR and \f(CW\*(C`:all\*(C'\fR.
239 .Sp
240 See "CATEGORIES" in autodie for further information.
241 .Sp
242 On Perl 5.10 and above, using smart-match (\f(CW\*(C`~~\*(C'\fR) with an
243 \&\f(CW\*(C`autodie::exception\*(C'\fR object will use \f(CW\*(C`matches\*(C'\fR underneath. This module
244 used to recommend using smart-match with the exception object on the left
245 hand side, but in future Perls that is likely to stop working.
246 The smart-match facility of this class should only be used with the
247 exception object on the right hand side. Having the exception object on
248 the right is both future-proof and portable to older Perls, back to 5.10.
249 Beware that this facility can only
250 be relied upon when it is certain that the exception object actually is
251 an \f(CW\*(C`autodie::exception\*(C'\fR object; it is no more capable than an explicit
252 call to the \f(CW\*(C`matches\*(C'\fR method.
253 .SS "Advanced methods"
254 .IX Subsection "Advanced methods"
255 The following methods, while usable from anywhere, are primarily
256 intended for developers wishing to subclass \f(CW\*(C`autodie::exception\*(C'\fR,
257 write code that registers custom error messages, or otherwise
258 work closely with the \f(CW\*(C`autodie::exception\*(C'\fR model.
259 .PP
260 \fIregister\fR
261 .IX Subsection "register"
262 .PP
263 .Vb 1
264 \& autodie::exception\->register( \*(AqCORE::open\*(Aq => \e&mysub );
265 .Ve
266 .PP
267 The \f(CW\*(C`register\*(C'\fR method allows for the registration of a message
268 handler for a given subroutine. The full subroutine name including
269 the package should be used.
270 .PP
271 Registered message handlers will receive the \f(CW\*(C`autodie::exception\*(C'\fR
272 object as the first parameter.
273 .PP
274 \fIadd_file_and_line\fR
275 .IX Subsection "add_file_and_line"
276 .PP
277 .Vb 1
278 \& say "Problem occurred",$@\->add_file_and_line;
279 .Ve
280 .PP
281 Returns the string \f(CW\*(C` at %s line %d\*(C'\fR, where \f(CW%s\fR is replaced with
282 the filename, and \f(CW%d\fR is replaced with the line number.
283 .PP
284 Primarily intended for use by format handlers.
285 .PP
286 \fIstringify\fR
287 .IX Subsection "stringify"
288 .PP
289 .Vb 1
290 \& say "The error was: ",$@\->stringify;
291 .Ve
292 .PP
293 Formats the error as a human readable string. Usually there's no
294 reason to call this directly, as it is used automatically if an
295 \&\f(CW\*(C`autodie::exception\*(C'\fR object is ever used as a string.
296 .PP
297 Child classes can override this method to change how they're
298 stringified.
299 .PP
300 \fIformat_default\fR
301 .IX Subsection "format_default"
302 .PP
303 .Vb 1
304 \& my $error_string = $E\->format_default;
305 .Ve
306 .PP
307 This produces the default error string for the given exception,
308 \&\fIwithout using any registered message handlers\fR. It is primarily
309 intended to be called from a message handler when they have
310 been passed an exception they don't want to format.
311 .PP
312 Child classes can override this method to change how default
313 messages are formatted.
314 .PP
315 \fInew\fR
316 .IX Subsection "new"
317 .PP
318 .Vb 7
319 \& my $error = autodie::exception\->new(
320 \& args => \e@_,
321 \& function => "CORE::open",
322 \& errno => $!,
323 \& context => \*(Aqscalar\*(Aq,
324 \& return => undef,
325 \& );
326 .Ve
327 .PP
328 Creates a new \f(CW\*(C`autodie::exception\*(C'\fR object. Normally called
329 directly from an autodying function. The \f(CW\*(C`function\*(C'\fR argument
330 is required, its the function we were trying to call that
331 generated the exception. The \f(CW\*(C`args\*(C'\fR parameter is optional.
332 .PP
333 The \f(CW\*(C`errno\*(C'\fR value is optional. In versions of \f(CW\*(C`autodie::exception\*(C'\fR
334 1.99 and earlier the code would try to automatically use the
335 current value of \f(CW$!\fR, but this was unreliable and is no longer
336 supported.
337 .PP
338 Atrributes such as package, file, and caller are determined
339 automatically, and cannot be specified.
340 .SH "SEE ALSO"
341 .IX Header "SEE ALSO"
342 autodie, autodie::exception::system
343 .SH LICENSE
344 .IX Header "LICENSE"
345 Copyright (C)2008 Paul Fenwick
346 .PP
347 This is free software. You may modify and/or redistribute this
348 code under the same terms as Perl 5.10 itself, or, at your option,
349 any later version of Perl 5.
350 .SH AUTHOR
351 .IX Header "AUTHOR"
352 Paul Fenwick <[email protected]>