Carp::Always(3pm) User Contributed Perl Documentation Carp::Always(3pm)NAME
Carp::Always - Warns and dies noisily with stack backtraces
SYNOPSIS
use Carp::Always;
makes every "warn()" and "die()" complains loudly in the calling package and elsewhere. More often used on the command line:
perl -MCarp::Always script.pl
DESCRIPTION
This module is meant as a debugging aid. It can be used to make a script complain loudly with stack backtraces when warn()ing or die()ing.
Here are how stack backtraces produced by this module looks:
# it works for explicit die's and warn's
$ perl -MCarp::Always -e 'sub f { die "arghh" }; sub g { f }; g'
arghh at -e line 1
main::f() called at -e line 1
main::g() called at -e line 1
# it works for interpreter-thrown failures
$ perl -MCarp::Always -w -e 'sub f { $a = shift; @a = @$a };'
-e 'sub g { f(undef) }; g'
Use of uninitialized value in array dereference at -e line 1
main::f('undef') called at -e line 2
main::g() called at -e line 2
In the implementation, the "Carp" module does the heavy work, through "longmess()". The actual implementation sets the signal hooks
$SIG{__WARN__} and $SIG{__DIE__} to emit the stack backtraces.
Oh, by the way, "carp" and "croak" when requiring/using the "Carp" module are also made verbose, behaving like "cluck" and "confess",
respectively.
EXPORT
Nothing at all is exported.
ACKNOWLEDGMENTS
This module was born as a reaction to a release of Acme::JavaTrace by Sebastien Aperghis-Tramoni. Sebastien also has a newer module called
Devel::SimpleTrace with the same code and fewer flame comments on docs. The pruning of the uselessly long docs of this module were prodded
by Michael Schwern.
Schwern and others told me "the module name stinked" - it was called "Carp::Indeed". After thinking long and not getting nowhere, I went
with nuffin's suggestion and now it is called "Carp::Always". "Carp::Indeed" which is now deprecate lives in its own distribution (which
won't go anywhere but will stay there as a redirection to this module).
SEE ALSO
o Carp
o Acme::JavaTrace and Devel::SimpleTrace
o Carp::Always::Color
o Carp::Source::Always
Please report bugs via CPAN RT http://rt.cpan.org/NoAuth/Bugs.html?Dist=Carp-Always.
BUGS
Every (un)deserving module has its own pet bugs.
o This module does not play well with other modules which fusses around with "warn", "die", $SIG{'__WARN__'}, $SIG{'__DIE__'}.
o Test scripts are good. I should write more of these.
o I don't know if this module name is still a bug as it was at the time of "Carp::Indeed".
AUTHOR
Adriano Ferreira, <ferreira@cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2005-2012 by Adriano R. Ferreira
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl v5.14.2 2012-04-18 Carp::Always(3pm)
Check Out this Related Man Page
Carp::Clan(3) User Contributed Perl Documentation Carp::Clan(3)NAME
Carp::Clan - Report errors from perspective of caller of a "clan" of modules
SYNOPSIS
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!";
use Carp::Clan;
confess "This is how we got here!";
DESCRIPTION
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.
Forcing a Stack Trace
As a debugging aid, you can force ""Carp::Clan"" to treat a "croak" as a "confess" and a "carp" as a "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 "importing" the non-existent symbol 'verbose', or by setting the global variable "$Carp::Clan::Verbose"
to a true value.
You would typically enable it by saying
use Carp::Clan qw(verbose);
Note that you can both specify a "family pattern" and the string "verbose" inside the ""qw()"" term (or argument list) of the "use"
statement, but consider that a pattern of packages to skip is pointless when "verbose" causes a full stack trace anyway.
BUGS
The ""Carp::Clan"" routines don't handle exception objects currently. If called with a first argument that is a reference, they simply
call ""die()"" or ""warn()"", as appropriate.
perl v5.16.2 2009-10-24 Carp::Clan(3)