Filename | /home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Exception/Class/Base.pm |
Statements | Executed 58 statements in 7.01ms |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
1 | 1 | 1 | 5.98ms | 20.0ms | BEGIN@10 | Exception::Class::Base::
1 | 1 | 1 | 1.10ms | 1.37ms | BEGIN@9 | Exception::Class::Base::
1 | 1 | 1 | 257µs | 257µs | BEGIN@37 | Exception::Class::Base::
1 | 1 | 1 | 151µs | 400µs | BEGIN@15 | Exception::Class::Base::
1 | 1 | 1 | 50µs | 74µs | BEGIN@7 | Exception::Class::Base::
1 | 1 | 1 | 38µs | 180µs | BEGIN@11 | Exception::Class::Base::
1 | 1 | 1 | 37µs | 88µs | BEGIN@43 | Exception::Class::Base::
1 | 1 | 1 | 35µs | 311µs | BEGIN@13 | Exception::Class::Base::
1 | 1 | 1 | 35µs | 233µs | BEGIN@34 | Exception::Class::Base::
1 | 1 | 1 | 32µs | 32µs | BEGIN@2 | Exception::Class::Base::
1 | 1 | 1 | 27µs | 38µs | BEGIN@6 | Exception::Class::Base::
1 | 1 | 1 | 26µs | 63µs | BEGIN@63 | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | Classes | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | Fields | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | __ANON__[:34] | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | __ANON__[:41] | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | __ANON__[:62] | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | _initialize | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | as_string | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | caught | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | description | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | full_message | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | new | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | rethrow | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | show_trace | Exception::Class::Base::
0 | 0 | 0 | 0s | 0s | throw | Exception::Class::Base::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | package Exception::Class::Base; | ||||
2 | # spent 32µs within Exception::Class::Base::BEGIN@2 which was called:
# once (32µs+0s) by Exception::Class::BEGIN@10 at line 4 | ||||
3 | 1 | 28µs | $Exception::Class::Base::VERSION = '1.32'; | ||
4 | 1 | 88µs | 1 | 32µs | } # spent 32µs making 1 call to Exception::Class::Base::BEGIN@2 |
5 | |||||
6 | 2 | 88µs | 2 | 49µs | # spent 38µs (27+11) within Exception::Class::Base::BEGIN@6 which was called:
# once (27µs+11µs) by Exception::Class::BEGIN@10 at line 6 # spent 38µs making 1 call to Exception::Class::Base::BEGIN@6
# spent 11µs making 1 call to strict::import |
7 | 2 | 95µs | 2 | 98µs | # spent 74µs (50+24) within Exception::Class::Base::BEGIN@7 which was called:
# once (50µs+24µs) by Exception::Class::BEGIN@10 at line 7 # spent 74µs making 1 call to Exception::Class::Base::BEGIN@7
# spent 24µs making 1 call to warnings::import |
8 | |||||
9 | 2 | 409µs | 1 | 1.37ms | # spent 1.37ms (1.10+274µs) within Exception::Class::Base::BEGIN@9 which was called:
# once (1.10ms+274µs) by Exception::Class::BEGIN@10 at line 9 # spent 1.37ms making 1 call to Exception::Class::Base::BEGIN@9 |
10 | 3 | 545µs | 2 | 20.1ms | # spent 20.0ms (5.98+14.0) within Exception::Class::Base::BEGIN@10 which was called:
# once (5.98ms+14.0ms) by Exception::Class::BEGIN@10 at line 10 # spent 20.0ms making 1 call to Exception::Class::Base::BEGIN@10
# spent 76µs making 1 call to UNIVERSAL::VERSION |
11 | 2 | 112µs | 2 | 322µs | # spent 180µs (38+142) within Exception::Class::Base::BEGIN@11 which was called:
# once (38µs+142µs) by Exception::Class::BEGIN@10 at line 11 # spent 180µs making 1 call to Exception::Class::Base::BEGIN@11
# spent 142µs making 1 call to Exporter::import |
12 | |||||
13 | 2 | 362µs | 2 | 588µs | # spent 311µs (35+277) within Exception::Class::Base::BEGIN@13 which was called:
# once (35µs+277µs) by Exception::Class::BEGIN@10 at line 13 # spent 311µs making 1 call to Exception::Class::Base::BEGIN@13
# spent 277µs making 1 call to base::import |
14 | |||||
15 | # spent 400µs (151+250) within Exception::Class::Base::BEGIN@15 which was called:
# once (151µs+250µs) by Exception::Class::BEGIN@10 at line 30 | ||||
16 | 1 | 15µs | 1 | 52µs | __PACKAGE__->mk_classdata('Trace'); # spent 52µs making 1 call to Class::Data::Inheritable::mk_classdata |
17 | 1 | 6µs | 1 | 37µs | __PACKAGE__->mk_classdata('NoRefs'); # spent 37µs making 1 call to Class::Data::Inheritable::mk_classdata |
18 | 1 | 7µs | 1 | 15µs | __PACKAGE__->NoRefs(1); # spent 15µs making 1 call to Class::Data::Inheritable::__ANON__[Class/Data/Inheritable.pm:23] |
19 | |||||
20 | 1 | 5µs | 1 | 40µs | __PACKAGE__->mk_classdata('NoContextInfo'); # spent 40µs making 1 call to Class::Data::Inheritable::mk_classdata |
21 | 1 | 7µs | 1 | 11µs | __PACKAGE__->NoContextInfo(0); # spent 11µs making 1 call to Class::Data::Inheritable::__ANON__[Class/Data/Inheritable.pm:23] |
22 | |||||
23 | 1 | 5µs | 1 | 35µs | __PACKAGE__->mk_classdata('RespectOverload'); # spent 35µs making 1 call to Class::Data::Inheritable::mk_classdata |
24 | 1 | 7µs | 1 | 10µs | __PACKAGE__->RespectOverload(0); # spent 10µs making 1 call to Class::Data::Inheritable::__ANON__[Class/Data/Inheritable.pm:23] |
25 | |||||
26 | 1 | 5µs | 1 | 38µs | __PACKAGE__->mk_classdata('MaxArgLength'); # spent 38µs making 1 call to Class::Data::Inheritable::mk_classdata |
27 | 1 | 19µs | 1 | 11µs | __PACKAGE__->MaxArgLength(0); # spent 11µs making 1 call to Class::Data::Inheritable::__ANON__[Class/Data/Inheritable.pm:23] |
28 | |||||
29 | sub Fields { () } | ||||
30 | 1 | 196µs | 1 | 400µs | } # spent 400µs making 1 call to Exception::Class::Base::BEGIN@15 |
31 | |||||
32 | use overload | ||||
33 | # an exception is always true | ||||
34 | 2 | 382µs | 2 | 432µs | # spent 233µs (35+199) within Exception::Class::Base::BEGIN@34 which was called:
# once (35µs+199µs) by Exception::Class::BEGIN@10 at line 34 # spent 233µs making 1 call to Exception::Class::Base::BEGIN@34
# spent 199µs making 1 call to overload::import |
35 | |||||
36 | # Create accessor routines | ||||
37 | # spent 257µs within Exception::Class::Base::BEGIN@37 which was called:
# once (257µs+0s) by Exception::Class::BEGIN@10 at line 66 | ||||
38 | 1 | 7µs | my @fields = qw( message pid uid euid gid egid time trace ); | ||
39 | |||||
40 | 1 | 3µs | foreach my $f (@fields) { | ||
41 | 8 | 72µs | my $sub = sub { my $s = shift; return $s->{$f}; }; | ||
42 | |||||
43 | 2 | 566µs | 2 | 140µs | # spent 88µs (37+52) within Exception::Class::Base::BEGIN@43 which was called:
# once (37µs+52µs) by Exception::Class::BEGIN@10 at line 43 # spent 88µs making 1 call to Exception::Class::Base::BEGIN@43
# spent 52µs making 1 call to strict::unimport |
44 | 8 | 77µs | *{$f} = $sub; | ||
45 | } | ||||
46 | 1 | 3µs | *error = \&message; | ||
47 | |||||
48 | 1 | 8µs | my %trace_fields = ( | ||
49 | package => 'package', | ||||
50 | file => 'filename', | ||||
51 | line => 'line', | ||||
52 | ); | ||||
53 | |||||
54 | 1 | 41µs | while ( my ( $f, $m ) = each %trace_fields ) { | ||
55 | my $sub = sub { | ||||
56 | my $s = shift; | ||||
57 | return $s->{$f} if exists $s->{$f}; | ||||
58 | |||||
59 | my $frame = $s->trace->frame(0); | ||||
60 | |||||
61 | return $s->{$f} = $frame ? $frame->$m() : undef; | ||||
62 | 3 | 23µs | }; | ||
63 | 2 | 130µs | 2 | 99µs | # spent 63µs (26+37) within Exception::Class::Base::BEGIN@63 which was called:
# once (26µs+37µs) by Exception::Class::BEGIN@10 at line 63 # spent 63µs making 1 call to Exception::Class::Base::BEGIN@63
# spent 37µs making 1 call to strict::unimport |
64 | 3 | 24µs | *{$f} = $sub; | ||
65 | } | ||||
66 | 1 | 3.66ms | 1 | 257µs | } # spent 257µs making 1 call to Exception::Class::Base::BEGIN@37 |
67 | |||||
68 | 1; | ||||
69 | |||||
70 | sub Classes { Exception::Class::Classes() } | ||||
71 | |||||
72 | sub throw { | ||||
73 | my $proto = shift; | ||||
74 | |||||
75 | $proto->rethrow if ref $proto; | ||||
76 | |||||
77 | die $proto->new(@_); | ||||
78 | } | ||||
79 | |||||
80 | sub rethrow { | ||||
81 | my $self = shift; | ||||
82 | |||||
83 | die $self; | ||||
84 | } | ||||
85 | |||||
86 | sub new { | ||||
87 | my $proto = shift; | ||||
88 | my $class = ref $proto || $proto; | ||||
89 | |||||
90 | my $self = bless {}, $class; | ||||
91 | |||||
92 | $self->_initialize(@_); | ||||
93 | |||||
94 | return $self; | ||||
95 | } | ||||
96 | |||||
97 | sub _initialize { | ||||
98 | my $self = shift; | ||||
99 | my %p = @_ == 1 ? ( error => $_[0] ) : @_; | ||||
100 | |||||
101 | $self->{message} = $p{message} || $p{error} || ''; | ||||
102 | |||||
103 | $self->{show_trace} = $p{show_trace} if exists $p{show_trace}; | ||||
104 | |||||
105 | if ( $self->NoContextInfo() ) { | ||||
106 | $self->{show_trace} = 0; | ||||
107 | $self->{package} = $self->{file} = $self->{line} = undef; | ||||
108 | } | ||||
109 | else { | ||||
110 | # CORE::time is important to fix an error with some versions of | ||||
111 | # Perl | ||||
112 | $self->{time} = CORE::time(); | ||||
113 | $self->{pid} = $$; | ||||
114 | $self->{uid} = $<; | ||||
115 | $self->{euid} = $>; | ||||
116 | $self->{gid} = $(; | ||||
117 | $self->{egid} = $); | ||||
118 | |||||
119 | my @ignore_class = (__PACKAGE__); | ||||
120 | my @ignore_package = 'Exception::Class'; | ||||
121 | |||||
122 | if ( my $i = delete $p{ignore_class} ) { | ||||
123 | push @ignore_class, ( ref($i) eq 'ARRAY' ? @$i : $i ); | ||||
124 | } | ||||
125 | |||||
126 | if ( my $i = delete $p{ignore_package} ) { | ||||
127 | push @ignore_package, ( ref($i) eq 'ARRAY' ? @$i : $i ); | ||||
128 | } | ||||
129 | |||||
130 | $self->{trace} = Devel::StackTrace->new( | ||||
131 | ignore_class => \@ignore_class, | ||||
132 | ignore_package => \@ignore_package, | ||||
133 | no_refs => $self->NoRefs, | ||||
134 | respect_overload => $self->RespectOverload, | ||||
135 | max_arg_length => $self->MaxArgLength, | ||||
136 | ); | ||||
137 | } | ||||
138 | |||||
139 | my %fields = map { $_ => 1 } $self->Fields; | ||||
140 | while ( my ( $key, $value ) = each %p ) { | ||||
141 | next if $key =~ /^(?:error|message|show_trace)$/; | ||||
142 | |||||
143 | if ( $fields{$key} ) { | ||||
144 | $self->{$key} = $value; | ||||
145 | } | ||||
146 | else { | ||||
147 | Exception::Class::Base->throw( | ||||
148 | error => "unknown field $key passed to constructor for class " | ||||
149 | . ref $self ); | ||||
150 | } | ||||
151 | } | ||||
152 | } | ||||
153 | |||||
154 | sub description { | ||||
155 | return 'Generic exception'; | ||||
156 | } | ||||
157 | |||||
158 | sub show_trace { | ||||
159 | my $self = shift; | ||||
160 | |||||
161 | return 0 unless $self->{trace}; | ||||
162 | |||||
163 | if (@_) { | ||||
164 | $self->{show_trace} = shift; | ||||
165 | } | ||||
166 | |||||
167 | return exists $self->{show_trace} ? $self->{show_trace} : $self->Trace; | ||||
168 | } | ||||
169 | |||||
170 | sub as_string { | ||||
171 | my $self = shift; | ||||
172 | |||||
173 | my $str = $self->full_message; | ||||
174 | $str .= "\n\n" . $self->trace->as_string | ||||
175 | if $self->show_trace; | ||||
176 | |||||
177 | return $str; | ||||
178 | } | ||||
179 | |||||
180 | sub full_message { $_[0]->{message} } | ||||
181 | |||||
182 | # | ||||
183 | # The %seen bit protects against circular inheritance. | ||||
184 | # | ||||
185 | 1 | 5µs | eval <<'EOF' if $] == 5.006; | ||
186 | sub isa { | ||||
187 | my ( $inheritor, $base ) = @_; | ||||
188 | $inheritor = ref($inheritor) if ref($inheritor); | ||||
189 | |||||
190 | my %seen; | ||||
191 | |||||
192 | no strict 'refs'; | ||||
193 | my @parents = ( $inheritor, @{"$inheritor\::ISA"} ); | ||||
194 | while ( my $class = shift @parents ) { | ||||
195 | return 1 if $class eq $base; | ||||
196 | |||||
197 | push @parents, grep { !$seen{$_}++ } @{"$class\::ISA"}; | ||||
198 | } | ||||
199 | return 0; | ||||
200 | } | ||||
201 | EOF | ||||
202 | |||||
203 | sub caught { | ||||
204 | my $class = shift; | ||||
205 | |||||
206 | my $e = $@; | ||||
207 | |||||
208 | return unless defined $e && blessed($e) && $e->isa($class); | ||||
209 | return $e; | ||||
210 | } | ||||
211 | |||||
212 | 1 | 14µs | 1; | ||
213 | |||||
214 | # ABSTRACT: A base class for exception objects | ||||
215 | |||||
- - | |||||
218 | =pod | ||||
219 | |||||
220 | =head1 NAME | ||||
221 | |||||
222 | Exception::Class::Base - A base class for exception objects | ||||
223 | |||||
224 | =head1 VERSION | ||||
225 | |||||
226 | version 1.32 | ||||
227 | |||||
228 | =head1 SYNOPSIS | ||||
229 | |||||
230 | use Exception::Class 'MyException'; | ||||
231 | |||||
232 | eval { MyException->throw( error => 'I feel funny.' ) }; | ||||
233 | |||||
234 | print $@->error(); | ||||
235 | |||||
236 | =head1 DESCRIPTION | ||||
237 | |||||
238 | This class is the base class for all exceptions created by | ||||
239 | L<Exception::Class>. It provides a number of methods for getting | ||||
240 | information about the exception. | ||||
241 | |||||
242 | =head1 METHODS | ||||
243 | |||||
244 | =head2 MyException->Trace($boolean) | ||||
245 | |||||
246 | Each C<Exception::Class::Base> subclass can be set individually to | ||||
247 | include a stacktrace when the C<as_string> method is called. The | ||||
248 | default is to not include a stacktrace. Calling this method with a | ||||
249 | value changes this behavior. It always returns the current value | ||||
250 | (after any change is applied). | ||||
251 | |||||
252 | This value is inherited by any subclasses. However, if this value is | ||||
253 | set for a subclass, it will thereafter be independent of the value in | ||||
254 | C<Exception::Class::Base>. | ||||
255 | |||||
256 | Do not call this on the C<Exception::Class::Base> class directly or | ||||
257 | you'll change it for all exception classes that use | ||||
258 | L<Exception::Class>, including ones created in modules you don't | ||||
259 | control. | ||||
260 | |||||
261 | This is a class method, not an object method. | ||||
262 | |||||
263 | =head2 MyException->NoRefs($boolean) | ||||
264 | |||||
265 | When a C<Devel::StackTrace> object is created, it walks through the | ||||
266 | stack and stores the arguments which were passed to each subroutine on | ||||
267 | the stack. If any of these arguments are references, then that means | ||||
268 | that the C<Devel::StackTrace> ends up increasing the refcount of these | ||||
269 | references, delaying their destruction. | ||||
270 | |||||
271 | Since C<Exception::Class::Base> uses C<Devel::StackTrace> internally, | ||||
272 | this method provides a way to tell C<Devel::StackTrace> not to store | ||||
273 | these references. Instead, C<Devel::StackTrace> replaces references | ||||
274 | with their stringified representation. | ||||
275 | |||||
276 | This method defaults to true. As with C<Trace()>, it is inherited by | ||||
277 | subclasses but setting it in a subclass makes it independent | ||||
278 | thereafter. | ||||
279 | |||||
280 | Do not call this on the C<Exception::Class::Base> class directly or | ||||
281 | you'll change it for all exception classes that use | ||||
282 | L<Exception::Class>, including ones created in modules you don't | ||||
283 | control. | ||||
284 | |||||
285 | =head2 MyException->RespectOverload($boolean) | ||||
286 | |||||
287 | When a C<Devel::StackTrace> object stringifies, by default it ignores | ||||
288 | stringification overloading on any objects being dealt with. | ||||
289 | |||||
290 | Since C<Exception::Class::Base> uses C<Devel::StackTrace> internally, | ||||
291 | this method provides a way to tell C<Devel::StackTrace> to respect | ||||
292 | overloading. | ||||
293 | |||||
294 | This method defaults to false. As with C<Trace()>, it is inherited by | ||||
295 | subclasses but setting it in a subclass makes it independent | ||||
296 | thereafter. | ||||
297 | |||||
298 | Do not call this on the C<Exception::Class::Base> class directly or | ||||
299 | you'll change it for all exception classes that use | ||||
300 | L<Exception::Class>, including ones created in modules you don't | ||||
301 | control. | ||||
302 | |||||
303 | =head2 MyException->MaxArgLength($boolean) | ||||
304 | |||||
305 | When a C<Devel::StackTrace> object stringifies, by default it displays | ||||
306 | the full argument for each function. This parameter can be used to | ||||
307 | limit the maximum length of each argument. | ||||
308 | |||||
309 | Since C<Exception::Class::Base> uses C<Devel::StackTrace> internally, | ||||
310 | this method provides a way to tell C<Devel::StackTrace> to limit the | ||||
311 | length of arguments. | ||||
312 | |||||
313 | This method defaults to 0. As with C<Trace()>, it is inherited by | ||||
314 | subclasses but setting it in a subclass makes it independent | ||||
315 | thereafter. | ||||
316 | |||||
317 | Do not call this on the C<Exception::Class::Base> class directly or | ||||
318 | you'll change it for all exception classes that use | ||||
319 | L<Exception::Class>, including ones created in modules you don't | ||||
320 | control. | ||||
321 | |||||
322 | =head2 MyException->Fields | ||||
323 | |||||
324 | This method returns the extra fields defined for the given class, as | ||||
325 | an array. | ||||
326 | |||||
327 | Do not call this on the C<Exception::Class::Base> class directly or | ||||
328 | you'll change it for all exception classes that use | ||||
329 | L<Exception::Class>, including ones created in modules you don't | ||||
330 | control. | ||||
331 | |||||
332 | =head2 MyException->throw( $message ) | ||||
333 | |||||
334 | =head2 MyException->throw( message => $message ) | ||||
335 | |||||
336 | =head2 MyException->throw( error => $error ) | ||||
337 | |||||
338 | This method creates a new object with the given error message. If no | ||||
339 | error message is given, this will be an empty string. It then dies | ||||
340 | with this object as its argument. | ||||
341 | |||||
342 | This method also takes a C<show_trace> parameter which indicates | ||||
343 | whether or not the particular exception object being created should | ||||
344 | show a stacktrace when its C<as_string()> method is called. This | ||||
345 | overrides the value of C<Trace()> for this class if it is given. | ||||
346 | |||||
347 | The frames included in the trace can be controlled by the C<ignore_class> | ||||
348 | and C<ignore_package> parameters. These are passed directly to | ||||
349 | Devel::Stacktrace's constructor. See C<Devel::Stacktrace> for more details. | ||||
350 | |||||
351 | If only a single value is given to the constructor it is assumed to be | ||||
352 | the message parameter. | ||||
353 | |||||
354 | Additional keys corresponding to the fields defined for the particular | ||||
355 | exception subclass will also be accepted. | ||||
356 | |||||
357 | =head2 MyException->new(...) | ||||
358 | |||||
359 | This method takes the same parameters as C<throw()>, but instead of | ||||
360 | dying simply returns a new exception object. | ||||
361 | |||||
362 | This method is always called when constructing a new exception object | ||||
363 | via the C<throw()> method. | ||||
364 | |||||
365 | =head2 MyException->description() | ||||
366 | |||||
367 | Returns the description for the given C<Exception::Class::Base> | ||||
368 | subclass. The C<Exception::Class::Base> class's description is | ||||
369 | "Generic exception" (this may change in the future). This is also an | ||||
370 | object method. | ||||
371 | |||||
372 | =head2 $exception->rethrow() | ||||
373 | |||||
374 | Simply dies with the object as its sole argument. It's just syntactic | ||||
375 | sugar. This does not change any of the object's attribute values. | ||||
376 | However, it will cause C<caller()> to report the die as coming from | ||||
377 | within the C<Exception::Class::Base> class rather than where rethrow | ||||
378 | was called. | ||||
379 | |||||
380 | Of course, you always have access to the original stacktrace for the | ||||
381 | exception object. | ||||
382 | |||||
383 | =head2 $exception->message() | ||||
384 | |||||
385 | =head2 $exception->error() | ||||
386 | |||||
387 | Returns the error/message associated with the exception. | ||||
388 | |||||
389 | =head2 $exception->pid() | ||||
390 | |||||
391 | Returns the pid at the time the exception was thrown. | ||||
392 | |||||
393 | =head2 $exception->uid() | ||||
394 | |||||
395 | Returns the real user id at the time the exception was thrown. | ||||
396 | |||||
397 | =head2 $exception->gid() | ||||
398 | |||||
399 | Returns the real group id at the time the exception was thrown. | ||||
400 | |||||
401 | =head2 $exception->euid() | ||||
402 | |||||
403 | Returns the effective user id at the time the exception was thrown. | ||||
404 | |||||
405 | =head2 $exception->egid() | ||||
406 | |||||
407 | Returns the effective group id at the time the exception was thrown. | ||||
408 | |||||
409 | =head2 $exception->time() | ||||
410 | |||||
411 | Returns the time in seconds since the epoch at the time the exception | ||||
412 | was thrown. | ||||
413 | |||||
414 | =head2 $exception->package() | ||||
415 | |||||
416 | Returns the package from which the exception was thrown. | ||||
417 | |||||
418 | =head2 $exception->file() | ||||
419 | |||||
420 | Returns the file within which the exception was thrown. | ||||
421 | |||||
422 | =head2 $exception->line() | ||||
423 | |||||
424 | Returns the line where the exception was thrown. | ||||
425 | |||||
426 | =head2 $exception->trace() | ||||
427 | |||||
428 | Returns the trace object associated with the object. | ||||
429 | |||||
430 | =head2 $exception->show_trace($boolean) | ||||
431 | |||||
432 | This method can be used to set whether or not a stack trace is | ||||
433 | included when the as_string method is called or the object is | ||||
434 | stringified. | ||||
435 | |||||
436 | =head2 $exception->as_string() | ||||
437 | |||||
438 | Returns a string form of the error message (something like what you'd | ||||
439 | expect from die). If the class or object is set to show traces then | ||||
440 | then the full trace is also included. The result looks like | ||||
441 | C<Carp::confess()>. | ||||
442 | |||||
443 | =head2 $exception->full_message() | ||||
444 | |||||
445 | Called by the C<as_string()> method to get the message. By default, | ||||
446 | this is the same as calling the C<message()> method, but may be | ||||
447 | overridden by a subclass. See below for details. | ||||
448 | |||||
449 | =head1 LIGHTWEIGHT EXCEPTIONS | ||||
450 | |||||
451 | A lightweight exception is one which records no information about its context | ||||
452 | when it is created. This can be achieved by setting C<< | ||||
453 | $class->NoContextInfo() >> to a true value. | ||||
454 | |||||
455 | You can make this the default for a class of exceptions by setting it after | ||||
456 | creating the class: | ||||
457 | |||||
458 | use Exception::Class ( | ||||
459 | 'LightWeight', | ||||
460 | 'HeavyWeight', | ||||
461 | ); | ||||
462 | |||||
463 | LightWeight->NoContextInfo(1); | ||||
464 | |||||
465 | A lightweight exception does have a stack trace object, nor does it record the | ||||
466 | time, pid, uid, euid, gid, or egid. It only has a message. | ||||
467 | |||||
468 | =head1 OVERLOADING | ||||
469 | |||||
470 | C<Exception::Class::Base> objects are overloaded so that | ||||
471 | stringification produces a normal error message. This just calls the | ||||
472 | C<< $exception->as_string() >> method described above. This means | ||||
473 | that you can just C<print $@> after an C<eval> and not worry about | ||||
474 | whether or not its an actual object. It also means an application or | ||||
475 | module could do this: | ||||
476 | |||||
477 | $SIG{__DIE__} = sub { Exception::Class::Base->throw( error => join '', @_ ); }; | ||||
478 | |||||
479 | and this would probably not break anything (unless someone was | ||||
480 | expecting a different type of exception object from C<die()>). | ||||
481 | |||||
482 | =head1 OVERRIDING THE as_string METHOD | ||||
483 | |||||
484 | By default, the C<as_string()> method simply returns the value | ||||
485 | C<message> or C<error> param plus a stack trace, if the class's | ||||
486 | C<Trace()> method returns a true value or C<show_trace> was set when | ||||
487 | creating the exception. | ||||
488 | |||||
489 | However, once you add new fields to a subclass, you may want to | ||||
490 | include those fields in the stringified error. | ||||
491 | |||||
492 | Inside the C<as_string()> method, the message (non-stack trace) | ||||
493 | portion of the error is generated by calling the C<full_message()> | ||||
494 | method. This can be easily overridden. For example: | ||||
495 | |||||
496 | sub full_message { | ||||
497 | my $self = shift; | ||||
498 | |||||
499 | my $msg = $self->message; | ||||
500 | |||||
501 | $msg .= " and foo was " . $self->foo; | ||||
502 | |||||
503 | return $msg; | ||||
504 | } | ||||
505 | |||||
506 | =head1 AUTHOR | ||||
507 | |||||
508 | Dave Rolsky <autarch@urth.org> | ||||
509 | |||||
510 | =head1 COPYRIGHT AND LICENSE | ||||
511 | |||||
512 | This software is Copyright (c) 2010 by Dave Rolsky. | ||||
513 | |||||
514 | This is free software, licensed under: | ||||
515 | |||||
516 | The Artistic License 2.0 | ||||
517 | |||||
518 | =cut | ||||
519 | |||||
520 | |||||
521 | __END__ |