1autodie::exception(3) User Contributed Perl Documentationautodie::exception(3)
2
3
4

NAME

6       autodie::exception - Exceptions from autodying functions.
7

SYNOPSIS

9           eval {
10               use autodie;
11
12               open(my $fh, '<', 'some_file.txt');
13
14               ...
15           };
16
17           if (my $E = $@) {
18               say "Ooops!  ",$E->caller," had problems: $@";
19           }
20

DESCRIPTION

22       When an autodie enabled function fails, it generates an
23       "autodie::exception" object.  This can be interrogated to determine
24       further information about the error that occurred.
25
26       This document is broken into two sections; those methods that are most
27       useful to the end-developer, and those methods for anyone wishing to
28       subclass or get very familiar with "autodie::exception".
29
30   Common Methods
31       These methods are intended to be used in the everyday dealing of
32       exceptions.
33
34       The following assume that the error has been copied into a separate
35       scalar:
36
37           if ($E = $@) {
38               ...
39           }
40
41       This is not required, but is recommended in case any code is called
42       which may reset or alter $@.
43
44       args
45
46           my $array_ref = $E->args;
47
48       Provides a reference to the arguments passed to the subroutine that
49       died.
50
51       function
52
53           my $sub = $E->function;
54
55       The subroutine (including package) that threw the exception.
56
57       file
58
59           my $file = $E->file;
60
61       The file in which the error occurred (eg, "myscript.pl" or
62       "MyTest.pm").
63
64       package
65
66           my $package = $E->package;
67
68       The package from which the exceptional subroutine was called.
69
70       caller
71
72           my $caller = $E->caller;
73
74       The subroutine that called the exceptional code.
75
76       line
77
78           my $line = $E->line;
79
80       The line in "$E->file" where the exceptional code was called.
81
82       context
83
84           my $context = $E->context;
85
86       The context in which the subroutine was called by autodie; usually the
87       same as the context in which you called the autodying subroutine.  This
88       can be 'list', 'scalar', or undefined (unknown).  It will never be
89       'void', as "autodie" always captures the return value in one way or
90       another.
91
92       For some core functions that always return a scalar value regardless of
93       their context (eg, "chown"), this may be 'scalar', even if you used a
94       list context.
95
96       return
97
98           my $return_value = $E->return;
99
100       The value(s) returned by the failed subroutine.  When the subroutine
101       was called in a list context, this will always be a reference to an
102       array containing the results.  When the subroutine was called in a
103       scalar context, this will be the actual scalar returned.
104
105       errno
106
107           my $errno = $E->errno;
108
109       The value of $! at the time when the exception occurred.
110
111       NOTE: This method will leave the main "autodie::exception" class and
112       become part of a role in the future.  You should only call "errno" for
113       exceptions where $! would reasonably have been set on failure.
114
115       eval_error
116
117           my $old_eval_error = $E->eval_error;
118
119       The contents of $@ immediately after autodie triggered an exception.
120       This may be useful when dealing with modules such as Text::Balanced
121       that set (but do not throw) $@ on error.
122
123       matches
124
125           if ( $e->matches('open') ) { ... }
126
127           if ( $e ~~ 'open' ) { ... }
128
129       "matches" is used to determine whether a given exception matches a
130       particular role.  On Perl 5.10, using smart-match ("~~") with an
131       "autodie::exception" object will use "matches" underneath.
132
133       An exception is considered to match a string if:
134
135       ·   For a string not starting with a colon, the string exactly matches
136           the package and subroutine that threw the exception.  For example,
137           "MyModule::log".  If the string does not contain a package name,
138           "CORE::" is assumed.
139
140       ·   For a string that does start with a colon, if the subroutine
141           throwing the exception does that behaviour.  For example, the
142           "CORE::open" subroutine does ":file", ":io" and ":all".
143
144           See "CATEGORIES" in autodie for futher information.
145
146   Advanced methods
147       The following methods, while usable from anywhere, are primarily
148       intended for developers wishing to subclass "autodie::exception", write
149       code that registers custom error messages, or otherwise work closely
150       with the "autodie::exception" model.
151
152       register
153
154           autodie::exception->register( 'CORE::open' => \&mysub );
155
156       The "register" method allows for the registration of a message handler
157       for a given subroutine.  The full subroutine name including the package
158       should be used.
159
160       Registered message handlers will receive the "autodie::exception"
161       object as the first parameter.
162
163       add_file_and_line
164
165           say "Problem occurred",$@->add_file_and_line;
166
167       Returns the string " at %s line %d", where %s is replaced with the
168       filename, and %d is replaced with the line number.
169
170       Primarily intended for use by format handlers.
171
172       stringify
173
174           say "The error was: ",$@->stringify;
175
176       Formats the error as a human readable string.  Usually there's no
177       reason to call this directly, as it is used automatically if an
178       "autodie::exception" object is ever used as a string.
179
180       Child classes can override this method to change how they're
181       stringified.
182
183       format_default
184
185           my $error_string = $E->format_default;
186
187       This produces the default error string for the given exception, without
188       using any registered message handlers.  It is primarily intended to be
189       called from a message handler when they have been passed an exception
190       they don't want to format.
191
192       Child classes can override this method to change how default messages
193       are formatted.
194
195       new
196
197           my $error = autodie::exception->new(
198               args => \@_,
199               function => "CORE::open",
200               errno => $!,
201               context => 'scalar',
202               return => undef,
203           );
204
205       Creates a new "autodie::exception" object.  Normally called directly
206       from an autodying function.  The "function" argument is required, its
207       the function we were trying to call that generated the exception.  The
208       "args" parameter is optional.
209
210       The "errno" value is optional.  In versions of "autodie::exception"
211       1.99 and earlier the code would try to automatically use the current
212       value of $!, but this was unreliable and is no longer supported.
213
214       Atrributes such as package, file, and caller are determined
215       automatically, and cannot be specified.
216

SEE ALSO

218       autodie, autodie::exception::system
219

LICENSE

221       Copyright (C)2008 Paul Fenwick
222
223       This is free software.  You may modify and/or redistribute this code
224       under the same terms as Perl 5.10 itself, or, at your option, any later
225       version of Perl 5.
226

AUTHOR

228       Paul Fenwick <pjf@perltraining.com.au>
229
230
231
232perl v5.16.3                      2013-02-22             autodie::exception(3)