| 1 | |
| 2 | =head1 NAME |
| 3 | |
| 4 | Carp::Clan - Report errors from perspective of caller of a "clan" of modules |
| 5 | |
| 6 | =head1 SYNOPSIS |
| 7 | |
| 8 | carp - warn of errors (from perspective of caller) |
| 9 | |
| 10 | cluck - warn of errors with stack backtrace |
| 11 | |
| 12 | croak - die of errors (from perspective of caller) |
| 13 | |
| 14 | confess - die of errors with stack backtrace |
| 15 | |
| 16 | use Carp::Clan qw(^MyClan::); |
| 17 | croak "We're outta here!"; |
| 18 | |
| 19 | use Carp::Clan; |
| 20 | confess "This is how we got here!"; |
| 21 | |
| 22 | =head1 DESCRIPTION |
| 23 | |
| 24 | This module is based on "C<Carp.pm>" from Perl 5.005_03. It has been |
| 25 | modified to skip all package names matching the pattern given in |
| 26 | the "use" statement inside the "C<qw()>" term (or argument list). |
| 27 | |
| 28 | Suppose you have a family of modules or classes named "Pack::A", |
| 29 | "Pack::B" and so on, and each of them uses "C<Carp::Clan qw(^Pack::);>" |
| 30 | (or at least the one in which the error or warning gets raised). |
| 31 | |
| 32 | Thus when for example your script "tool.pl" calls module "Pack::A", |
| 33 | and module "Pack::A" calls module "Pack::B", an exception raised in |
| 34 | module "Pack::B" will appear to have originated in "tool.pl" where |
| 35 | "Pack::A" was called, and not in "Pack::A" where "Pack::B" was called, |
| 36 | as the unmodified "C<Carp.pm>" would try to make you believe C<:-)>. |
| 37 | |
| 38 | This works similarly if "Pack::B" calls "Pack::C" where the |
| 39 | exception is raised, etcetera. |
| 40 | |
| 41 | In other words, this blames all errors in the "C<Pack::*>" modules |
| 42 | on the user of these modules, i.e., on you. C<;-)> |
| 43 | |
| 44 | The skipping of a clan (or family) of packages according to a pattern |
| 45 | describing its members is necessary in cases where these modules are |
| 46 | not classes derived from each other (and thus when examining C<@ISA> |
| 47 | (as in the original "C<Carp.pm>" module) doesn't help). |
| 48 | |
| 49 | The purpose and advantage of this is that a "clan" of modules can work |
| 50 | together (and call each other) and throw exceptions at various depths |
| 51 | down the calling hierarchy and still appear as a monolithic block (as |
| 52 | though they were a single module) from the perspective of the caller. |
| 53 | |
| 54 | In case you just want to ward off all error messages from the module |
| 55 | in which you "C<use Carp::Clan>", i.e., if you want to make all error |
| 56 | messages or warnings to appear to originate from where your module |
| 57 | was called (this is what you usually used to "C<use Carp;>" for C<;-)>), |
| 58 | instead of in your module itself (which is what you can do with a |
| 59 | "die" or "warn" anyway), you do not need to provide a pattern, |
| 60 | the module will automatically provide the correct one for you. |
| 61 | |
| 62 | I.e., just "C<use Carp::Clan;>" without any arguments and call "carp" |
| 63 | or "croak" as appropriate, and they will automatically defend your |
| 64 | module against all blames! |
| 65 | |
| 66 | In other words, a pattern is only necessary if you want to make |
| 67 | several modules (more than one) work together and appear as though |
| 68 | they were only one. |
| 69 | |
| 70 | =head2 Forcing a Stack Trace |
| 71 | |
| 72 | As a debugging aid, you can force "C<Carp::Clan>" to treat a "croak" as |
| 73 | a "confess" and a "carp" as a "cluck". In other words, force a detailed |
| 74 | stack trace to be given. This can be very helpful when trying to |
| 75 | understand why, or from where, a warning or error is being generated. |
| 76 | |
| 77 | This feature is enabled either by "importing" the non-existent symbol |
| 78 | 'verbose', or by setting the global variable "C<$Carp::Clan::Verbose>" |
| 79 | to a true value. |
| 80 | |
| 81 | You would typically enable it by saying |
| 82 | |
| 83 | use Carp::Clan qw(verbose); |
| 84 | |
| 85 | Note that you can both specify a "family pattern" and the string "verbose" |
| 86 | inside the "C<qw()>" term (or argument list) of the "use" statement, but |
| 87 | consider that a pattern of packages to skip is pointless when "verbose" |
| 88 | causes a full stack trace anyway. |
| 89 | |
| 90 | =head1 BUGS |
| 91 | |
| 92 | The "C<Carp::Clan>" routines don't handle exception objects currently. |
| 93 | If called with a first argument that is a reference, they simply |
| 94 | call "C<die()>" or "C<warn()>", as appropriate. |
| 95 | |