1autodie(3) User Contributed Perl Documentation autodie(3)
2
6 autodie - Replace functions with ones that succeed or die with lexical
7 scope
8
10 use autodie; # Recommended: implies 'use autodie qw(:default)'
11 use autodie qw(:all); # Recommended more: defaults and system/exec.
13 use autodie qw(open close); # open/close succeed or die
15 open(my $fh, "<", $filename); # No need to check!
17 {
19 no autodie qw(open); # open failures won't die
20 open(my $fh, "<", $filename); # Could fail silently!
21 no autodie; # disable all autodies
22 }
23 print "Hello World" or die $!; # autodie DOESN'T check print!
25
27 bIlujDI' yIchegh()Qo'; yIHegh()!
28 It is better to die() than to return() in failure.
30 -- Klingon programming proverb.
32 The "autodie" pragma provides a convenient way to replace functions
34 that normally return false on failure with equivalents that throw an
35 exception on failure.
36 The "autodie" pragma has lexical scope, meaning that functions and
38 subroutines altered with "autodie" will only change their behaviour
39 until the end of the enclosing block, file, or "eval".
40 If "system" is specified as an argument to "autodie", then it uses
42 IPC::System::Simple to do the heavy lifting. See the description of
43 that module for more information.
44
46 Exceptions produced by the "autodie" pragma are members of the
47 autodie::exception class. The preferred way to work with these
48 exceptions under Perl 5.10 is as follows:
49 use feature qw(switch);
51 eval {
53 use autodie;
54 open(my $fh, '<', $some_file);
56 my @records = <$fh>;
58 # Do things with @records...
60 close($fh);
62 };
64 given ($@) {
66 when (undef) { say "No error"; }
67 when ('open') { say "Error from open"; }
68 when (':io') { say "Non-open, IO error."; }
69 when (':all') { say "All other autodie errors." }
70 default { say "Not an autodie error at all." }
71 }
72 Under Perl 5.8, the "given/when" structure is not available, so the
74 following structure may be used:
75 eval {
77 use autodie;
78 open(my $fh, '<', $some_file);
80 my @records = <$fh>;
82 # Do things with @records...
84 close($fh);
86 };
87 if ($@ and $@->isa('autodie::exception')) {
89 if ($@->matches('open')) { print "Error from open\n"; }
90 if ($@->matches(':io' )) { print "Non-open, IO error."; }
91 } elsif ($@) {
92 # A non-autodie exception.
93 }
94 See autodie::exception for further information on interrogating
96 exceptions.
97
99 Autodie uses a simple set of categories to group together similar
100 built-ins. Requesting a category type (starting with a colon) will
101 enable autodie for all built-ins beneath that category. For example,
102 requesting ":file" will enable autodie for "close", "fcntl", "open" and
103 "sysopen".
104 The categories are currently:
106 :all
108 :default
109 :io
110 read
111 seek
112 sysread
113 sysseek
114 syswrite
115 :dbm
116 dbmclose
117 dbmopen
118 :file
119 binmode
120 close
121 chmod
122 chown
123 fcntl
124 flock
125 ioctl
126 open
127 sysopen
128 truncate
129 :filesys
130 chdir
131 closedir
132 opendir
133 link
134 mkdir
135 readlink
136 rename
137 rmdir
138 symlink
139 unlink
140 :ipc
141 kill
142 pipe
143 :msg
144 msgctl
145 msgget
146 msgrcv
147 msgsnd
148 :semaphore
149 semctl
150 semget
151 semop
152 :shm
153 shmctl
154 shmget
155 shmread
156 :socket
157 accept
158 bind
159 connect
160 getsockopt
161 listen
162 recv
163 send
164 setsockopt
165 shutdown
166 socketpair
167 :threads
168 fork
169 :system
170 system
171 exec
172 Note that while the above category system is presently a strict
174 hierarchy, this should not be assumed.
175 A plain "use autodie" implies "use autodie qw(:default)". Note that
177 "system" and "exec" are not enabled by default. "system" requires the
178 optional IPC::System::Simple module to be installed, and enabling
179 "system" or "exec" will invalidate their exotic forms. See "BUGS"
180 below for more details.
181 The syntax:
183 use autodie qw(:1.994);
185 allows the ":default" list from a particular version to be used. This
187 provides the convenience of using the default methods, but the surety
188 that no behavioral changes will occur if the "autodie" module is
189 upgraded.
190 "autodie" can be enabled for all of Perl's built-ins, including
192 "system" and "exec" with:
193 use autodie qw(:all);
195
197 print
198 The autodie pragma <does not check calls to "print">.
199 flock
201 It is not considered an error for "flock" to return false if it fails
202 due to an "EWOULDBLOCK" (or equivalent) condition. This means one can
203 still use the common convention of testing the return value of "flock"
204 when called with the "LOCK_NB" option:
205 use autodie;
207 if ( flock($fh, LOCK_EX | LOCK_NB) ) {
209 # We have a lock
210 }
211 Autodying "flock" will generate an exception if "flock" returns false
213 with any other error.
214 system/exec
216 The "system" built-in is considered to have failed in the following
217 circumstances:
218 · The command does not start.
220 · The command is killed by a signal.
222 · The command returns a non-zero exit value (but see below).
224 On success, the autodying form of "system" returns the exit value
226 rather than the contents of $?.
227 Additional allowable exit values can be supplied as an optional first
229 argument to autodying "system":
230 system( [ 0, 1, 2 ], $cmd, @args); # 0,1,2 are good exit values
232 "autodie" uses the IPC::System::Simple module to change "system". See
234 its documentation for further information.
235 Applying "autodie" to "system" or "exec" causes the exotic forms
237 "system { $cmd } @args " or "exec { $cmd } @args" to be considered a
238 syntax error until the end of the lexical scope. If you really need to
239 use the exotic form, you can call "CORE::system" or "CORE::exec"
240 instead, or use "no autodie qw(system exec)" before calling the exotic
241 form.
242
244 Functions called in list context are assumed to have failed if they
245 return an empty list, or a list consisting only of a single undef
246 element.
247 Some builtins (e.g. "chdir" or "truncate") has a call signature that
249 cannot completely be representated with a Perl prototype. This means
250 that some valid Perl code will be invalid under autodie. As an
251 example:
252 chdir(BAREWORD);
254 Without autodie (and assuming BAREWORD is an open filehandle/dirhandle)
256 this is a valid call to chdir. But under autodie, "chdir" will behave
257 like it had the prototype ";$" and thus BAREWORD will be a syntax error
258 (under "use strict". Without strict, it will interpreted as a
259 filename).
260
262 :void cannot be used with lexical scope
263 The ":void" option is supported in Fatal, but not "autodie". To
264 workaround this, "autodie" may be explicitly disabled until the end
265 of the current block with "no autodie". To disable autodie for
266 only a single function (eg, open) use "no autodie qw(open)".
267 "autodie" performs no checking of called context to determine
269 whether to throw an exception; the explicitness of error handling
270 with "autodie" is a deliberate feature.
271 No user hints defined for %s
273 You've insisted on hints for user-subroutines, either by pre-
274 pending a "!" to the subroutine name itself, or earlier in the list
275 of arguments to "autodie". However the subroutine in question does
276 not have any hints available.
277 See also "DIAGNOSTICS" in Fatal.
279
281 "Used only once" warnings can be generated when "autodie" or "Fatal" is
282 used with package filehandles (eg, "FILE"). Scalar filehandles are
283 strongly recommended instead.
284 When using "autodie" or "Fatal" with user subroutines, the declaration
286 of those subroutines must appear before the first use of "Fatal" or
287 "autodie", or have been exported from a module. Attempting to use
288 "Fatal" or "autodie" on other user subroutines will result in a
289 compile-time error.
290 Due to a bug in Perl, "autodie" may "lose" any format which has the
292 same name as an autodying built-in or function.
293 "autodie" may not work correctly if used inside a file with a name that
295 looks like a string eval, such as eval [4m(3).
296 autodie and string eval
298 Due to the current implementation of "autodie", unexpected results may
299 be seen when used near or with the string version of eval. None of
300 these bugs exist when using block eval.
301 Under Perl 5.8 only, "autodie" does not propagate into string "eval"
303 statements, although it can be explicitly enabled inside a string
304 "eval".
305 Under Perl 5.10 only, using a string eval when "autodie" is in effect
307 can cause the autodie behaviour to leak into the surrounding scope.
308 This can be worked around by using a "no autodie" at the end of the
309 scope to explicitly remove autodie's effects, or by avoiding the use of
310 string eval.
311 None of these bugs exist when using block eval. The use of "autodie"
313 with block eval is considered good practice.
314 REPORTING BUGS
316 Please report bugs via the GitHub Issue Tracker at
317 <https://github.com/pjf/autodie/issues> or via the CPAN Request Tracker
318 at <https://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>.
319
321 If you find this module useful, please consider rating it on the CPAN
322 Ratings service at
323 <http://cpanratings.perl.org/rate?distribution=autodie> .
324 The module author loves to hear how "autodie" has made your life better
326 (or worse). Feedback can be sent to <pjf@perltraining.com.au>.
327
329 Copyright 2008-2009, Paul Fenwick <pjf@perltraining.com.au>
330
332 This module is free software. You may distribute it under the same
333 terms as Perl itself.
334
336 Fatal, autodie::exception, autodie::hints, IPC::System::Simple
337 Perl tips, autodie at <http://perltraining.com.au/tips/2008-08-20.html>
339
341 Mark Reed and Roland Giersig -- Klingon translators.
342 See the AUTHORS file for full credits. The latest version of this file
344 can be found at <https://github.com/pjf/autodie/tree/master/AUTHORS> .
345perl v5.28.0 2015-07-09 autodie(3)