| 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 | Exception::Class::Base::BEGIN@10 |
| 1 | 1 | 1 | 1.10ms | 1.37ms | Exception::Class::Base::BEGIN@9 |
| 1 | 1 | 1 | 257µs | 257µs | Exception::Class::Base::BEGIN@37 |
| 1 | 1 | 1 | 151µs | 400µs | Exception::Class::Base::BEGIN@15 |
| 1 | 1 | 1 | 50µs | 74µs | Exception::Class::Base::BEGIN@7 |
| 1 | 1 | 1 | 38µs | 180µs | Exception::Class::Base::BEGIN@11 |
| 1 | 1 | 1 | 37µs | 88µs | Exception::Class::Base::BEGIN@43 |
| 1 | 1 | 1 | 35µs | 311µs | Exception::Class::Base::BEGIN@13 |
| 1 | 1 | 1 | 35µs | 233µs | Exception::Class::Base::BEGIN@34 |
| 1 | 1 | 1 | 32µs | 32µs | Exception::Class::Base::BEGIN@2 |
| 1 | 1 | 1 | 27µs | 38µs | Exception::Class::Base::BEGIN@6 |
| 1 | 1 | 1 | 26µs | 63µs | Exception::Class::Base::BEGIN@63 |
| 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__[:34] |
| 0 | 0 | 0 | 0s | 0s | Exception::Class::Base::__ANON__[:41] |
| 0 | 0 | 0 | 0s | 0s | Exception::Class::Base::__ANON__[:62] |
| 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 | # 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__ |