| 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]> |