lib/DBIx/Class/Exception.pm

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