--- name: "autodie::exception" section: "3p" platform: "openbsd" package: "man" version: "8.0-current-20261101" release: "OpenBSD 8.0-current (2026-11-01)" platforms: ["openbsd"] url: "https://new.carta.tech/autodie::exception" --- # autodie::exception(3p) Exceptions from autodying functions. ## NAME autodie::exception - Exceptions from autodying functions. ## SYNOPSIS ``` eval { use autodie; open(my $fh, '<', 'some_file.txt'); ... }; if (my $E = $@) { say "Ooops! ",$E->caller," had problems: $@"; } ``` ## DESCRIPTION When an autodie 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: ``` if ($E = $@) { ... } ``` This is not required, but is recommended in case any code is called which may reset or alter `$@`. *args* ``` my $array_ref = $E->args; ``` Provides a reference to the arguments passed to the subroutine that died. *function* ``` my $sub = $E->function; ``` The subroutine (including package) that threw the exception. *file* ``` my $file = $E->file; ``` The file in which the error occurred (eg, `"myscript.pl"` or `"MyTest.pm"`). *package* ``` my $package = $E->package; ``` The package from which the exceptional subroutine was called. *caller* ``` my $caller = $E->caller; ``` The subroutine that *called* the exceptional code. *line* ``` my $line = $E->line; ``` The line in `"$E->file"` where the exceptional code was called. *context* ``` 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* ``` 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* ``` 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* ``` 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 that set (but do not throw) `$@` on error. *matches* ``` 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 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* ``` 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* ``` 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* ``` 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* ``` 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* ``` 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::exception::system ## 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 \