<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/autodie/exception.md. Do not edit. -->

```{index} single: autodie::exception (pragma)
```

# autodie::exception

Exceptions from autodying functions.

## SYNOPSIS

```perl
eval {
    use autodie;

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

    ...
};

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

## DESCRIPTION

When an [autodie](../autodie.md) enabled function fails, it generates an
`autodie::exception` 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
`autodie::exception`.

### 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:

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

This is not required, but is recommended in case any code
is called which may reset or alter `$@`.

#### args

```perl
my $array_ref = $E->args;
```

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

#### function

```perl
my $sub = $E->function;
```

The subroutine (including package) that threw the exception.

#### file

```perl
my $file = $E->file;
```

The file in which the error occurred (eg, `myscript.pl` or
`MyTest.pm`).

#### package

```perl
my $package = $E->package;
```

The package from which the exceptional subroutine was called.

#### caller

```perl
my $caller = $E->caller;
```

The subroutine that _called_ the exceptional code.

#### line

```perl
my $line = $E->line;
```

The line in `$E->file` where the exceptional code was called.

#### context

```perl
my $context = $E->context;
```

The context in which the subroutine was called by autodie; usually
the same as the context in which you called the autodying subroutine.
This can be 'list', 'scalar', or undefined (unknown).  It will never
be 'void', as `autodie` always captures the return value in one way
or another.

For some core functions that always return a scalar value regardless
of their context (eg, `chown`), this may be 'scalar', even if you
used a list context.

#### return

```perl
my $return_value = $E->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.

#### errno

```perl
my $errno = $E->errno;
```

The value of `$!` at the time when the exception occurred.

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

#### eval\_error

```perl
my $old_eval_error = $E->eval_error;
```

The contents of `$@` immediately after autodie triggered an
exception.  This may be useful when dealing with modules such
as [Text::Balanced](../Text/Balanced.md) that set (but do not throw) `$@` on error.

#### matches

```perl
if ( $e->matches('open') ) { ... }

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

`matches` is used to determine whether a
given exception matches a particular role.

An exception is considered to match a string if:

- For a string not starting with a colon, the string exactly matches the
package and subroutine that threw the exception.  For example,
`MyModule::log`.  If the string does not contain a package name,
`CORE::` is assumed.
- For a string that does start with a colon, if the subroutine
throwing the exception _does_ that behaviour.  For example, the
`CORE::open` subroutine does `:file`, `:io` and `:all`.

    See ["CATEGORIES" in autodie](../autodie.md) for further information.

    On Perl 5.10 and above, using smart-match (`~~`) with an
    `autodie::exception` object will use `matches` underneath.  This module
    used to recommend using smart-match with the exception object on the left
    hand side, but in future Perls that is likely to stop working.
    The smart-match facility of this class should only be used with the
    exception object on the right hand side.  Having the exception object on
    the right is both future-proof and portable to older Perls, back to 5.10.
    Beware that this facility can only
    be relied upon when it is certain that the exception object actually is
    an `autodie::exception` object; it is no more capable than an explicit
    call to the `matches` method.

### Advanced methods

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

#### register

```perl
autodie::exception->register( 'CORE::open' => \&mysub );
```

The `register` 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 `autodie::exception`
object as the first parameter.

#### add\_file\_and\_line

```perl
say "Problem occurred",$@->add_file_and_line;
```

Returns the string ` at %s line %d`, where `%s` is replaced with
the filename, and `%d` is replaced with the line number.

Primarily intended for use by format handlers.

#### stringify

```perl
say "The error was: ",$@->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
`autodie::exception` object is ever used as a string.

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

#### format\_default

```perl
my $error_string = $E->format_default;
```

This produces the default error string for the given exception,
_without using any registered message handlers_.  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.

#### new

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

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

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

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

## SEE ALSO

[autodie](../autodie.md), [autodie::exception::system](exception/system.md)

## 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.

## AUTHOR

Paul Fenwick <pjf@perltraining.com.au>

## Modules

- [`autodie::exception::system`](exception/system.md) - Exceptions from autodying system().

```{toctree}
:hidden:
:maxdepth: 1

exception/system
```