.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\" ========================================================================
.de Sh \" Subsection heading
.de Sp \" Vertical space (when we can't use .PP)
.de Vb \" Begin verbatim text
.de Ve \" End verbatim text
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
. tm Index:\\$1\t\\n%\t"\\$2"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. \" simple accents for nroff and troff
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
.\" ========================================================================
.TH CLAN 1 "2002-09-28" "perl v5.8.0" "User Contributed Perl Documentation"
Carp::Clan \- Report errors from perspective of caller of a "clan" of modules
\& carp - warn of errors (from perspective of caller)
\& cluck - warn of errors with stack backtrace
\& croak - die of errors (from perspective of caller)
\& confess - die of errors with stack backtrace
\& use Carp::Clan qw(^MyClan::);
\& croak "We're outta here!";
\& confess "This is how we got here!";
This module is based on "\f(CW\*(C`Carp.pm\*(C'\fR\*(L" from Perl 5.005_03. It has been
modified to skip all package names matching the pattern given in
the \*(R"use\*(L" statement inside the \*(R"\f(CW\*(C`qw()\*(C'\fR" term (or argument list).
Suppose you have a family of modules or classes named \*(L"Pack::A\*(R",
\&\*(L"Pack::B\*(R" and so on, and each of them uses "\f(CW\*(C`Carp::Clan qw(^Pack::);\*(C'\fR"
(or at least the one in which the error or warning gets raised).
Thus when for example your script \*(L"tool.pl\*(R" calls module \*(L"Pack::A\*(R",
and module \*(L"Pack::A\*(R" calls module \*(L"Pack::B\*(R", an exception raised in
module \*(L"Pack::B\*(R" will appear to have originated in \*(L"tool.pl\*(R" where
\&\*(L"Pack::A\*(R" was called, and not in \*(L"Pack::A\*(R" where \*(L"Pack::B\*(R" was called,
as the unmodified "\f(CW\*(C`Carp.pm\*(C'\fR" would try to make you believe \f(CW\*(C`:\-)\*(C'\fR.
This works similarly if \*(L"Pack::B\*(R" calls \*(L"Pack::C\*(R" where the
exception is raised, etcetera.
In other words, this blames all errors in the "\f(CW\*(C`Pack::*\*(C'\fR" modules
on the user of these modules, i.e., on you. \f(CW\*(C`;\-)\*(C'\fR
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 \f(CW@ISA\fR
(as in the original "\f(CW\*(C`Carp.pm\*(C'\fR" module) doesn't help).
The purpose and advantage of this is that a \*(L"clan\*(R" 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 "\f(CW\*(C`use Carp::Clan\*(C'\fR\*(L", 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 \*(R"\f(CW\*(C`use Carp;\*(C'\fR" for \f(CW\*(C`;\-)\*(C'\fR),
instead of in your module itself (which is what you can do with a
\&\*(L"die\*(R" or \*(L"warn\*(R" anyway), you do not need to provide a pattern,
the module will automatically provide the correct one for you.
I.e., just "\f(CW\*(C`use Carp::Clan;\*(C'\fR\*(L" without any arguments and call \*(R"carp\*(L"
or \*(R"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
.Sh "Forcing a Stack Trace"
.IX Subsection "Forcing a Stack Trace"
As a debugging aid, you can force "\f(CW\*(C`Carp::Clan\*(C'\fR\*(L" to treat a \*(R"croak\*(L" as
a \*(R"confess\*(L" and a \*(R"carp\*(L" as a \*(R"cluck". In other words, force a detailed
stack trace to be given. This can be very helpful when trying to
understand why, or from where, a warning or error is being generated.
This feature is enabled either by \*(L"importing\*(R" the non-existent symbol
\&'verbose', or by setting the global variable "\f(CW$Carp::Clan::Verbose\fR"
You would typically enable it by saying
\& use Carp::Clan qw(verbose);
Note that you can both specify a \*(L"family pattern\*(R" and the string \*(L"verbose\*(R"
inside the "\f(CW\*(C`qw()\*(C'\fR\*(L" term (or argument list) of the \*(R"use\*(L" statement, but
consider that a pattern of packages to skip is pointless when \*(R"verbose"
causes a full stack trace anyway.
The "\f(CW\*(C`Carp::Clan\*(C'\fR\*(L" routines don't handle exception objects currently.
If called with a first argument that is a reference, they simply
call \*(R"\f(CW\*(C`die()\*(C'\fR\*(L" or \*(R"\f(CW\*(C`warn()\*(C'\fR", as appropriate.
projects / OpenSPARC-T2-DV / blob