GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CARP::CLAN (3)

.ds Aq ’

NAME

Carp::Clan - Report errors from perspective of caller of a "clan" of modules

CONTENTS

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 "Were 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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CARP::CLAN (3) 2009-10-24

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.