]>
Commit | Line | Data |
---|---|---|
5c4082fd PB |
1 | # Error.pm |
2 | # | |
3 | # Copyright (c) 1997-8 Graham Barr <gbarr@ti.com>. All rights reserved. | |
4 | # This program is free software; you can redistribute it and/or | |
5 | # modify it under the same terms as Perl itself. | |
6 | # | |
7 | # Based on my original Error.pm, and Exceptions.pm by Peter Seibel | |
8 | # <peter@weblogic.com> and adapted by Jesse Glick <jglick@sig.bsh.com>. | |
9 | # | |
10 | # but modified ***significantly*** | |
11 | ||
12 | package Error; | |
13 | ||
14 | use strict; | |
15 | use vars qw($VERSION); | |
16 | use 5.004; | |
17 | ||
18 | $VERSION = "0.15009"; | |
19 | ||
20 | use overload ( | |
21 | '""' => 'stringify', | |
22 | '0+' => 'value', | |
23 | 'bool' => sub { return 1; }, | |
24 | 'fallback' => 1 | |
25 | ); | |
26 | ||
27 | $Error::Depth = 0; # Depth to pass to caller() | |
28 | $Error::Debug = 0; # Generate verbose stack traces | |
29 | @Error::STACK = (); # Clause stack for try | |
30 | $Error::THROWN = undef; # last error thrown, a workaround until die $ref works | |
31 | ||
32 | my $LAST; # Last error created | |
33 | my %ERROR; # Last error associated with package | |
34 | ||
35 | sub throw_Error_Simple | |
36 | { | |
37 | my $args = shift; | |
38 | return Error::Simple->new($args->{'text'}); | |
39 | } | |
40 | ||
41 | $Error::ObjectifyCallback = \&throw_Error_Simple; | |
42 | ||
43 | ||
44 | # Exported subs are defined in Error::subs | |
45 | ||
5c4082fd PB |
46 | sub import { |
47 | shift; | |
48 | local $Exporter::ExportLevel = $Exporter::ExportLevel + 1; | |
49 | Error::subs->import(@_); | |
50 | } | |
51 | ||
52 | # I really want to use last for the name of this method, but it is a keyword | |
53 | # which prevent the syntax last Error | |
54 | ||
55 | sub prior { | |
56 | shift; # ignore | |
57 | ||
58 | return $LAST unless @_; | |
59 | ||
60 | my $pkg = shift; | |
61 | return exists $ERROR{$pkg} ? $ERROR{$pkg} : undef | |
62 | unless ref($pkg); | |
63 | ||
64 | my $obj = $pkg; | |
65 | my $err = undef; | |
66 | if($obj->isa('HASH')) { | |
67 | $err = $obj->{'__Error__'} | |
68 | if exists $obj->{'__Error__'}; | |
69 | } | |
70 | elsif($obj->isa('GLOB')) { | |
71 | $err = ${*$obj}{'__Error__'} | |
72 | if exists ${*$obj}{'__Error__'}; | |
73 | } | |
74 | ||
75 | $err; | |
76 | } | |
77 | ||
78 | sub flush { | |
79 | shift; #ignore | |
80 | ||
81 | unless (@_) { | |
82 | $LAST = undef; | |
83 | return; | |
84 | } | |
85 | ||
86 | my $pkg = shift; | |
87 | return unless ref($pkg); | |
88 | ||
89 | undef $ERROR{$pkg} if defined $ERROR{$pkg}; | |
90 | } | |
91 | ||
92 | # Return as much information as possible about where the error | |
93 | # happened. The -stacktrace element only exists if $Error::DEBUG | |
94 | # was set when the error was created | |
95 | ||
96 | sub stacktrace { | |
97 | my $self = shift; | |
98 | ||
99 | return $self->{'-stacktrace'} | |
100 | if exists $self->{'-stacktrace'}; | |
101 | ||
102 | my $text = exists $self->{'-text'} ? $self->{'-text'} : "Died"; | |
103 | ||
104 | $text .= sprintf(" at %s line %d.\n", $self->file, $self->line) | |
105 | unless($text =~ /\n$/s); | |
106 | ||
107 | $text; | |
108 | } | |
109 | ||
110 | # Allow error propagation, ie | |
111 | # | |
112 | # $ber->encode(...) or | |
113 | # return Error->prior($ber)->associate($ldap); | |
114 | ||
115 | sub associate { | |
116 | my $err = shift; | |
117 | my $obj = shift; | |
118 | ||
119 | return unless ref($obj); | |
120 | ||
121 | if($obj->isa('HASH')) { | |
122 | $obj->{'__Error__'} = $err; | |
123 | } | |
124 | elsif($obj->isa('GLOB')) { | |
125 | ${*$obj}{'__Error__'} = $err; | |
126 | } | |
127 | $obj = ref($obj); | |
128 | $ERROR{ ref($obj) } = $err; | |
129 | ||
130 | return; | |
131 | } | |
132 | ||
133 | sub new { | |
134 | my $self = shift; | |
135 | my($pkg,$file,$line) = caller($Error::Depth); | |
136 | ||
137 | my $err = bless { | |
138 | '-package' => $pkg, | |
139 | '-file' => $file, | |
140 | '-line' => $line, | |
141 | @_ | |
142 | }, $self; | |
143 | ||
144 | $err->associate($err->{'-object'}) | |
145 | if(exists $err->{'-object'}); | |
146 | ||
147 | # To always create a stacktrace would be very inefficient, so | |
148 | # we only do it if $Error::Debug is set | |
149 | ||
150 | if($Error::Debug) { | |
151 | require Carp; | |
152 | local $Carp::CarpLevel = $Error::Depth; | |
153 | my $text = defined($err->{'-text'}) ? $err->{'-text'} : "Error"; | |
154 | my $trace = Carp::longmess($text); | |
155 | # Remove try calls from the trace | |
156 | $trace =~ s/(\n\s+\S+__ANON__[^\n]+)?\n\s+eval[^\n]+\n\s+Error::subs::try[^\n]+(?=\n)//sog; | |
157 | $trace =~ s/(\n\s+\S+__ANON__[^\n]+)?\n\s+eval[^\n]+\n\s+Error::subs::run_clauses[^\n]+\n\s+Error::subs::try[^\n]+(?=\n)//sog; | |
158 | $err->{'-stacktrace'} = $trace | |
159 | } | |
160 | ||
161 | $@ = $LAST = $ERROR{$pkg} = $err; | |
162 | } | |
163 | ||
164 | # Throw an error. this contains some very gory code. | |
165 | ||
166 | sub throw { | |
167 | my $self = shift; | |
168 | local $Error::Depth = $Error::Depth + 1; | |
169 | ||
170 | # if we are not rethrow-ing then create the object to throw | |
171 | $self = $self->new(@_) unless ref($self); | |
172 | ||
173 | die $Error::THROWN = $self; | |
174 | } | |
175 | ||
176 | # syntactic sugar for | |
177 | # | |
178 | # die with Error( ... ); | |
179 | ||
180 | sub with { | |
181 | my $self = shift; | |
182 | local $Error::Depth = $Error::Depth + 1; | |
183 | ||
184 | $self->new(@_); | |
185 | } | |
186 | ||
187 | # syntactic sugar for | |
188 | # | |
189 | # record Error( ... ) and return; | |
190 | ||
191 | sub record { | |
192 | my $self = shift; | |
193 | local $Error::Depth = $Error::Depth + 1; | |
194 | ||
195 | $self->new(@_); | |
196 | } | |
197 | ||
198 | # catch clause for | |
199 | # | |
200 | # try { ... } catch CLASS with { ... } | |
201 | ||
202 | sub catch { | |
203 | my $pkg = shift; | |
204 | my $code = shift; | |
205 | my $clauses = shift || {}; | |
206 | my $catch = $clauses->{'catch'} ||= []; | |
207 | ||
208 | unshift @$catch, $pkg, $code; | |
209 | ||
210 | $clauses; | |
211 | } | |
212 | ||
213 | # Object query methods | |
214 | ||
215 | sub object { | |
216 | my $self = shift; | |
217 | exists $self->{'-object'} ? $self->{'-object'} : undef; | |
218 | } | |
219 | ||
220 | sub file { | |
221 | my $self = shift; | |
222 | exists $self->{'-file'} ? $self->{'-file'} : undef; | |
223 | } | |
224 | ||
225 | sub line { | |
226 | my $self = shift; | |
227 | exists $self->{'-line'} ? $self->{'-line'} : undef; | |
228 | } | |
229 | ||
230 | sub text { | |
231 | my $self = shift; | |
232 | exists $self->{'-text'} ? $self->{'-text'} : undef; | |
233 | } | |
234 | ||
235 | # overload methods | |
236 | ||
237 | sub stringify { | |
238 | my $self = shift; | |
239 | defined $self->{'-text'} ? $self->{'-text'} : "Died"; | |
240 | } | |
241 | ||
242 | sub value { | |
243 | my $self = shift; | |
244 | exists $self->{'-value'} ? $self->{'-value'} : undef; | |
245 | } | |
246 | ||
247 | package Error::Simple; | |
248 | ||
249 | @Error::Simple::ISA = qw(Error); | |
250 | ||
251 | sub new { | |
252 | my $self = shift; | |
253 | my $text = "" . shift; | |
254 | my $value = shift; | |
255 | my(@args) = (); | |
256 | ||
257 | local $Error::Depth = $Error::Depth + 1; | |
258 | ||
259 | @args = ( -file => $1, -line => $2) | |
260 | if($text =~ s/\s+at\s+(\S+)\s+line\s+(\d+)(?:,\s*<[^>]*>\s+line\s+\d+)?\.?\n?$//s); | |
261 | push(@args, '-value', 0 + $value) | |
262 | if defined($value); | |
263 | ||
264 | $self->SUPER::new(-text => $text, @args); | |
265 | } | |
266 | ||
267 | sub stringify { | |
268 | my $self = shift; | |
269 | my $text = $self->SUPER::stringify; | |
270 | $text .= sprintf(" at %s line %d.\n", $self->file, $self->line) | |
271 | unless($text =~ /\n$/s); | |
272 | $text; | |
273 | } | |
274 | ||
275 | ########################################################################## | |
276 | ########################################################################## | |
277 | ||
278 | # Inspired by code from Jesse Glick <jglick@sig.bsh.com> and | |
279 | # Peter Seibel <peter@weblogic.com> | |
280 | ||
281 | package Error::subs; | |
282 | ||
283 | use Exporter (); | |
284 | use vars qw(@EXPORT_OK @ISA %EXPORT_TAGS); | |
285 | ||
286 | @EXPORT_OK = qw(try with finally except otherwise); | |
287 | %EXPORT_TAGS = (try => \@EXPORT_OK); | |
288 | ||
289 | @ISA = qw(Exporter); | |
290 | ||
96bc4de8 PB |
291 | |
292 | sub blessed { | |
293 | my $item = shift; | |
294 | local $@; # don't kill an outer $@ | |
295 | ref $item and eval { $item->can('can') }; | |
296 | } | |
297 | ||
298 | ||
5c4082fd PB |
299 | sub run_clauses ($$$\@) { |
300 | my($clauses,$err,$wantarray,$result) = @_; | |
301 | my $code = undef; | |
302 | ||
303 | $err = $Error::ObjectifyCallback->({'text' =>$err}) unless ref($err); | |
304 | ||
305 | CATCH: { | |
306 | ||
307 | # catch | |
308 | my $catch; | |
309 | if(defined($catch = $clauses->{'catch'})) { | |
310 | my $i = 0; | |
311 | ||
312 | CATCHLOOP: | |
313 | for( ; $i < @$catch ; $i += 2) { | |
314 | my $pkg = $catch->[$i]; | |
315 | unless(defined $pkg) { | |
316 | #except | |
317 | splice(@$catch,$i,2,$catch->[$i+1]->()); | |
318 | $i -= 2; | |
319 | next CATCHLOOP; | |
320 | } | |
96bc4de8 | 321 | elsif(blessed($err) && $err->isa($pkg)) { |
5c4082fd PB |
322 | $code = $catch->[$i+1]; |
323 | while(1) { | |
324 | my $more = 0; | |
325 | local($Error::THROWN); | |
326 | my $ok = eval { | |
327 | if($wantarray) { | |
328 | @{$result} = $code->($err,\$more); | |
329 | } | |
330 | elsif(defined($wantarray)) { | |
331 | @{$result} = (); | |
332 | $result->[0] = $code->($err,\$more); | |
333 | } | |
334 | else { | |
335 | $code->($err,\$more); | |
336 | } | |
337 | 1; | |
338 | }; | |
339 | if( $ok ) { | |
340 | next CATCHLOOP if $more; | |
341 | undef $err; | |
342 | } | |
343 | else { | |
344 | $err = defined($Error::THROWN) | |
345 | ? $Error::THROWN : $@; | |
346 | $err = $Error::ObjectifyCallback->({'text' =>$err}) | |
347 | unless ref($err); | |
348 | } | |
349 | last CATCH; | |
350 | }; | |
351 | } | |
352 | } | |
353 | } | |
354 | ||
355 | # otherwise | |
356 | my $owise; | |
357 | if(defined($owise = $clauses->{'otherwise'})) { | |
358 | my $code = $clauses->{'otherwise'}; | |
359 | my $more = 0; | |
360 | my $ok = eval { | |
361 | if($wantarray) { | |
362 | @{$result} = $code->($err,\$more); | |
363 | } | |
364 | elsif(defined($wantarray)) { | |
365 | @{$result} = (); | |
366 | $result->[0] = $code->($err,\$more); | |
367 | } | |
368 | else { | |
369 | $code->($err,\$more); | |
370 | } | |
371 | 1; | |
372 | }; | |
373 | if( $ok ) { | |
374 | undef $err; | |
375 | } | |
376 | else { | |
377 | $err = defined($Error::THROWN) | |
378 | ? $Error::THROWN : $@; | |
379 | ||
380 | $err = $Error::ObjectifyCallback->({'text' =>$err}) | |
381 | unless ref($err); | |
382 | } | |
383 | } | |
384 | } | |
385 | $err; | |
386 | } | |
387 | ||
388 | sub try (&;$) { | |
389 | my $try = shift; | |
390 | my $clauses = @_ ? shift : {}; | |
391 | my $ok = 0; | |
392 | my $err = undef; | |
393 | my @result = (); | |
394 | ||
395 | unshift @Error::STACK, $clauses; | |
396 | ||
397 | my $wantarray = wantarray(); | |
398 | ||
399 | do { | |
400 | local $Error::THROWN = undef; | |
401 | local $@ = undef; | |
402 | ||
403 | $ok = eval { | |
404 | if($wantarray) { | |
405 | @result = $try->(); | |
406 | } | |
407 | elsif(defined $wantarray) { | |
408 | $result[0] = $try->(); | |
409 | } | |
410 | else { | |
411 | $try->(); | |
412 | } | |
413 | 1; | |
414 | }; | |
415 | ||
416 | $err = defined($Error::THROWN) ? $Error::THROWN : $@ | |
417 | unless $ok; | |
418 | }; | |
419 | ||
420 | shift @Error::STACK; | |
421 | ||
422 | $err = run_clauses($clauses,$err,wantarray,@result) | |
423 | unless($ok); | |
424 | ||
425 | $clauses->{'finally'}->() | |
426 | if(defined($clauses->{'finally'})); | |
427 | ||
428 | if (defined($err)) | |
429 | { | |
96bc4de8 | 430 | if (blessed($err) && $err->can('throw')) |
5c4082fd PB |
431 | { |
432 | throw $err; | |
433 | } | |
434 | else | |
435 | { | |
436 | die $err; | |
437 | } | |
438 | } | |
439 | ||
440 | wantarray ? @result : $result[0]; | |
441 | } | |
442 | ||
443 | # Each clause adds a sub to the list of clauses. The finally clause is | |
444 | # always the last, and the otherwise clause is always added just before | |
445 | # the finally clause. | |
446 | # | |
447 | # All clauses, except the finally clause, add a sub which takes one argument | |
448 | # this argument will be the error being thrown. The sub will return a code ref | |
449 | # if that clause can handle that error, otherwise undef is returned. | |
450 | # | |
451 | # The otherwise clause adds a sub which unconditionally returns the users | |
452 | # code reference, this is why it is forced to be last. | |
453 | # | |
454 | # The catch clause is defined in Error.pm, as the syntax causes it to | |
455 | # be called as a method | |
456 | ||
457 | sub with (&;$) { | |
458 | @_ | |
459 | } | |
460 | ||
461 | sub finally (&) { | |
462 | my $code = shift; | |
463 | my $clauses = { 'finally' => $code }; | |
464 | $clauses; | |
465 | } | |
466 | ||
467 | # The except clause is a block which returns a hashref or a list of | |
468 | # key-value pairs, where the keys are the classes and the values are subs. | |
469 | ||
470 | sub except (&;$) { | |
471 | my $code = shift; | |
472 | my $clauses = shift || {}; | |
473 | my $catch = $clauses->{'catch'} ||= []; | |
474 | ||
475 | my $sub = sub { | |
476 | my $ref; | |
477 | my(@array) = $code->($_[0]); | |
478 | if(@array == 1 && ref($array[0])) { | |
479 | $ref = $array[0]; | |
480 | $ref = [ %$ref ] | |
481 | if(UNIVERSAL::isa($ref,'HASH')); | |
482 | } | |
483 | else { | |
484 | $ref = \@array; | |
485 | } | |
486 | @$ref | |
487 | }; | |
488 | ||
489 | unshift @{$catch}, undef, $sub; | |
490 | ||
491 | $clauses; | |
492 | } | |
493 | ||
494 | sub otherwise (&;$) { | |
495 | my $code = shift; | |
496 | my $clauses = shift || {}; | |
497 | ||
498 | if(exists $clauses->{'otherwise'}) { | |
499 | require Carp; | |
500 | Carp::croak("Multiple otherwise clauses"); | |
501 | } | |
502 | ||
503 | $clauses->{'otherwise'} = $code; | |
504 | ||
505 | $clauses; | |
506 | } | |
507 | ||
508 | 1; | |
509 | __END__ | |
510 | ||
511 | =head1 NAME | |
512 | ||
513 | Error - Error/exception handling in an OO-ish way | |
514 | ||
515 | =head1 SYNOPSIS | |
516 | ||
517 | use Error qw(:try); | |
518 | ||
519 | throw Error::Simple( "A simple error"); | |
520 | ||
521 | sub xyz { | |
522 | ... | |
523 | record Error::Simple("A simple error") | |
524 | and return; | |
525 | } | |
526 | ||
527 | unlink($file) or throw Error::Simple("$file: $!",$!); | |
528 | ||
529 | try { | |
530 | do_some_stuff(); | |
531 | die "error!" if $condition; | |
532 | throw Error::Simple -text => "Oops!" if $other_condition; | |
533 | } | |
534 | catch Error::IO with { | |
535 | my $E = shift; | |
536 | print STDERR "File ", $E->{'-file'}, " had a problem\n"; | |
537 | } | |
538 | except { | |
539 | my $E = shift; | |
540 | my $general_handler=sub {send_message $E->{-description}}; | |
541 | return { | |
542 | UserException1 => $general_handler, | |
543 | UserException2 => $general_handler | |
544 | }; | |
545 | } | |
546 | otherwise { | |
547 | print STDERR "Well I don't know what to say\n"; | |
548 | } | |
549 | finally { | |
550 | close_the_garage_door_already(); # Should be reliable | |
551 | }; # Don't forget the trailing ; or you might be surprised | |
552 | ||
553 | =head1 DESCRIPTION | |
554 | ||
555 | The C<Error> package provides two interfaces. Firstly C<Error> provides | |
556 | a procedural interface to exception handling. Secondly C<Error> is a | |
557 | base class for errors/exceptions that can either be thrown, for | |
558 | subsequent catch, or can simply be recorded. | |
559 | ||
560 | Errors in the class C<Error> should not be thrown directly, but the | |
561 | user should throw errors from a sub-class of C<Error>. | |
562 | ||
563 | =head1 PROCEDURAL INTERFACE | |
564 | ||
565 | C<Error> exports subroutines to perform exception handling. These will | |
566 | be exported if the C<:try> tag is used in the C<use> line. | |
567 | ||
568 | =over 4 | |
569 | ||
570 | =item try BLOCK CLAUSES | |
571 | ||
572 | C<try> is the main subroutine called by the user. All other subroutines | |
573 | exported are clauses to the try subroutine. | |
574 | ||
575 | The BLOCK will be evaluated and, if no error is throw, try will return | |
576 | the result of the block. | |
577 | ||
578 | C<CLAUSES> are the subroutines below, which describe what to do in the | |
579 | event of an error being thrown within BLOCK. | |
580 | ||
581 | =item catch CLASS with BLOCK | |
582 | ||
583 | This clauses will cause all errors that satisfy C<$err-E<gt>isa(CLASS)> | |
584 | to be caught and handled by evaluating C<BLOCK>. | |
585 | ||
586 | C<BLOCK> will be passed two arguments. The first will be the error | |
587 | being thrown. The second is a reference to a scalar variable. If this | |
588 | variable is set by the catch block then, on return from the catch | |
589 | block, try will continue processing as if the catch block was never | |
590 | found. | |
591 | ||
592 | To propagate the error the catch block may call C<$err-E<gt>throw> | |
593 | ||
594 | If the scalar reference by the second argument is not set, and the | |
595 | error is not thrown. Then the current try block will return with the | |
596 | result from the catch block. | |
597 | ||
598 | =item except BLOCK | |
599 | ||
600 | When C<try> is looking for a handler, if an except clause is found | |
601 | C<BLOCK> is evaluated. The return value from this block should be a | |
602 | HASHREF or a list of key-value pairs, where the keys are class names | |
603 | and the values are CODE references for the handler of errors of that | |
604 | type. | |
605 | ||
606 | =item otherwise BLOCK | |
607 | ||
608 | Catch any error by executing the code in C<BLOCK> | |
609 | ||
610 | When evaluated C<BLOCK> will be passed one argument, which will be the | |
611 | error being processed. | |
612 | ||
613 | Only one otherwise block may be specified per try block | |
614 | ||
615 | =item finally BLOCK | |
616 | ||
617 | Execute the code in C<BLOCK> either after the code in the try block has | |
618 | successfully completed, or if the try block throws an error then | |
619 | C<BLOCK> will be executed after the handler has completed. | |
620 | ||
621 | If the handler throws an error then the error will be caught, the | |
622 | finally block will be executed and the error will be re-thrown. | |
623 | ||
624 | Only one finally block may be specified per try block | |
625 | ||
626 | =back | |
627 | ||
628 | =head1 CLASS INTERFACE | |
629 | ||
630 | =head2 CONSTRUCTORS | |
631 | ||
632 | The C<Error> object is implemented as a HASH. This HASH is initialized | |
633 | with the arguments that are passed to it's constructor. The elements | |
634 | that are used by, or are retrievable by the C<Error> class are listed | |
635 | below, other classes may add to these. | |
636 | ||
637 | -file | |
638 | -line | |
639 | -text | |
640 | -value | |
641 | -object | |
642 | ||
643 | If C<-file> or C<-line> are not specified in the constructor arguments | |
644 | then these will be initialized with the file name and line number where | |
645 | the constructor was called from. | |
646 | ||
647 | If the error is associated with an object then the object should be | |
648 | passed as the C<-object> argument. This will allow the C<Error> package | |
649 | to associate the error with the object. | |
650 | ||
651 | The C<Error> package remembers the last error created, and also the | |
652 | last error associated with a package. This could either be the last | |
653 | error created by a sub in that package, or the last error which passed | |
654 | an object blessed into that package as the C<-object> argument. | |
655 | ||
656 | =over 4 | |
657 | ||
658 | =item throw ( [ ARGS ] ) | |
659 | ||
660 | Create a new C<Error> object and throw an error, which will be caught | |
661 | by a surrounding C<try> block, if there is one. Otherwise it will cause | |
662 | the program to exit. | |
663 | ||
664 | C<throw> may also be called on an existing error to re-throw it. | |
665 | ||
666 | =item with ( [ ARGS ] ) | |
667 | ||
668 | Create a new C<Error> object and returns it. This is defined for | |
669 | syntactic sugar, eg | |
670 | ||
671 | die with Some::Error ( ... ); | |
672 | ||
673 | =item record ( [ ARGS ] ) | |
674 | ||
675 | Create a new C<Error> object and returns it. This is defined for | |
676 | syntactic sugar, eg | |
677 | ||
678 | record Some::Error ( ... ) | |
679 | and return; | |
680 | ||
681 | =back | |
682 | ||
683 | =head2 STATIC METHODS | |
684 | ||
685 | =over 4 | |
686 | ||
687 | =item prior ( [ PACKAGE ] ) | |
688 | ||
689 | Return the last error created, or the last error associated with | |
690 | C<PACKAGE> | |
691 | ||
692 | =item flush ( [ PACKAGE ] ) | |
693 | ||
694 | Flush the last error created, or the last error associated with | |
695 | C<PACKAGE>.It is necessary to clear the error stack before exiting the | |
696 | package or uncaught errors generated using C<record> will be reported. | |
697 | ||
698 | $Error->flush; | |
699 | ||
700 | =cut | |
701 | ||
702 | =back | |
703 | ||
704 | =head2 OBJECT METHODS | |
705 | ||
706 | =over 4 | |
707 | ||
708 | =item stacktrace | |
709 | ||
710 | If the variable C<$Error::Debug> was non-zero when the error was | |
711 | created, then C<stacktrace> returns a string created by calling | |
712 | C<Carp::longmess>. If the variable was zero the C<stacktrace> returns | |
713 | the text of the error appended with the filename and line number of | |
714 | where the error was created, providing the text does not end with a | |
715 | newline. | |
716 | ||
717 | =item object | |
718 | ||
719 | The object this error was associated with | |
720 | ||
721 | =item file | |
722 | ||
723 | The file where the constructor of this error was called from | |
724 | ||
725 | =item line | |
726 | ||
727 | The line where the constructor of this error was called from | |
728 | ||
729 | =item text | |
730 | ||
731 | The text of the error | |
732 | ||
733 | =back | |
734 | ||
735 | =head2 OVERLOAD METHODS | |
736 | ||
737 | =over 4 | |
738 | ||
739 | =item stringify | |
740 | ||
741 | A method that converts the object into a string. This method may simply | |
742 | return the same as the C<text> method, or it may append more | |
743 | information. For example the file name and line number. | |
744 | ||
745 | By default this method returns the C<-text> argument that was passed to | |
746 | the constructor, or the string C<"Died"> if none was given. | |
747 | ||
748 | =item value | |
749 | ||
750 | A method that will return a value that can be associated with the | |
751 | error. For example if an error was created due to the failure of a | |
752 | system call, then this may return the numeric value of C<$!> at the | |
753 | time. | |
754 | ||
755 | By default this method returns the C<-value> argument that was passed | |
756 | to the constructor. | |
757 | ||
758 | =back | |
759 | ||
760 | =head1 PRE-DEFINED ERROR CLASSES | |
761 | ||
762 | =over 4 | |
763 | ||
764 | =item Error::Simple | |
765 | ||
766 | This class can be used to hold simple error strings and values. It's | |
767 | constructor takes two arguments. The first is a text value, the second | |
768 | is a numeric value. These values are what will be returned by the | |
769 | overload methods. | |
770 | ||
771 | If the text value ends with C<at file line 1> as $@ strings do, then | |
772 | this infomation will be used to set the C<-file> and C<-line> arguments | |
773 | of the error object. | |
774 | ||
775 | This class is used internally if an eval'd block die's with an error | |
776 | that is a plain string. (Unless C<$Error::ObjectifyCallback> is modified) | |
777 | ||
778 | =back | |
779 | ||
780 | =head1 $Error::ObjectifyCallback | |
781 | ||
782 | This variable holds a reference to a subroutine that converts errors that | |
783 | are plain strings to objects. It is used by Error.pm to convert textual | |
3dff5379 | 784 | errors to objects, and can be overridden by the user. |
5c4082fd PB |
785 | |
786 | It accepts a single argument which is a hash reference to named parameters. | |
787 | Currently the only named parameter passed is C<'text'> which is the text | |
788 | of the error, but others may be available in the future. | |
789 | ||
790 | For example the following code will cause Error.pm to throw objects of the | |
791 | class MyError::Bar by default: | |
792 | ||
793 | sub throw_MyError_Bar | |
794 | { | |
795 | my $args = shift; | |
796 | my $err = MyError::Bar->new(); | |
797 | $err->{'MyBarText'} = $args->{'text'}; | |
798 | return $err; | |
799 | } | |
800 | ||
801 | { | |
802 | local $Error::ObjectifyCallback = \&throw_MyError_Bar; | |
803 | ||
804 | # Error handling here. | |
805 | } | |
806 | ||
807 | =head1 KNOWN BUGS | |
808 | ||
809 | None, but that does not mean there are not any. | |
810 | ||
811 | =head1 AUTHORS | |
812 | ||
813 | Graham Barr <gbarr@pobox.com> | |
814 | ||
815 | The code that inspired me to write this was originally written by | |
816 | Peter Seibel <peter@weblogic.com> and adapted by Jesse Glick | |
817 | <jglick@sig.bsh.com>. | |
818 | ||
819 | =head1 MAINTAINER | |
820 | ||
821 | Shlomi Fish <shlomif@iglu.org.il> | |
822 | ||
823 | =head1 PAST MAINTAINERS | |
824 | ||
825 | Arun Kumar U <u_arunkumar@yahoo.com> | |
826 | ||
827 | =cut |