============================ Package "Carp::Clan" ============================ Copyright (c) 2006-2009 by Joshua ben Jore All rights reserved. Copyright (c) 2001-2009 by Steffen Beyer All rights reserved. Abstract: --------- This module reports errors from the perspective of the caller of a "clan" of modules, similar to "Carp.pm" itself. But instead of giving it a number of levels to skip on the calling stack, you give it a pattern to characterize the package names of the "clan" of modules which shall never be blamed for any error. :-) So these modules stick together like a "clan" and any error which occurs will be blamed on the "outsider" script or modules not belonging to this "clan". What's new in this release: --------------------------- Version 6.06 29.05.2016 + Avoid failure due to version self-check in 20pre560.t This test seems like a footgun for release management reasons, but apprently I wasn't quite as careful as I tried to be in keeping the last release minimal. Copyright & License: -------------------- This package with all its parts is Copyright (c) 2006-2009 by Joshua ben Jore Copyright (c) 2001-2009 by Steffen Beyer All rights reserved. This package is free software; you can use, modify and redistribute it under the same terms as Perl itself, i.e., at your option, under the terms either of the "Artistic License" or the "GNU General Public License". Prerequisites: -------------- Perl version 5.005_03 or higher. (Should probably also work with older versions of Perl, however.) Installation: ------------- As usual: perl Makefile.PL make make test make install Changes over previous versions: ------------------------------- Please refer to the file "Changes" in this distribution for a more detailed version history log. What does it do: ---------------- This module is based on "Carp.pm" from Perl 5.005_03. It has been modified to skip all package names matching the pattern given in the "use" statement inside the "qw()" term (or argument list). Suppose you have a family of modules or classes named "Pack::A", "Pack::B" and so on, and each of them uses "Carp::Clan qw(^Pack::);" (or at least the one in which the error or warning gets raised). Thus when for example your script "tool.pl" calls module "Pack::A", and module "Pack::A" calls module "Pack::B", an exception raised in module "Pack::B" will appear to have originated in "tool.pl" where "Pack::A" was called, and not in "Pack::A" where "Pack::B" was called, as the unmodified "Carp.pm" would try to make you believe :-). This works similarly if "Pack::B" calls "Pack::C" where the exception is raised, etcetera. In other words, this blames all errors in the "Pack::*" modules on the user of these modules, i.e., on you. ;-) The skipping of a clan (or family) of packages according to a pattern describing its members is necessary in cases where these modules are not classes derived from each other (and thus when examining "@ISA" - as in the original "Carp.pm" module - doesn't help). The purpose and advantage of this is that a "clan" of modules can work together (and call each other) and throw exceptions at various depths down the calling hierarchy and still appear as a monolithic block (as though they were a single module) from the perspective of the caller. In case you just want to ward off all error messages from the module in which you "use Carp::Clan", i.e., if you want to make all error messages or warnings to appear to originate from where your module was called (this is what you usually used to "use Carp;" for ;-) ), instead of in your module itself (which is what you can do with a "die" or "warn" anyway), you do not need to provide a pattern, the module will automatically provide the correct one for you. I.e., just "use Carp::Clan;" without any arguments and call "carp" or "croak" as appropriate, and they will automatically defend your module against all blames! In other words, a pattern is only necessary if you want to make several modules (more than one) work together and appear as though they were only one. Contact Authors: ---------------- Joshua ben Jore http://perlmonks.org/?node=diotalevi Steffen Beyer http://www.engelschall.com/u/sb/download/