Debian Codegraph @

upstream/opensuse-tumbleweed/man3/autodie::exception.3pm

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