In perl.git, the branch blead has been updated
<http://perl5.git.perl.org/perl.git/commitdiff/b60d6605411da17cfde0ca1b95ab0950a1ba84f5?hp=75a012fe81458190a6875571a0732fe9233952cf>
- Log -----------------------------------------------------------------
commit b60d6605411da17cfde0ca1b95ab0950a1ba84f5
Author: Alan Grover <awgro...@gmail.com>
Date: Mon Aug 24 09:38:31 2009 +0200
[perl #68708] Add "CARP_NOT" section to Carp's POD
I Carp's POD, @CARP_NOT is mentioned but it's use is not clear. It is
particularly not clear that @CARP_NOT is a variable in _your_ package.
I propose adding a section to the POD, before the %Carp::Internal
section.
-----------------------------------------------------------------------
Summary of changes:
lib/Carp.pm | 39 +++++++++++++++++++++++++++++++++++++++
1 files changed, 39 insertions(+), 0 deletions(-)
diff --git a/lib/Carp.pm b/lib/Carp.pm
index f541c64..0c69860 100644
--- a/lib/Carp.pm
+++ b/lib/Carp.pm
@@ -431,6 +431,45 @@ is implemented internally.
Defaults to C<0>.
+=head2 @CARP_NOT
+
+This variable, I<in your package>, says which packages are I<not> to be
+considered as the location of an error. The C<carp()> and C<cluck()>
+functions will skip over callers when reporting where an error occurred.
+
+NB: This variable must be in the package's symbol table, thus:
+
+ # These work
+ our @CARP_NOT; # file scope
+ use vars qw(@CARP_NOT); # package scope
+ @My::Package::CARP_NOT = ... ; # explicit package variable
+
+ # These don't work
+ sub xyz { ... @CARP_NOT = ... } # w/o declarations above
+ my @CARP_NOT; # even at top-level
+
+Example of use:
+
+ package My::Carping::Package;
+ use Carp;
+ our @CARP_NOT;
+ sub bar { .... or _error('Wrong input') }
+ sub _error {
+ # temporary control of where'ness, __PACKAGE__ is implicit
+ local @CARP_NOT = qw(My::Friendly::Caller);
+ carp(@_)
+ }
+
+This would make C<Carp> report the error as coming from a caller not
+in C<My::Carping::Package>, nor from C<My::Friendly::Caller>.
+
+Also read the L</"Description"> section above, about how C<Carp> decides
+where the error is reported from.
+
+Use C<@CARP_NOT>, instead of C<$Carp::CarpLevel>.
+
+Overrides C<Carp>'s use of C<@ISA>.
+
=head2 %Carp::Internal
This says what packages are internal to Perl. C<Carp> will never
--
Perl5 Master Repository
