<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">package autodie::exception;
use 5.008;
use strict;
use warnings;
use Carp qw(croak);

our $DEBUG = 0;

use overload
    q{""} =&gt; "stringify"
;

# Overload smart-match only if we're using 5.10

use if ($] &gt;= 5.010), overload =&gt; '~~'  =&gt; "matches";

our $VERSION = '2.13';

my $PACKAGE = __PACKAGE__;  # Useful to have a scalar for hash keys.

=head1 NAME

autodie::exception - Exceptions from autodying functions.

=head1 SYNOPSIS

    eval {
        use autodie;

        open(my $fh, '&lt;', 'some_file.txt');

        ...
    };

    if (my $E = $@) {
        say "Ooops!  ",$E-&gt;caller," had problems: $@";
    }


=head1 DESCRIPTION

When an L&lt;autodie&gt; enabled function fails, it generates an
C&lt;autodie::exception&gt; object.  This can be interrogated to
determine further information about the error that occurred.

This document is broken into two sections; those methods that
are most useful to the end-developer, and those methods for
anyone wishing to subclass or get very familiar with
C&lt;autodie::exception&gt;.

=head2 Common Methods

These methods are intended to be used in the everyday dealing
of exceptions.

The following assume that the error has been copied into
a separate scalar:

    if ($E = $@) {
        ...
    }

This is not required, but is recommended in case any code
is called which may reset or alter C&lt;$@&gt;.

=cut

=head3 args

    my $array_ref = $E-&gt;args;

Provides a reference to the arguments passed to the subroutine
that died.

=cut

sub args        { return $_[0]-&gt;{$PACKAGE}{args}; }

=head3 function

    my $sub = $E-&gt;function;

The subroutine (including package) that threw the exception.

=cut

sub function   { return $_[0]-&gt;{$PACKAGE}{function};  }

=head3 file

    my $file = $E-&gt;file;

The file in which the error occurred (eg, C&lt;myscript.pl&gt; or
C&lt;MyTest.pm&gt;).

=cut

sub file        { return $_[0]-&gt;{$PACKAGE}{file};  }

=head3 package

    my $package = $E-&gt;package;

The package from which the exceptional subroutine was called.

=cut

sub package     { return $_[0]-&gt;{$PACKAGE}{package}; }

=head3 caller

    my $caller = $E-&gt;caller;

The subroutine that I&lt;called&gt; the exceptional code.

=cut

sub caller      { return $_[0]-&gt;{$PACKAGE}{caller};  }

=head3 line

    my $line = $E-&gt;line;

The line in C&lt;&lt; $E-&gt;file &gt;&gt; where the exceptional code was called.

=cut

sub line        { return $_[0]-&gt;{$PACKAGE}{line};  }

=head3 context

    my $context = $E-&gt;context;

The context in which the subroutine was called.  This can be
'list', 'scalar', or undefined (unknown).  It will never be 'void', as
C&lt;autodie&gt; always captures the return value in one way or another.

=cut

sub context     { return $_[0]-&gt;{$PACKAGE}{context} }

=head3 return

    my $return_value = $E-&gt;return;

The value(s) returned by the failed subroutine.  When the subroutine
was called in a list context, this will always be a reference to an
array containing the results.  When the subroutine was called in
a scalar context, this will be the actual scalar returned.

=cut

sub return      { return $_[0]-&gt;{$PACKAGE}{return} }

=head3 errno

    my $errno = $E-&gt;errno;

The value of C&lt;$!&gt; at the time when the exception occurred.

B&lt;NOTE&gt;: This method will leave the main C&lt;autodie::exception&gt; class
and become part of a role in the future.  You should only call
C&lt;errno&gt; for exceptions where C&lt;$!&gt; would reasonably have been
set on failure.

=cut

# TODO: Make errno part of a role.  It doesn't make sense for
# everything.

sub errno       { return $_[0]-&gt;{$PACKAGE}{errno}; }

=head3 eval_error

    my $old_eval_error = $E-&gt;eval_error;

The contents of C&lt;$@&gt; immediately after autodie triggered an
exception.  This may be useful when dealing with modules such
as L&lt;Text::Balanced&gt; that set (but do not throw) C&lt;$@&gt; on error.

=cut

sub eval_error { return $_[0]-&gt;{$PACKAGE}{eval_error}; }

=head3 matches

    if ( $e-&gt;matches('open') ) { ... }

    if ( $e ~~ 'open' ) { ... }

C&lt;matches&gt; is used to determine whether a
given exception matches a particular role.  On Perl 5.10,
using smart-match (C&lt;~~&gt;) with an C&lt;autodie::exception&gt; object
will use C&lt;matches&gt; underneath.

An exception is considered to match a string if:

=over 4

=item *

For a string not starting with a colon, the string exactly matches the
package and subroutine that threw the exception.  For example,
C&lt;MyModule::log&gt;.  If the string does not contain a package name,
C&lt;CORE::&gt; is assumed.

=item *

For a string that does start with a colon, if the subroutine
throwing the exception I&lt;does&gt; that behaviour.  For example, the
C&lt;CORE::open&gt; subroutine does C&lt;:file&gt;, C&lt;:io&gt; and C&lt;:all&gt;.

See L&lt;autodie/CATEGORIES&gt; for futher information.

=back

=cut

{
    my (%cache);

    sub matches {
        my ($this, $that) = @_;

        # TODO - Handle references
        croak "UNIMPLEMENTED" if ref $that;

        my $sub = $this-&gt;function;

        if ($DEBUG) {
            my $sub2 = $this-&gt;function;
            warn "Smart-matching $that against $sub / $sub2\n";
        }

        # Direct subname match.
        return 1 if $that eq $sub;
        return 1 if $that !~ /:/ and "CORE::$that" eq $sub;
        return 0 if $that !~ /^:/;

        # Cached match / check tags.
        require Fatal;

        if (exists $cache{$sub}{$that}) {
            return $cache{$sub}{$that};
        }

        # This rather awful looking line checks to see if our sub is in the
        # list of expanded tags, caches it, and returns the result.

        return $cache{$sub}{$that} = grep { $_ eq $sub } @{ $this-&gt;_expand_tag($that) };
    }
}

# This exists primarily so that child classes can override or
# augment it if they wish.

sub _expand_tag {
    my ($this, @args) = @_;

    return Fatal-&gt;_expand_tag(@args);
}

=head2 Advanced methods

The following methods, while usable from anywhere, are primarily
intended for developers wishing to subclass C&lt;autodie::exception&gt;,
write code that registers custom error messages, or otherwise
work closely with the C&lt;autodie::exception&gt; model.

=cut

# The table below records customer formatters.
# TODO - Should this be a package var instead?
# TODO - Should these be in a completely different file, or
#        perhaps loaded on demand?  Most formatters will never
#        get used in most programs.

my %formatter_of = (
    'CORE::close'   =&gt; \&amp;_format_close,
    'CORE::open'    =&gt; \&amp;_format_open,
    'CORE::dbmopen' =&gt; \&amp;_format_dbmopen,
    'CORE::flock'   =&gt; \&amp;_format_flock,
);

# TODO: Our tests only check LOCK_EX | LOCK_NB is properly
# formatted.  Try other combinations and ensure they work
# correctly.

sub _format_flock {
    my ($this) = @_;

    require Fcntl;

    my $filehandle = $this-&gt;args-&gt;[0];
    my $raw_mode   = $this-&gt;args-&gt;[1];

    my $mode_type;
    my $lock_unlock;

    if ($raw_mode &amp; Fcntl::LOCK_EX() ) {
        $lock_unlock = "lock";
        $mode_type = "for exclusive access";
    }
    elsif ($raw_mode &amp; Fcntl::LOCK_SH() ) {
        $lock_unlock = "lock";
        $mode_type = "for shared access";
    }
    elsif ($raw_mode &amp; Fcntl::LOCK_UN() ) {
        $lock_unlock = "unlock";
        $mode_type = "";
    }
    else {
        # I've got no idea what they're trying to do.
        $lock_unlock = "lock";
        $mode_type = "with mode $raw_mode";
    }

    my $cooked_filehandle;

    if ($filehandle and not ref $filehandle) {

        # A package filehandle with a name!

        $cooked_filehandle = " $filehandle";
    }
    else {
        # Otherwise we have a scalar filehandle.

        $cooked_filehandle = '';

    }

    local $! = $this-&gt;errno;

    return "Can't $lock_unlock filehandle$cooked_filehandle $mode_type: $!";

}

# Default formatter for CORE::dbmopen
sub _format_dbmopen {
    my ($this) = @_;
    my @args   = @{$this-&gt;args};

    # TODO: Presently, $args flattens out the (usually empty) hash
    # which is passed as the first argument to dbmopen.  This is
    # a bug in our args handling code (taking a reference to it would
    # be better), but for the moment we'll just examine the end of
    # our arguments list for message formatting.

    my $mode = $args[-1];
    my $file = $args[-2];

    # If we have a mask, then display it in octal, not decimal.
    # We don't do this if it already looks octalish, or doesn't
    # look like a number.

    if ($mode =~ /^[^\D0]\d+$/) {
        $mode = sprintf("0%lo", $mode);
    };

    local $! = $this-&gt;errno;

    return "Can't dbmopen(%hash, '$file', $mode): '$!'";
}

# Default formatter for CORE::close

sub _format_close {
    my ($this) = @_;
    my $close_arg = $this-&gt;args-&gt;[0];

    local $! = $this-&gt;errno;

    # If we've got an old-style filehandle, mention it.
    if ($close_arg and not ref $close_arg) {
        return "Can't close filehandle '$close_arg': '$!'";
    }

    # TODO - This will probably produce an ugly error.  Test and fix.
    return "Can't close($close_arg) filehandle: '$!'";

}

# Default formatter for CORE::open

use constant _FORMAT_OPEN =&gt; "Can't open '%s' for %s: '%s'";

sub _format_open_with_mode {
    my ($this, $mode, $file, $error) = @_;

    my $wordy_mode;

    if    ($mode eq '&lt;')  { $wordy_mode = 'reading';   }
    elsif ($mode eq '&gt;')  { $wordy_mode = 'writing';   }
    elsif ($mode eq '&gt;&gt;') { $wordy_mode = 'appending'; }

    return sprintf _FORMAT_OPEN, $file, $wordy_mode, $error if $wordy_mode;

    Carp::confess("Internal autodie::exception error: Don't know how to format mode '$mode'.");

}

sub _format_open {
    my ($this) = @_;

    my @open_args = @{$this-&gt;args};

    # Use the default formatter for single-arg and many-arg open
    if (@open_args &lt;= 1 or @open_args &gt;= 4) {
        return $this-&gt;format_default;
    }

    # For two arg open, we have to extract the mode
    if (@open_args == 2) {
        my ($fh, $file) = @open_args;

        if (ref($fh) eq "GLOB") {
            $fh = '$fh';
        }

        my ($mode) = $file =~ m{
            ^\s*                # Spaces before mode
            (
                (?&gt;             # Non-backtracking subexp.
                    &lt;           # Reading
                    |&gt;&gt;?        # Writing/appending
                )
            )
            [^&amp;]                # Not an ampersand (which means a dup)
        }x;

        if (not $mode) {
            # Maybe it's a 2-arg open without any mode at all?
            # Detect the most simple case for this, where our
            # file consists only of word characters.

            if ( $file =~ m{^\s*\w+\s*$} ) {
                $mode = '&lt;'
            }
            else {
                # Otherwise, we've got no idea what's going on.
                # Use the default.
                return $this-&gt;format_default;
            }
        }

        # Localising $! means perl make make it a pretty error for us.
        local $! = $this-&gt;errno;

        return $this-&gt;_format_open_with_mode($mode, $file, $!);
    }

    # Here we must be using three arg open.

    my $file = $open_args[2];

    local $! = $this-&gt;errno;

    my $mode = $open_args[1];

    local $@;

    my $msg = eval { $this-&gt;_format_open_with_mode($mode, $file, $!); };

    return $msg if $msg;

    # Default message (for pipes and odd things)

    return "Can't open '$file' with mode '$open_args[1]': '$!'";
}

=head3 register

    autodie::exception-&gt;register( 'CORE::open' =&gt; \&amp;mysub );

The C&lt;register&gt; method allows for the registration of a message
handler for a given subroutine.  The full subroutine name including
the package should be used.

Registered message handlers will receive the C&lt;autodie::exception&gt;
object as the first parameter.

=cut

sub register {
    my ($class, $symbol, $handler) = @_;

    croak "Incorrect call to autodie::register" if @_ != 3;

    $formatter_of{$symbol} = $handler;

}

=head3 add_file_and_line

    say "Problem occurred",$@-&gt;add_file_and_line;

Returns the string C&lt; at %s line %d&gt;, where C&lt;%s&gt; is replaced with
the filename, and C&lt;%d&gt; is replaced with the line number.

Primarily intended for use by format handlers.

=cut

# Simply produces the file and line number; intended to be added
# to the end of error messages.

sub add_file_and_line {
    my ($this) = @_;

    return sprintf(" at %s line %d\n", $this-&gt;file, $this-&gt;line);
}

=head3 stringify

    say "The error was: ",$@-&gt;stringify;

Formats the error as a human readable string.  Usually there's no
reason to call this directly, as it is used automatically if an
C&lt;autodie::exception&gt; object is ever used as a string.

Child classes can override this method to change how they're
stringified.

=cut

sub stringify {
    my ($this) = @_;

    my $call        =  $this-&gt;function;

    if ($DEBUG) {
        my $dying_pkg   = $this-&gt;package;
        my $sub   = $this-&gt;function;
        my $caller = $this-&gt;caller;
        warn "Stringifing exception for $dying_pkg :: $sub / $caller / $call\n";
    }

    # TODO - This isn't using inheritance.  Should it?
    if ( my $sub = $formatter_of{$call} ) {
        return $sub-&gt;($this) . $this-&gt;add_file_and_line;
    }

    return $this-&gt;format_default . $this-&gt;add_file_and_line;

}

=head3 format_default

    my $error_string = $E-&gt;format_default;

This produces the default error string for the given exception,
I&lt;without using any registered message handlers&gt;.  It is primarily
intended to be called from a message handler when they have
been passed an exception they don't want to format.

Child classes can override this method to change how default
messages are formatted.

=cut

# TODO: This produces ugly errors.  Is there any way we can
# dig around to find the actual variable names?  I know perl 5.10
# does some dark and terrible magicks to find them for undef warnings.

sub format_default {
    my ($this) = @_;

    my $call        =  $this-&gt;function;

    local $! = $this-&gt;errno;

    # TODO: This is probably a good idea for CORE, is it
    # a good idea for other subs?

    # Trim package name off dying sub for error messages.
    $call =~ s/.*:://;

    # Walk through all our arguments, and...
    #
    #   * Replace undef with the word 'undef'
    #   * Replace globs with the string '$fh'
    #   * Quote all other args.

    my @args = @{ $this-&gt;args() };

    foreach my $arg (@args) {
       if    (not defined($arg))   { $arg = 'undef' }
       elsif (ref($arg) eq "GLOB") { $arg = '$fh'   }
       else                        { $arg = qq{'$arg'} }
    }

    # Format our beautiful error.

    return "Can't $call(".  join(q{, }, @args) . "): $!" ;

    # TODO - Handle user-defined errors from hash.

    # TODO - Handle default error messages.

}

=head3 new

    my $error = autodie::exception-&gt;new(
        args =&gt; \@_,
        function =&gt; "CORE::open",
        errno =&gt; $!,
        context =&gt; 'scalar',
        return =&gt; undef,
    );


Creates a new C&lt;autodie::exception&gt; object.  Normally called
directly from an autodying function.  The C&lt;function&gt; argument
is required, its the function we were trying to call that
generated the exception.  The C&lt;args&gt; parameter is optional.

The C&lt;errno&gt; value is optional.  In versions of C&lt;autodie::exception&gt;
1.99 and earlier the code would try to automatically use the
current value of C&lt;$!&gt;, but this was unreliable and is no longer
supported.

Atrributes such as package, file, and caller are determined
automatically, and cannot be specified.

=cut

sub new {
    my ($class, @args) = @_;

    my $this = {};

    bless($this,$class);

    # I'd love to use EVERY here, but it causes our code to die
    # because it wants to stringify our objects before they're
    # initialised, causing everything to explode.

    $this-&gt;_init(@args);

    return $this;
}

sub _init {

    my ($this, %args) = @_;

    # Capturing errno here is not necessarily reliable.
    my $original_errno = $!;

    our $init_called = 1;

    my $class = ref $this;

    # We're going to walk up our call stack, looking for the
    # first thing that doesn't look like our exception
    # code, autodie/Fatal, or some whacky eval.

    my ($package, $file, $line, $sub);

    my $depth = 0;

    while (1) {
        $depth++;

        ($package, $file, $line, $sub) = CORE::caller($depth);

        # Skip up the call stack until we find something outside
        # of the Fatal/autodie/eval space.

        next if $package-&gt;isa('Fatal');
        next if $package-&gt;isa($class);
        next if $package-&gt;isa(__PACKAGE__);
        next if $file =~ /^\(eval\s\d+\)$/;

        last;

    }

    # We now have everything correct, *except* for our subroutine
    # name.  If it's __ANON__ or (eval), then we need to keep on
    # digging deeper into our stack to find the real name.  However we
    # don't update our other information, since that will be correct
    # for our current exception.

    my $first_guess_subroutine = $sub;

    while (defined $sub and $sub =~ /^\(eval\)$|::__ANON__$/) {
        $depth++;

        $sub = (CORE::caller($depth))[3];
    }

    # If we end up falling out the bottom of our stack, then our
    # __ANON__ guess is the best we can get.  This includes situations
    # where we were called from the top level of a program.

    if (not defined $sub) {
        $sub = $first_guess_subroutine;
    }

    $this-&gt;{$PACKAGE}{package} = $package;
    $this-&gt;{$PACKAGE}{file}    = $file;
    $this-&gt;{$PACKAGE}{line}    = $line;
    $this-&gt;{$PACKAGE}{caller}  = $sub;
    $this-&gt;{$PACKAGE}{package} = $package;

    $this-&gt;{$PACKAGE}{errno}   = $args{errno} || 0;

    $this-&gt;{$PACKAGE}{context} = $args{context};
    $this-&gt;{$PACKAGE}{return}  = $args{return};
    $this-&gt;{$PACKAGE}{eval_error}  = $args{eval_error};

    $this-&gt;{$PACKAGE}{args}    = $args{args} || [];
    $this-&gt;{$PACKAGE}{function}= $args{function} or
              croak("$class-&gt;new() called without function arg");

    return $this;

}

1;

__END__

=head1 SEE ALSO

L&lt;autodie&gt;, L&lt;autodie::exception::system&gt;

=head1 LICENSE

Copyright (C)2008 Paul Fenwick

This is free software.  You may modify and/or redistribute this
code under the same terms as Perl 5.10 itself, or, at your option,
any later version of Perl 5.

=head1 AUTHOR

Paul Fenwick E&lt;lt&gt;pjf@perltraining.com.auE&lt;gt&gt;
</pre></body></html>