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