1Exception::Class::TryCaUtscehr(3C)ontributed Perl DocumeEnxtcaetpitoinon::Class::TryCatch(3)
2
6 Exception::Class::TryCatch - Syntactic try/catch sugar for use with
7 Exception::Class
8
10 version 1.13
11
13 use Exception::Class::TryCatch;
14 # simple usage of catch()
16 eval { Exception::Class::Base->throw('error') };
18 catch my $err and warn $err->error;
19 # catching only certain types or else rethrowing
21 eval { Exception::Class::Base::SubClass->throw('error') };
23 catch( my $err, ['Exception::Class::Base', 'Other::Exception'] )
24 and warn $err->error;
25 # catching and handling different types of errors
27 eval { Exception::Class::Base->throw('error') };
29 if ( catch my $err ) {
30 $err->isa('this') and do { handle_this($err) };
31 $err->isa('that') and do { handle_that($err) };
32 }
33 # use "try eval" to push exceptions onto a stack to catch later
35 try eval {
37 Exception::Class::Base->throw('error')
38 };
39 do {
40 # cleanup that might use "try/catch" again
41 };
42 catch my $err; # catches a matching "try"
43
45 Exception::Class::TryCatch provides syntactic sugar for use with
46 Exception::Class using the familiar keywords "try" and "catch". Its
47 primary objective is to allow users to avoid dealing directly with $@
48 by ensuring that any exceptions caught in an "eval" are captured as
49 Exception::Class objects, whether they were thrown objects to begin
50 with or whether the error resulted from "die". This means that users
51 may immediately use "isa" and various Exception::Class methods to
52 process the exception.
53 In addition, this module provides for a method to push errors onto a
55 hidden error stack immediately after an "eval" so that cleanup code or
56 other error handling may also call "eval" without the original error in
57 $@ being lost.
58 Inspiration for this module is due in part to Dave Rolsky's article
60 "Exception Handling in Perl With Exception::Class" in The Perl Journal
61 (Rolsky 2004).
62 The "try/catch" syntax used in this module does not use code reference
64 prototypes the way the Error.pm module does, but simply provides some
65 helpful functionality when used in combination with "eval". As a
66 result, it avoids the complexity and dangers involving nested closures
67 and memory leaks inherent in Error.pm (Perrin 2003).
68 Rolsky (2004) notes that these memory leaks may not occur in recent
70 versions of Perl, but the approach used in Exception::Class::TryCatch
71 should be safe for all versions of Perl as it leaves all code execution
72 to the "eval" in the current scope, avoiding closures altogether.
73
75 "catch"
76 # zero argument form
77 my $err = catch;
78 # one argument forms
80 catch my $err;
81 my $err = catch( [ 'Exception::Type', 'Exception::Other::Type' ] );
82 # two argument form
84 catch my $err, [ 'Exception::Type', 'Exception::Other::Type' ];
85 Returns an "Exception::Class::Base" object (or an object which is a
87 subclass of it) if an exception has been caught by "eval". If no
88 exception was thrown, it returns "undef" in scalar context and an empty
89 list in list context. The exception is either popped from a hidden
90 error stack (see "try") or, if the stack is empty, taken from the
91 current value of $@.
92 If the exception is not an "Exception::Class::Base" object (or subclass
94 object), an "Exception::Class::Base" object will be created using the
95 string contents of the exception. This means that calls to "die" will
96 be wrapped and may be treated as exception objects. Other objects
97 caught will be stringified and wrapped likewise. Such wrapping will
98 likely result in confusing stack traces and the like, so any methods
99 other than "error" used on "Exception::Class::Base" objects caught
100 should be used with caution.
101 "catch" is prototyped to take up to two optional scalar arguments. The
103 single argument form has two variations.
104 • If the argument is a reference to an array, any exception caught
106 that is not of the same type (or a subtype) of one of the classes
107 listed in the array will be rethrown.
108 • If the argument is not a reference to an array, "catch" will set
110 the argument to the same value that is returned. This allows for
111 the "catch my $err" idiom without parentheses.
112 In the two-argument form, the first argument is set to the same value
114 as is returned. The second argument must be an array reference and is
115 handled the same as as for the single argument version with an array
116 reference, as given above.
117 "caught" (DEPRECATED)
119 "caught" is a synonym for "catch" for syntactic convenience.
120 NOTE: Exception::Class version 1.21 added a "caught" method of its own.
122 It provides somewhat similar functionality to this subroutine, but with
123 very different semantics. As this class is intended to work closely
124 with Exception::Class, the existence of a subroutine and a method with
125 the same name is liable to cause confusion and this method is
126 deprecated and may be removed in future releases of
127 Exception::Class::TryCatch.
128 This method is no longer exported by default.
130 "try"
132 # void context
133 try eval {
134 # dangerous code
135 };
136 do {
137 # cleanup code can use try/catch
138 };
139 catch my $err;
140 # scalar context
142 $rv = try eval { return $scalar };
143 # list context
145 @rv = try [ eval { return @array } ];
146 Pushes the current error ($@) onto a hidden error stack for later use
148 by "catch". "try" uses a prototype that expects a single scalar so
149 that it can be used with eval without parentheses. As "eval { BLOCK }"
150 is an argument to try, it will be evaluated just prior to "try",
151 ensuring that "try" captures the correct error status. "try" does not
152 itself handle any errors -- it merely records the results of "eval".
153 "try { BLOCK }" will be interpreted as passing a hash reference and
154 will (probably) not compile. (And if it does, it will result in very
155 unexpected behavior.)
156 Since "try" requires a single argument, "eval" will normally be called
158 in scalar context. To use "eval" in list context with "try", put the
159 call to "eval" in an anonymous array:
160 @rv = try [ eval {return @array} ];
162 When "try" is called in list context, if the argument to "try" is an
164 array reference, "try" will dereference the array and return the
165 resulting list.
166 In scalar context, "try" passes through the scalar value returned by
168 "eval" without modifications -- even if that is an array reference.
169 $rv = try eval { return $scalar };
171 $rv = try eval { return [ qw( anonymous array ) ] };
172 Of course, if the eval throws an exception, "eval" and thus "try" will
174 return undef.
175 "try" must always be properly bracketed with a matching "catch" or
177 unexpected behavior may result when "catch" pops the error off of the
178 stack. "try" executes right after its "eval", so inconsistent usage of
179 "try" like the following will work as expected:
180 try eval {
182 eval { die "inner" };
183 catch my $inner_err
184 die "outer" if $inner_err;
185 };
186 catch my $outer_err;
187 # handle $outer_err;
188 However, the following code is a problem:
190 # BAD EXAMPLE
192 try eval {
193 try eval { die "inner" };
194 die $@ if $@;
195 };
196 catch my $outer_err;
197 # handle $outer_err;
198 This code will appear to run correctly, but "catch" gets the exception
200 from the inner "try", not the outer one, and there will still be an
201 exception on the error stack which will be caught by the next "catch"
202 in the program, causing unexpected (and likely hard to track) behavior.
203 In short, if you use "try", you must have a matching "catch". The
205 problem code above should be rewritten as:
206 try eval {
208 try eval { die "inner" };
209 catch my $inner_err;
210 $inner_err->rethrow if $inner_err;
211 };
212 catch my $outer_err;
213 # handle $outer_err;
214
216 1. perrin. (2003), "Re: Re2: Learning how to use the Error module by
217 example", (perlmonks.org), Available:
218 http://www.perlmonks.org/index.pl?node_id=278900 (Accessed
219 September 8, 2004).
220 2. Rolsky, D. (2004), "Exception Handling in Perl with
222 Exception::Class", The Perl Journal, vol. 8, no. 7, pp. 9-13
223
225 • Exception::Class
226 • Error -- but see (Perrin 2003) before using
228
230 Bugs / Feature Requests
231 Please report any bugs or feature requests through the issue tracker at
232 <https://github.com/dagolden/Exception-Class-TryCatch/issues>. You
233 will be notified automatically of any progress on your issue.
234 Source Code
236 This is open source software. The code repository is available for
237 public review and contribution under the terms of the license.
238 <https://github.com/dagolden/Exception-Class-TryCatch>
240 git clone https://github.com/dagolden/Exception-Class-TryCatch.git
242
244 David Golden <dagolden@cpan.org>
245
247 This software is Copyright (c) 2014 by David Golden.
248 This is free software, licensed under:
250 The Apache License, Version 2.0, January 2004
252perl v5.34.0 2022-01-21 Exception::Class::TryCatch(3)