Carp::Clan5.12 man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

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.12.5			  2009-10-24			 Carp::Clan(3)
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net