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