NAME

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

SYNOPSIS

use autodie;    # Recommended, implies 'use autodie qw(:all)'

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
}

DESCRIPTION

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

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

        -- Klingon programming proverb.

NOTE! This is BETA code. It is NOT the final release. Implementation and interface may change!

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

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

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

EXCEPTIONS

Exceptions produced by the autodie pragma are members of the 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 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 autodie::exception for further information on interrogating exceptions.

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.

A bare autodie will change from meaning :all to :default before the final release. There is the possibility for :default may contain user-defined subs, or for some built-ins that exist in :all to have been removed from :default.

DIAGNOSTICS

:void cannot be used with lexical scope

The :void option is supported in Fatal, but not autodie. If you want a block of code with autodie turned off, use no autodie instead.

BUGS

Applying autodie to system causes the exotic system { ... } @args form 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 CORE::system instead.

"Used only once" warnings can be generated when autodie or Fatal is used with package filehandles (eg, FILE). It's strongly recommended you use scalar filehandles instead.

There are plenty more bugs! See http://github.com/pfenwick/autodie/tree/master/TODO for a selection of what's remaining to be fixed.

AUTHOR

Copyright 2008, Paul Fenwick <pjf@perltraining.com.au>

LICENSE

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

SEE ALSO

Fatal, autodie::exception, IPC::System::Simple

ACKNOWLEDGEMENTS

Mark Reed and Roland Giersig -- Klingon translators.

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

cpanm autodie

perl -MCPAN -e shell
install autodie