[perl5.git] / lib / autodie.pm

package autodie;
use 5.008;
use strict;
use warnings;

use Fatal ();
our @ISA = qw(Fatal);
our $VERSION;

BEGIN {
    $VERSION = '2.05';
}

use constant ERROR_WRONG_FATAL => q{
Incorrect version of Fatal.pm loaded by autodie.

The autodie pragma uses an updated version of Fatal to do its
heavy lifting.  We seem to have loaded Fatal version %s, which is
probably the version that came with your version of Perl.  However
autodie needs version %s, which would have come bundled with
autodie.

You may be able to solve this problem by adding the following
line of code to your main program, before any use of Fatal or
autodie.

    use lib "%s";

};

# We have to check we've got the right version of Fatal before we
# try to compile the rest of our code, lest we use a constant
# that doesn't exist.

BEGIN {

    # If we have the wrong Fatal, then we've probably loaded the system
    # one, not our own.  Complain, and give a useful hint. ;)

    if ($Fatal::VERSION ne $VERSION) {
        my $autodie_path = $INC{'autodie.pm'};

        $autodie_path =~ s/autodie\.pm//;

        require Carp;

        Carp::croak sprintf(
            ERROR_WRONG_FATAL, $Fatal::VERSION, $VERSION, $autodie_path
        );
    }
}

# When passing args to Fatal we want to keep the first arg
# (our package) in place.  Hence the splice.

sub import {
        splice(@_,1,0,Fatal::LEXICAL_TAG);
        goto &Fatal::import;
}

sub unimport {
        splice(@_,1,0,Fatal::LEXICAL_TAG);
        goto &Fatal::unimport;
}

1;

__END__

=head1 NAME

autodie - Replace functions with ones that succeed or die with lexical scope

=head1 SYNOPSIS

    use autodie;            # Recommended: implies 'use autodie qw(:default)'

    use autodie qw(:all);   # Recommended more: defaults and system/exec.

    use autodie qw(open close);   # open/close succeed or die

    open(my $fh, "<", $filename); # No need to check!

    {
        no autodie qw(open);          # open failures won't die
        open(my $fh, "<", $filename); # Could fail silently!
        no autodie;                   # disable all autodies
    }

=head1 DESCRIPTION

        bIlujDI' yIchegh()Qo'; yIHegh()!

        It is better to die() than to return() in failure.

                -- Klingon programming proverb.

The C<autodie> pragma provides a convenient way to replace functions
that normally return false on failure with equivalents that throw
an exception on failure.

The C<autodie> pragma has I<lexical scope>, meaning that functions
and subroutines altered with C<autodie> will only change their behaviour
until the end of the enclosing block, file, or C<eval>.

If C<system> is specified as an argument to C<autodie>, then it
uses L<IPC::System::Simple> to do the heavy lifting.  See the
description of that module for more information.

=head1 EXCEPTIONS

Exceptions produced by the C<autodie> pragma are members of the
L<autodie::exception> class.  The preferred way to work with
these exceptions under Perl 5.10 is as follows:

    use feature qw(switch);

    eval {
        use autodie;

        open(my $fh, '<', $some_file);

        my @records = <$fh>;

        # Do things with @records...

        close($fh);

    };

    given ($@) {
        when (undef)   { say "No error";                    }
        when ('open')  { say "Error from open";             }
        when (':io')   { say "Non-open, IO error.";         }
        when (':all')  { say "All other autodie errors."    }
        default        { say "Not an autodie error at all." }
    }

Under Perl 5.8, the C<given/when> structure is not available, so the
following structure may be used:

    eval {
        use autodie;

        open(my $fh, '<', $some_file);

        my @records = <$fh>;

        # Do things with @records...

        close($fh);
    };

    if ($@ and $@->isa('autodie::exception')) {
        if ($@->matches('open')) { print "Error from open\n";   }
        if ($@->matches(':io' )) { print "Non-open, IO error."; }
    } elsif ($@) {
        # A non-autodie exception.
    }

See L<autodie::exception> for further information on interrogating
exceptions.

=head1 CATEGORIES

Autodie uses a simple set of categories to group together similar
built-ins.  Requesting a category type (starting with a colon) will
enable autodie for all built-ins beneath that category.  For example,
requesting C<:file> will enable autodie for C<close>, C<fcntl>,
C<fileno>, C<open> and C<sysopen>.

The categories are currently:

    :all
        :default
            :io
                read
                seek
                sysread
                sysseek
                syswrite
                :dbm
                    dbmclose
                    dbmopen
                :file
                    binmode
                    close
                    fcntl
                    fileno
                    flock
                    ioctl
                    open
                    sysopen
                    truncate
                :filesys
                    chdir
                    closedir
                    opendir
                    link
                    mkdir
                    readlink
                    rename
                    rmdir
                    symlink
                    unlink
                :ipc
                    pipe
                    :msg
                        msgctl
                        msgget
                        msgrcv
                        msgsnd
                    :semaphore
                        semctl
                        semget
                        semop
                    :shm
                        shmctl
                        shmget
                        shmread
                :socket
                    accept
                    bind
                    connect
                    getsockopt
                    listen
                    recv
                    send
                    setsockopt
                    shutdown
                    socketpair
            :threads
                fork
        :system
            system
            exec


Note that while the above category system is presently a strict
hierarchy, this should not be assumed.

A plain C<use autodie> implies C<use autodie qw(:default)>.  Note that
C<system> and C<exec> are not enabled by default.  C<system> requires
the optional L<IPC::System::Simple> module to be installed, and enabling
C<system> or C<exec> will invalidate their exotic forms.  See L</BUGS>
below for more details.

The syntax:

    use autodie qw(:1.994);

allows the C<:default> list from a particular version to be used.  This
provides the convenience of using the default methods, but the surety
that no behavorial changes will occur if the C<autodie> module is
upgraded.

C<autodie> can be enabled for all of Perl's built-ins, including
C<system> and C<exec> with:

    use autodie qw(:all);

=head1 FUNCTION SPECIFIC NOTES

=head2 flock

It is not considered an error for C<flock> to return false if it fails
to an C<EWOULDBLOCK> (or equivalent) condition.  This means one can
still use the common convention of testing the return value of
C<flock> when called with the C<LOCK_NB> option:

    use autodie;

    if ( flock($fh, LOCK_EX | LOCK_NB) ) {
        # We have a lock
    }

Autodying C<flock> will generate an exception if C<flock> returns
false with any other error.

=head2 system/exec

The C<system> built-in is considered to have failed in the following
circumstances:

=over 4

=item *

The command does not start.

=item *

The command is killed by a signal.

=item *

The command returns a non-zero exit value (but see below).

=back

On success, the autodying form of C<system> returns the I<exit value>
rather than the contents of C<$?>.

Additional allowable exit values can be supplied as an optional first
argument to autodying C<system>:

    system( [ 0, 1, 2 ], $cmd, @args);  # 0,1,2 are good exit values

C<autodie> uses the L<IPC::System::Simple> module to change C<system>.
See its documentation for further information.

Applying C<autodie> to C<system> or C<exec> causes the exotic
forms C<system { $cmd } @args > or C<exec { $cmd } @args>
to be considered a syntax error until the end of the lexical scope.
If you really need to use the exotic form, you can call C<CORE::system>
or C<CORE::exec> instead, or use C<no autodie qw(system exec)> before
calling the exotic form.

=head1 GOTCHAS

Functions called in list context are assumed to have failed if they
return an empty list, or a list consisting only of a single undef
element.

=head1 DIAGNOSTICS

=over 4

=item :void cannot be used with lexical scope

The C<:void> option is supported in L<Fatal>, but not
C<autodie>.  To workaround this, C<autodie> may be explicitly disabled until
the end of the current block with C<no autodie>.
To disable autodie for only a single function (eg, open)
use C<no autodie qw(open)>.

=item No user hints defined for %s

You've insisted on hints for user-subroutines, either by pre-pending
a C<!> to the subroutine name itself, or earlier in the list of arguments
to C<autodie>.  However the subroutine in question does not have
any hints available.

=back

See also L<Fatal/DIAGNOSTICS>.

=head1 BUGS

"Used only once" warnings can be generated when C<autodie> or C<Fatal>
is used with package filehandles (eg, C<FILE>).  Scalar filehandles are
strongly recommended instead.

Under Perl 5.8 only, C<autodie> I<does not> propagate into string C<eval>
statements, although it can be explicitly enabled inside a string
C<eval>.  This bug does not affect block C<eval> statements in
any version of Perl.

When using C<autodie> or C<Fatal> with user subroutines, the
declaration of those subroutines must appear before the first use of
C<Fatal> or C<autodie>, or have been exported from a module.
Attempting to use C<Fatal> or C<autodie> on other user subroutines will
result in a compile-time error.

Due to a bug in Perl, C<autodie> may "lose" any format which has the
same name as an autodying built-in or function.

=head2 REPORTING BUGS

Please report bugs via the CPAN Request Tracker at
L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>.

=head1 FEEDBACK

If you find this module useful, please consider rating it on the
CPAN Ratings service at
L<http://cpanratings.perl.org/rate?distribution=autodie> .

The module author loves to hear how C<autodie> has made your life
better (or worse).  Feedback can be sent to
E<lt>pjf@perltraining.com.auE<gt>.

=head1 AUTHOR

Copyright 2008-2009, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt>

=head1 LICENSE

This module is free software.  You may distribute it under the
same terms as Perl itself.

=head1 SEE ALSO

L<Fatal>, L<autodie::exception>, L<autodie::hints>, L<IPC::System::Simple>

I<Perl tips, autodie> at
L<http://perltraining.com.au/tips/2008-08-20.html>

=head1 ACKNOWLEDGEMENTS

Mark Reed and Roland Giersig -- Klingon translators.

See the F<AUTHORS> file for full credits.  The latest version of this
file can be found at
L<http://github.com/pfenwick/autodie/tree/master/AUTHORS> .

=cut
Commit	Line	Data
0b09a93a PF	1	package autodie;
	2	use 5.008;
	3	use strict;
	4	use warnings;
	5
	6	use Fatal ();
	7	our @ISA = qw(Fatal);
	8	our $VERSION;
	9
	10	BEGIN {
02b13d1d	11	$VERSION = '2.05';
0b09a93a PF	12	}
	13
	14	use constant ERROR_WRONG_FATAL => q{
	15	Incorrect version of Fatal.pm loaded by autodie.
	16
	17	The autodie pragma uses an updated version of Fatal to do its
	18	heavy lifting. We seem to have loaded Fatal version %s, which is
	19	probably the version that came with your version of Perl. However
	20	autodie needs version %s, which would have come bundled with
	21	autodie.
	22
	23	You may be able to solve this problem by adding the following
	24	line of code to your main program, before any use of Fatal or
	25	autodie.
	26
	27	use lib "%s";
	28
	29	};
	30
	31	# We have to check we've got the right version of Fatal before we
	32	# try to compile the rest of our code, lest we use a constant
	33	# that doesn't exist.
	34
	35	BEGIN {
	36
	37	# If we have the wrong Fatal, then we've probably loaded the system
	38	# one, not our own. Complain, and give a useful hint. ;)
	39
	40	if ($Fatal::VERSION ne $VERSION) {
	41	my $autodie_path = $INC{'autodie.pm'};
	42
	43	$autodie_path =~ s/autodie\.pm//;
	44
	45	require Carp;
	46
	47	Carp::croak sprintf(
	48	ERROR_WRONG_FATAL, $Fatal::VERSION, $VERSION, $autodie_path
	49	);
	50	}
	51	}
	52
	53	# When passing args to Fatal we want to keep the first arg
	54	# (our package) in place. Hence the splice.
	55
	56	sub import {
	57	splice(@_,1,0,Fatal::LEXICAL_TAG);
	58	goto &Fatal::import;
	59	}
	60
	61	sub unimport {
	62	splice(@_,1,0,Fatal::LEXICAL_TAG);
	63	goto &Fatal::unimport;
	64	}
	65
	66	1;
	67
	68	__END__
	69
	70	=head1 NAME
	71
	72	autodie - Replace functions with ones that succeed or die with lexical scope
	73
	74	=head1 SYNOPSIS
	75
9b657a62 PF	76	use autodie; # Recommended: implies 'use autodie qw(:default)'
	77
	78	use autodie qw(:all); # Recommended more: defaults and system/exec.
0b09a93a PF	79
	80	use autodie qw(open close); # open/close succeed or die
	81
	82	open(my $fh, "<", $filename); # No need to check!
	83
	84	{
	85	no autodie qw(open); # open failures won't die
	86	open(my $fh, "<", $filename); # Could fail silently!
	87	no autodie; # disable all autodies
	88	}
	89
	90	=head1 DESCRIPTION
	91
	92	bIlujDI' yIchegh()Qo'; yIHegh()!
	93
	94	It is better to die() than to return() in failure.
	95
	96	-- Klingon programming proverb.
	97
	98	The C<autodie> pragma provides a convenient way to replace functions
	99	that normally return false on failure with equivalents that throw
	100	an exception on failure.
	101
	102	The C<autodie> pragma has I<lexical scope>, meaning that functions
	103	and subroutines altered with C<autodie> will only change their behaviour
	104	until the end of the enclosing block, file, or C<eval>.
	105
	106	If C<system> is specified as an argument to C<autodie>, then it
	107	uses L<IPC::System::Simple> to do the heavy lifting. See the
	108	description of that module for more information.
	109
	110	=head1 EXCEPTIONS
	111
	112	Exceptions produced by the C<autodie> pragma are members of the
	113	L<autodie::exception> class. The preferred way to work with
	114	these exceptions under Perl 5.10 is as follows:
	115
	116	use feature qw(switch);
	117
	118	eval {
	119	use autodie;
	120
	121	open(my $fh, '<', $some_file);
	122
	123	my @records = <$fh>;
	124
	125	# Do things with @records...
	126
	127	close($fh);
	128
	129	};
	130
	131	given ($@) {
	132	when (undef) { say "No error"; }
	133	when ('open') { say "Error from open"; }
	134	when (':io') { say "Non-open, IO error."; }
	135	when (':all') { say "All other autodie errors." }
	136	default { say "Not an autodie error at all." }
	137	}
	138
	139	Under Perl 5.8, the C<given/when> structure is not available, so the
	140	following structure may be used:
	141
	142	eval {
143	use autodie;
144
145	open(my $fh, '<', $some_file);
146
147	my @records = <$fh>;
148
149	# Do things with @records...
150
151	close($fh);
152	};
153
154	if ($@ and $@->isa('autodie::exception')) {
155	if ($@->matches('open')) { print "Error from open\n"; }
156	if ($@->matches(':io' )) { print "Non-open, IO error."; }
157	} elsif ($@) {
158	# A non-autodie exception.
159	}
160
161	See L<autodie::exception> for further information on interrogating
162	exceptions.
163
164	=head1 CATEGORIES
165
166	Autodie uses a simple set of categories to group together similar
167	built-ins. Requesting a category type (starting with a colon) will
168	enable autodie for all built-ins beneath that category. For example,
169	requesting C<:file> will enable autodie for C<close>, C<fcntl>,
170	C<fileno>, C<open> and C<sysopen>.
171
172	The categories are currently:
173
174	:all
175	:default
176	:io
177	read
178	seek
179	sysread
180	sysseek
181	syswrite
182	:dbm
183	dbmclose
184	dbmopen
185	:file
186	binmode
187	close
188	fcntl
189	fileno
190	flock
191	ioctl
192	open
193	sysopen
194	truncate
195	:filesys
196	chdir
197	closedir
198	opendir
199	link
200	mkdir
201	readlink
202	rename
203	rmdir
204	symlink
205	unlink
206	:ipc
207	pipe
208	:msg
209	msgctl
210	msgget
211	msgrcv
212	msgsnd
213	:semaphore
214	semctl
215	semget
216	semop
217	:shm
218	shmctl
219	shmget
220	shmread
221	:socket
222	accept
223	bind
224	connect
225	getsockopt
226	listen
227	recv
228	send
229	setsockopt
230	shutdown
231	socketpair
232	:threads
233	fork
234	:system
235	system
236	exec
237
238
239	Note that while the above category system is presently a strict
240	hierarchy, this should not be assumed.
241
242	A plain C<use autodie> implies C<use autodie qw(:default)>. Note that
243	C<system> and C<exec> are not enabled by default. C<system> requires
244	the optional L<IPC::System::Simple> module to be installed, and enabling
245	C<system> or C<exec> will invalidate their exotic forms. See L</BUGS>
246	below for more details.
247
248	The syntax:
249
250	use autodie qw(:1.994);
251
252	allows the C<:default> list from a particular version to be used. This
9b657a62	253	provides the convenience of using the default methods, but the surety
0b09a93a PF	254	that no behavorial changes will occur if the C<autodie> module is
	255	upgraded.
	256
eb8d423f	257	C<autodie> can be enabled for all of Perl's built-ins, including
9b657a62 PF	258	C<system> and C<exec> with:
	259
	260	use autodie qw(:all);
	261
0b09a93a PF	262	=head1 FUNCTION SPECIFIC NOTES
	263
	264	=head2 flock
	265
	266	It is not considered an error for C<flock> to return false if it fails
	267	to an C<EWOULDBLOCK> (or equivalent) condition. This means one can
	268	still use the common convention of testing the return value of
	269	C<flock> when called with the C<LOCK_NB> option:
	270
	271	use autodie;
	272
	273	if ( flock($fh, LOCK_EX \| LOCK_NB) ) {
	274	# We have a lock
	275	}
	276
	277	Autodying C<flock> will generate an exception if C<flock> returns
	278	false with any other error.
	279
	280	=head2 system/exec
	281
9b657a62 PF	282	The C<system> built-in is considered to have failed in the following
	283	circumstances:
	284
	285	=over 4
	286
	287	=item *
	288
	289	The command does not start.
	290
	291	=item *
	292
	293	The command is killed by a signal.
	294
	295	=item *
	296
	297	The command returns a non-zero exit value (but see below).
	298
	299	=back
	300
	301	On success, the autodying form of C<system> returns the I<exit value>
	302	rather than the contents of C<$?>.
	303
	304	Additional allowable exit values can be supplied as an optional first
	305	argument to autodying C<system>:
	306
	307	system( [ 0, 1, 2 ], $cmd, @args); # 0,1,2 are good exit values
	308
	309	C<autodie> uses the L<IPC::System::Simple> module to change C<system>.
	310	See its documentation for further information.
	311
0b09a93a PF	312	Applying C<autodie> to C<system> or C<exec> causes the exotic
	313	forms C<system { $cmd } @args > or C<exec { $cmd } @args>
	314	to be considered a syntax error until the end of the lexical scope.
	315	If you really need to use the exotic form, you can call C<CORE::system>
	316	or C<CORE::exec> instead, or use C<no autodie qw(system exec)> before
	317	calling the exotic form.
	318
	319	=head1 GOTCHAS
	320
	321	Functions called in list context are assumed to have failed if they
	322	return an empty list, or a list consisting only of a single undef
	323	element.
	324
	325	=head1 DIAGNOSTICS
	326
	327	=over 4
	328
	329	=item :void cannot be used with lexical scope
	330
	331	The C<:void> option is supported in L<Fatal>, but not
eb8d423f PF	332	C<autodie>. To workaround this, C<autodie> may be explicitly disabled until
eb8d423f PF	333	the end of the current block with C<no autodie>.
0b09a93a	334	To disable autodie for only a single function (eg, open)
9b657a62 PF	335	use C<no autodie qw(open)>.
	336
	337	=item No user hints defined for %s
	338
	339	You've insisted on hints for user-subroutines, either by pre-pending
	340	a C<!> to the subroutine name itself, or earlier in the list of arguments
	341	to C<autodie>. However the subroutine in question does not have
	342	any hints available.
0b09a93a PF	343
	344	=back
	345
	346	See also L<Fatal/DIAGNOSTICS>.
	347
	348	=head1 BUGS
	349
	350	"Used only once" warnings can be generated when C<autodie> or C<Fatal>
eb8d423f PF	351	is used with package filehandles (eg, C<FILE>). Scalar filehandles are
eb8d423f PF	352	strongly recommended instead.
0b09a93a	353
db4e6d09 PF	354	Under Perl 5.8 only, C<autodie> I<does not> propagate into string C<eval>
	355	statements, although it can be explicitly enabled inside a string
	356	C<eval>. This bug does not affect block C<eval> statements in
	357	any version of Perl.
	358
0b09a93a PF	359	When using C<autodie> or C<Fatal> with user subroutines, the
	360	declaration of those subroutines must appear before the first use of
	361	C<Fatal> or C<autodie>, or have been exported from a module.
9b657a62	362	Attempting to use C<Fatal> or C<autodie> on other user subroutines will
0b09a93a PF	363	result in a compile-time error.
0b09a93a PF	364
9b657a62 PF	365	Due to a bug in Perl, C<autodie> may "lose" any format which has the
	366	same name as an autodying built-in or function.
	367
0b09a93a PF	368	=head2 REPORTING BUGS
	369
	370	Please report bugs via the CPAN Request Tracker at
	371	L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=autodie>.
	372
	373	=head1 FEEDBACK
	374
	375	If you find this module useful, please consider rating it on the
	376	CPAN Ratings service at
	377	L<http://cpanratings.perl.org/rate?distribution=autodie> .
	378
	379	The module author loves to hear how C<autodie> has made your life
	380	better (or worse). Feedback can be sent to
	381	E<lt>pjf@perltraining.com.auE<gt>.
	382
	383	=head1 AUTHOR
	384
9b657a62	385	Copyright 2008-2009, Paul Fenwick E<lt>pjf@perltraining.com.auE<gt>
0b09a93a PF	386
	387	=head1 LICENSE
	388
	389	This module is free software. You may distribute it under the
	390	same terms as Perl itself.
	391
	392	=head1 SEE ALSO
	393
9b657a62	394	L<Fatal>, L<autodie::exception>, L<autodie::hints>, L<IPC::System::Simple>
0b09a93a PF	395
	396	I<Perl tips, autodie> at
	397	L<http://perltraining.com.au/tips/2008-08-20.html>
	398
	399	=head1 ACKNOWLEDGEMENTS
	400
	401	Mark Reed and Roland Giersig -- Klingon translators.
	402
	403	See the F<AUTHORS> file for full credits. The latest version of this
	404	file can be found at
9b657a62	405	L<http://github.com/pfenwick/autodie/tree/master/AUTHORS> .
0b09a93a PF	406
0b09a93a PF	407	=cut