Remove dead code commented out since 2006 ( 953a18ef )
[dbsrgits/DBIx-Class.git] / 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;