=encoding euc-jp =head1 NAME =begin original autodie::exception - Exceptions from autodying functions. =end original autodie::exception - autodie した関数の例外 =head1 SYNOPSIS eval { use autodie; open(my $fh, '<', 'some_file.txt'); ... }; if (my $E = $@) { say "Ooops! ",$E->caller," had problems: $@"; } =head1 DESCRIPTION =begin original When an L enabled function fails, it generates an C object. This can be interrogated to determine further information about the error that occurred. =end original When an L enabled function fails, it generates an C object. This can be interrogated to determine further information about the error that occurred. (TBT) =begin original 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. =end original 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. (TBT) =head2 Common Methods =begin original These methods are intended to be used in the everyday dealing of exceptions. =end original These methods are intended to be used in the everyday dealing of exceptions. (TBT) =begin original The following assume that the error has been copied into a separate scalar: =end original The following assume that the error has been copied into a separate scalar: (TBT) if ($E = $@) { ... } =begin original This is not required, but is recommended in case any code is called which may reset or alter C<$@>. =end original This is not required, but is recommended in case any code is called which may reset or alter C<$@>. (TBT) =head3 args my $array_ref = $E->args; =begin original Provides a reference to the arguments passed to the subroutine that died. =end original Provides a reference to the arguments passed to the subroutine that died. (TBT) =head3 function my $sub = $E->function; =begin original The subroutine (including package) that threw the exception. =end original The subroutine (including package) that threw the exception. (TBT) =head3 file my $file = $E->file; =begin original The file in which the error occurred (eg, C or C). =end original The file in which the error occurred (eg, C or C). (TBT) =head3 package my $package = $E->package; =begin original The package from which the exceptional subroutine was called. =end original The package from which the exceptional subroutine was called. (TBT) =head3 caller my $caller = $E->caller; =begin original The subroutine that I the exceptional code. =end original The subroutine that I the exceptional code. (TBT) =head3 line my $line = $E->line; =begin original The line in C<< $E->file >> where the exceptional code was called. =end original The line in C<< $E->file >> where the exceptional code was called. (TBT) =head3 context my $context = $E->context; =begin original The context in which the subroutine was called. This can be 'list', 'scalar', or undefined (unknown). It will never be 'void', as C always captures the return value in one way or another. =end original The context in which the subroutine was called. This can be 'list', 'scalar', or undefined (unknown). It will never be 'void', as C always captures the return value in one way or another. (TBT) =head3 return my $return_value = $E->return; =begin original 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. =end original 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. (TBT) =head3 errno my $errno = $E->errno; =begin original The value of C<$!> at the time when the exception occurred. =end original The value of C<$!> at the time when the exception occurred. (TBT) =begin original B: This method will leave the main C class and become part of a role in the future. You should only call C for exceptions where C<$!> would reasonably have been set on failure. =end original B: This method will leave the main C class and become part of a role in the future. You should only call C for exceptions where C<$!> would reasonably have been set on failure. (TBT) =head3 eval_error my $old_eval_error = $E->eval_error; =begin original The contents of C<$@> immediately after autodie triggered an exception. This may be useful when dealing with modules such as L that set (but do not throw) C<$@> on error. =end original The contents of C<$@> immediately after autodie triggered an exception. This may be useful when dealing with modules such as L that set (but do not throw) C<$@> on error. (TBT) =head3 matches if ( $e->matches('open') ) { ... } if ( $e ~~ 'open' ) { ... } =begin original C is used to determine whether a given exception matches a particular role. On Perl 5.10, using smart-match (C<~~>) with an C object will use C underneath. =end original C is used to determine whether a given exception matches a particular role. On Perl 5.10, using smart-match (C<~~>) with an C object will use C underneath. (TBT) =begin original An exception is considered to match a string if: =end original An exception is considered to match a string if: (TBT) =over 4 =item * =begin original For a string not starting with a colon, the string exactly matches the package and subroutine that threw the exception. For example, C. If the string does not contain a package name, C is assumed. =end original For a string not starting with a colon, the string exactly matches the package and subroutine that threw the exception. For example, C. If the string does not contain a package name, C is assumed. (TBT) =item * =begin original For a string that does start with a colon, if the subroutine throwing the exception I that behaviour. For example, the C subroutine does C<:file>, C<:io> and C<:all>. =end original For a string that does start with a colon, if the subroutine throwing the exception I that behaviour. For example, the C subroutine does C<:file>, C<:io> and C<:all>. (TBT) =begin original See L for futher information. =end original See L for futher information. (TBT) =back =head2 Advanced methods =begin original The following methods, while usable from anywhere, are primarily intended for developers wishing to subclass C, write code that registers custom error messages, or otherwise work closely with the C model. =end original The following methods, while usable from anywhere, are primarily intended for developers wishing to subclass C, write code that registers custom error messages, or otherwise work closely with the C model. (TBT) =head3 register autodie::exception->register( 'CORE::open' => \&mysub ); =begin original The C method allows for the registration of a message handler for a given subroutine. The full subroutine name including the package should be used. =end original The C method allows for the registration of a message handler for a given subroutine. The full subroutine name including the package should be used. (TBT) =begin original Registered message handlers will receive the C object as the first parameter. =end original Registered message handlers will receive the C object as the first parameter. (TBT) =head3 add_file_and_line say "Problem occurred",$@->add_file_and_line; =begin original Returns the string C< at %s line %d>, where C<%s> is replaced with the filename, and C<%d> is replaced with the line number. =end original Returns the string C< at %s line %d>, where C<%s> is replaced with the filename, and C<%d> is replaced with the line number. (TBT) =begin original Primarily intended for use by format handlers. =end original Primarily intended for use by format handlers. (TBT) =head3 stringify say "The error was: ",$@->stringify; =begin original 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 object is ever used as a string. =end original 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 object is ever used as a string. (TBT) =begin original Child classes can override this method to change how they're stringified. =end original Child classes can override this method to change how they're stringified. (TBT) =head3 format_default my $error_string = $E->format_default; =begin original This produces the default error string for the given exception, I. It is primarily intended to be called from a message handler when they have been passed an exception they don't want to format. =end original This produces the default error string for the given exception, I. It is primarily intended to be called from a message handler when they have been passed an exception they don't want to format. (TBT) =begin original Child classes can override this method to change how default messages are formatted. =end original Child classes can override this method to change how default messages are formatted. (TBT) =head3 new my $error = autodie::exception->new( args => \@_, function => "CORE::open", errno => $!, context => 'scalar', return => undef, ); =begin original Creates a new C object. Normally called directly from an autodying function. The C argument is required, its the function we were trying to call that generated the exception. The C parameter is optional. =end original Creates a new C object. Normally called directly from an autodying function. The C argument is required, its the function we were trying to call that generated the exception. The C parameter is optional. (TBT) =begin original The C value is optional. In versions of C 1.99 and earlier the code would try to automatically use the current value of C<$!>, but this was unreliable and is no longer supported. =end original The C value is optional. In versions of C 1.99 and earlier the code would try to automatically use the current value of C<$!>, but this was unreliable and is no longer supported. (TBT) =begin original Atrributes such as package, file, and caller are determined automatically, and cannot be specified. =end original Atrributes such as package, file, and caller are determined automatically, and cannot be specified. (TBT) =head1 SEE ALSO L, L =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 Epjf@perltraining.com.auE