1autodie(3pm) Perl Programmers Reference Guide autodie(3pm)
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 fcntl
120 fileno
121 flock
122 ioctl
123 open
124 sysopen
125 truncate
126 :filesys
127 chdir
128 closedir
129 opendir
130 link
131 mkdir
132 readlink
133 rename
134 rmdir
135 symlink
136 unlink
137 :ipc
138 pipe
139 :msg
140 msgctl
141 msgget
142 msgrcv
143 msgsnd
144 :semaphore
145 semctl
146 semget
147 semop
148 :shm
149 shmctl
150 shmget
151 shmread
152 :socket
153 accept
154 bind
155 connect
156 getsockopt
157 listen
158 recv
159 send
160 setsockopt
161 shutdown
162 socketpair
163 :threads
164 fork
165 :system
166 system
167 exec
168 Note that while the above category system is presently a strict
170 hierarchy, this should not be assumed.
171 A plain "use autodie" implies "use autodie qw(:default)". Note that
173 "system" and "exec" are not enabled by default. "system" requires the
174 optional IPC::System::Simple module to be installed, and enabling
175 "system" or "exec" will invalidate their exotic forms. See "BUGS"
176 below for more details.
177 The syntax:
179 use autodie qw(:1.994);
181 allows the ":default" list from a particular version to be used. This
183 provides the convenience of using the default methods, but the surety
184 that no behavorial changes will occur if the "autodie" module is
185 upgraded.
186 "autodie" can be enabled for all of Perl's built-ins, including
188 "system" and "exec" with:
189 use autodie qw(:all);
191
193 flock
194 It is not considered an error for "flock" to return false if it fails
195 to an "EWOULDBLOCK" (or equivalent) condition. This means one can
196 still use the common convention of testing the return value of "flock"
197 when called with the "LOCK_NB" option:
198 use autodie;
200 if ( flock($fh, LOCK_EX | LOCK_NB) ) {
202 # We have a lock
203 }
204 Autodying "flock" will generate an exception if "flock" returns false
206 with any other error.
207 system/exec
209 The "system" built-in is considered to have failed in the following
210 circumstances:
211 · The command does not start.
213 · The command is killed by a signal.
215 · The command returns a non-zero exit value (but see below).
217 On success, the autodying form of "system" returns the exit value
219 rather than the contents of $?.
220 Additional allowable exit values can be supplied as an optional first
222 argument to autodying "system":
223 system( [ 0, 1, 2 ], $cmd, @args); # 0,1,2 are good exit values
225 "autodie" uses the IPC::System::Simple module to change "system". See
227 its documentation for further information.
228 Applying "autodie" to "system" or "exec" causes the exotic forms
230 "system { $cmd } @args " or "exec { $cmd } @args" to be considered a
231 syntax error until the end of the lexical scope. If you really need to
232 use the exotic form, you can call "CORE::system" or "CORE::exec"
233 instead, or use "no autodie qw(system exec)" before calling the exotic
234 form.
235
237 Functions called in list context are assumed to have failed if they
238 return an empty list, or a list consisting only of a single undef
239 element.
240
242 :void cannot be used with lexical scope
243 The ":void" option is supported in Fatal, but not "autodie". To
244 workaround this, "autodie" may be explicitly disabled until the end
245 of the current block with "no autodie". To disable autodie for
246 only a single function (eg, open) use "no autodie qw(open)".
247 No user hints defined for %s
249 You've insisted on hints for user-subroutines, either by pre-
250 pending a "!" to the subroutine name itself, or earlier in the list
251 of arguments to "autodie". However the subroutine in question does
252 not have any hints available.
253 See also "DIAGNOSTICS" in Fatal.
255
257 "Used only once" warnings can be generated when "autodie" or "Fatal" is
258 used with package filehandles (eg, "FILE"). Scalar filehandles are
259 strongly recommended instead.
260 When using "autodie" or "Fatal" with user subroutines, the declaration
262 of those subroutines must appear before the first use of "Fatal" or
263 "autodie", or have been exported from a module. Attempting to use
264 "Fatal" or "autodie" on other user subroutines will result in a
265 compile-time error.
266 Due to a bug in Perl, "autodie" may "lose" any format which has the
268 same name as an autodying built-in or function.
269 "autodie" may not work correctly if used inside a file with a name that
271 looks like a string eval, such as eval [4m(3).
272 autodie and string eval
274 Due to the current implementation of "autodie", unexpected results may
275 be seen when used near or with the string version of eval. None of
276 these bugs exist when using block eval.
277 Under Perl 5.8 only, "autodie" does not propagate into string "eval"
279 statements, although it can be explicitly enabled inside a string
280 "eval".
281 Under Perl 5.10 only, using a string eval when "autodie" is in effect
283 can cause the autodie behaviour to leak into the surrounding scope.
284 This can be worked around by using a "no autodie" at the end of the
285 scope to explicitly remove autodie's effects, or by avoiding the use of
286 string eval.
287 None of these bugs exist when using block eval. The use of "autodie"
289 with block eval is considered good practice.
290 REPORTING BUGS
292 Please report bugs via the CPAN Request Tracker at
293 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>.
294
296 If you find this module useful, please consider rating it on the CPAN
297 Ratings service at
298 <http://cpanratings.perl.org/rate?distribution=autodie> .
299 The module author loves to hear how "autodie" has made your life better
301 (or worse). Feedback can be sent to <pjf@perltraining.com.au>.
302
304 Copyright 2008-2009, Paul Fenwick <pjf@perltraining.com.au>
305
307 This module is free software. You may distribute it under the same
308 terms as Perl itself.
309
311 Fatal, autodie::exception, autodie::hints, IPC::System::Simple
312 Perl tips, autodie at <http://perltraining.com.au/tips/2008-08-20.html>
314
316 Mark Reed and Roland Giersig -- Klingon translators.
317 See the AUTHORS file for full credits. The latest version of this file
319 can be found at
320 <http://github.com/pfenwick/autodie/tree/master/AUTHORS> .
321perl v5.10.1 2009-07-25 autodie(3pm)