lib/DBIx/Class/Exception.pm

   1 package DBIx::Class::Exception;
   2
   3 use strict;
   4 use warnings;
   5
   6 # load Carp early to prevent tickling of the ::Internal stash being
   7 # interpreted as "Carp is already loaded" by some braindead loader
   8 use Carp ();
   9 $Carp::Internal{ (__PACKAGE__) }++;
  10
  11 use DBIx::Class::Carp ();
  12
  13 use overload
  14     '""' => sub { shift->{msg} },
  15     fallback => 1;
  16
  17 =head1 NAME
  18
  19 DBIx::Class::Exception - Exception objects for DBIx::Class
  20
  21 =head1 DESCRIPTION
  22
  23 Exception objects of this class are used internally by
  24 the default error handling of L<DBIx::Class::Schema/throw_exception>
  25 and derivatives.
  26
  27 These objects stringify to the contained error message, and use
  28 overload fallback to give natural boolean/numeric values.
  29
  30 =head1 METHODS
  31
  32 =head2 throw
  33
  34 =over 4
  35
  36 =item Arguments: $exception_scalar, $stacktrace
  37
  38 =back
  39
  40 This is meant for internal use by L<DBIx::Class>'s C<throw_exception>
  41 code, and shouldn't be used directly elsewhere.
  42
  43 Expects a scalar exception message. The optional boolean C<$stacktrace>
  44 causes it to output a full trace similar to L<confess|Carp/DESCRIPTION>.
  45
  46   DBIx::Class::Exception->throw('Foo');
  47   try { ... } catch { DBIx::Class::Exception->throw(shift) }
  48
  49 =cut
  50
  51 sub throw {
  52     my ($class, $msg, $stacktrace) = @_;
  53
  54     # Don't re-encapsulate exception objects of any kind
  55     die $msg if ref($msg);
  56
  57     # all exceptions include a caller
  58     $msg =~ s/\n$//;
  59
  60     if(!$stacktrace) {
  61         # skip all frames that match the original caller, or any of
  62         # the dbic-wide classdata patterns
  63         my ($ln, $calling) = DBIx::Class::Carp::__find_caller(
  64           '^' . CORE::caller() . '$',
  65           'DBIx::Class',
  66         );
  67
  68         $msg = "${calling}${msg} ${ln}\n";
  69     }
  70     else {
  71         $msg = Carp::longmess($msg);
  72     }
  73
  74     my $self = { msg => $msg };
  75     bless $self => $class;
  76
  77     die $self;
  78 }
  79
  80 =head2 rethrow
  81
  82 This method provides some syntactic sugar in order to
  83 re-throw exceptions.
  84
  85 =cut
  86
  87 sub rethrow {
  88     die shift;
  89 }
  90
  91 =head1 FURTHER QUESTIONS?
  92
  93 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
  94
  95 =head1 COPYRIGHT AND LICENSE
  96
  97 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
  98 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
  99 redistribute it and/or modify it under the same terms as the
 100 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
 101
 102 =cut
 103
 104 1;