autodie::exception(3pm)

1autodie::exception(3pm)Perl Programmers Reference Guideautodie::exception(3pm)
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.  This can be 'list',
87       'scalar', or undefined (unknown).  It will never be 'void', as
88       "autodie" always captures the return value in one way or another.
89
90       return
91
92           my $return_value = $E->return;
93
94       The value(s) returned by the failed subroutine.  When the subroutine
95       was called in a list context, this will always be a reference to an
96       array containing the results.  When the subroutine was called in a
97       scalar context, this will be the actual scalar returned.
98
99       errno
100
101           my $errno = $E->errno;
102
103       The value of $! at the time when the exception occurred.
104
105       NOTE: This method will leave the main "autodie::exception" class and
106       become part of a role in the future.  You should only call "errno" for
107       exceptions where $! would reasonably have been set on failure.
108
109       eval_error
110
111           my $old_eval_error = $E->eval_error;
112
113       The contents of $@ immediately after autodie triggered an exception.
114       This may be useful when dealing with modules such as Text::Balanced
115       that set (but do not throw) $@ on error.
116
117       matches
118
119           if ( $e->matches('open') ) { ... }
120
121           if ( $e ~~ 'open' ) { ... }
122
123       "matches" is used to determine whether a given exception matches a
124       particular role.  On Perl 5.10, using smart-match ("~~") with an
125       "autodie::exception" object will use "matches" underneath.
126
127       An exception is considered to match a string if:
128
129       ·   For a string not starting with a colon, the string exactly matches
130           the package and subroutine that threw the exception.  For example,
131           "MyModule::log".  If the string does not contain a package name,
132           "CORE::" is assumed.
133
134       ·   For a string that does start with a colon, if the subroutine
135           throwing the exception does that behaviour.  For example, the
136           "CORE::open" subroutine does ":file", ":io" and ":all".
137
138           See "CATEGORIES" in autodie for futher information.
139
140   Advanced methods
141       The following methods, while usable from anywhere, are primarily
142       intended for developers wishing to subclass "autodie::exception", write
143       code that registers custom error messages, or otherwise work closely
144       with the "autodie::exception" model.
145
146       register
147
148           autodie::exception->register( 'CORE::open' => \&mysub );
149
150       The "register" method allows for the registration of a message handler
151       for a given subroutine.  The full subroutine name including the package
152       should be used.
153
154       Registered message handlers will receive the "autodie::exception"
155       object as the first parameter.
156
157       add_file_and_line
158
159           say "Problem occurred",$@->add_file_and_line;
160
161       Returns the string " at %s line %d", where %s is replaced with the
162       filename, and %d is replaced with the line number.
163
164       Primarily intended for use by format handlers.
165
166       stringify
167
168           say "The error was: ",$@->stringify;
169
170       Formats the error as a human readable string.  Usually there's no
171       reason to call this directly, as it is used automatically if an
172       "autodie::exception" object is ever used as a string.
173
174       Child classes can override this method to change how they're
175       stringified.
176
177       format_default
178
179           my $error_string = $E->format_default;
180
181       This produces the default error string for the given exception, without
182       using any registered message handlers.  It is primarily intended to be
183       called from a message handler when they have been passed an exception
184       they don't want to format.
185
186       Child classes can override this method to change how default messages
187       are formatted.
188
189       new
190
191           my $error = autodie::exception->new(
192               args => \@_,
193               function => "CORE::open",
194               errno => $!,
195               context => 'scalar',
196               return => undef,
197           );
198
199       Creates a new "autodie::exception" object.  Normally called directly
200       from an autodying function.  The "function" argument is required, its
201       the function we were trying to call that generated the exception.  The
202       "args" parameter is optional.
203
204       The "errno" value is optional.  In versions of "autodie::exception"
205       1.99 and earlier the code would try to automatically use the current
206       value of $!, but this was unreliable and is no longer supported.
207
208       Atrributes such as package, file, and caller are determined
209       automatically, and cannot be specified.
210

LICENSE

215       Copyright (C)2008 Paul Fenwick
216
217       This is free software.  You may modify and/or redistribute this code
218       under the same terms as Perl 5.10 itself, or, at your option, any later
219       version of Perl 5.
220

AUTHOR

222       Paul Fenwick <pjf@perltraining.com.au>
223
224
225
226perl v5.10.1                      2009-07-25           autodie::exception(3pm)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

LICENSE

AUTHOR