1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Carp::Clan 3"
132 .TH Carp::Clan 3 "2009-10-24" "perl v5.8.7" "User Contributed Perl Documentation"
134 Carp::Clan \- Report errors from perspective of caller of a "clan" of modules
136 .IX Header "SYNOPSIS"
138 \& carp \- warn of errors (from perspective of caller)
142 \& cluck \- warn of errors with stack backtrace
146 \& croak \- die of errors (from perspective of caller)
150 \& confess \- die of errors with stack backtrace
154 \& use Carp::Clan qw(^MyClan::);
155 \& croak "We're outta here!";
160 \& confess "This is how we got here!";
163 .IX Header "DESCRIPTION"
164 This module is based on "\f(CW\*(C`Carp.pm\*(C'\fR\*(L" from Perl 5.005_03. It has been
165 modified to skip all package names matching the pattern given in
166 the \*(R"use\*(L" statement inside the \*(R"\f(CW\*(C`qw()\*(C'\fR" term (or argument list).
168 Suppose you have a family of modules or classes named \*(L"Pack::A\*(R",
169 \&\*(L"Pack::B\*(R" and so on, and each of them uses "\f(CW\*(C`Carp::Clan qw(^Pack::);\*(C'\fR"
170 (or at least the one in which the error or warning gets raised).
172 Thus when for example your script \*(L"tool.pl\*(R" calls module \*(L"Pack::A\*(R",
173 and module \*(L"Pack::A\*(R" calls module \*(L"Pack::B\*(R", an exception raised in
174 module \*(L"Pack::B\*(R" will appear to have originated in \*(L"tool.pl\*(R" where
175 \&\*(L"Pack::A\*(R" was called, and not in \*(L"Pack::A\*(R" where \*(L"Pack::B\*(R" was called,
176 as the unmodified "\f(CW\*(C`Carp.pm\*(C'\fR" would try to make you believe \f(CW\*(C`:\-)\*(C'\fR.
178 This works similarly if \*(L"Pack::B\*(R" calls \*(L"Pack::C\*(R" where the
179 exception is raised, etcetera.
181 In other words, this blames all errors in the "\f(CW\*(C`Pack::*\*(C'\fR" modules
182 on the user of these modules, i.e., on you. \f(CW\*(C`;\-)\*(C'\fR
184 The skipping of a clan (or family) of packages according to a pattern
185 describing its members is necessary in cases where these modules are
186 not classes derived from each other (and thus when examining \f(CW@ISA\fR
187 \&\- as in the original "\f(CW\*(C`Carp.pm\*(C'\fR" module \- doesn't help).
189 The purpose and advantage of this is that a \*(L"clan\*(R" of modules can work
190 together (and call each other) and throw exceptions at various depths
191 down the calling hierarchy and still appear as a monolithic block (as
192 though they were a single module) from the perspective of the caller.
194 In case you just want to ward off all error messages from the module
195 in which you "\f(CW\*(C`use Carp::Clan\*(C'\fR\*(L", i.e., if you want to make all error
196 messages or warnings to appear to originate from where your module
197 was called (this is what you usually used to \*(R"\f(CW\*(C`use Carp;\*(C'\fR" for \f(CW\*(C`;\-)\*(C'\fR),
198 instead of in your module itself (which is what you can do with a
199 \&\*(L"die\*(R" or \*(L"warn\*(R" anyway), you do not need to provide a pattern,
200 the module will automatically provide the correct one for you.
202 I.e., just "\f(CW\*(C`use Carp::Clan;\*(C'\fR\*(L" without any arguments and call \*(R"carp\*(L"
203 or \*(R"croak" as appropriate, and they will automatically defend your
204 module against all blames!
206 In other words, a pattern is only necessary if you want to make
207 several modules (more than one) work together and appear as though
209 .Sh "Forcing a Stack Trace"
210 .IX Subsection "Forcing a Stack Trace"
211 As a debugging aid, you can force "\f(CW\*(C`Carp::Clan\*(C'\fR\*(L" to treat a \*(R"croak\*(L" as
212 a \*(R"confess\*(L" and a \*(R"carp\*(L" as a \*(R"cluck". In other words, force a detailed
213 stack trace to be given. This can be very helpful when trying to
214 understand why, or from where, a warning or error is being generated.
216 This feature is enabled either by \*(L"importing\*(R" the non-existent symbol
217 \&'verbose', or by setting the global variable "\f(CW$Carp::Clan::Verbose\fR"
220 You would typically enable it by saying
223 \& use Carp::Clan qw(verbose);
226 Note that you can both specify a \*(L"family pattern\*(R" and the string \*(L"verbose\*(R"
227 inside the "\f(CW\*(C`qw()\*(C'\fR\*(L" term (or argument list) of the \*(R"use\*(L" statement, but
228 consider that a pattern of packages to skip is pointless when \*(R"verbose"
229 causes a full stack trace anyway.
232 The "\f(CW\*(C`Carp::Clan\*(C'\fR\*(L" routines don't handle exception objects currently.
233 If called with a first argument that is a reference, they simply
234 call \*(R"\f(CW\*(C`die()\*(C'\fR\*(L" or \*(R"\f(CW\*(C`warn()\*(C'\fR", as appropriate.