============================
                    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 <jjore@cpan.org>
Copyright (c) 2001-2009 by Steffen Beyer <stbey@cpan.org>

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 <jjore@cpan.org>
http://perlmonks.org/?node=diotalevi

Steffen Beyer <stbey@cpan.org>
http://www.engelschall.com/u/sb/download/