NAME

Carp::Indeed - Warns and dies noisily with stack backtraces

SYNOPSIS

use Carp::Indeed;

makes every warn() and die() complains loudly in the calling package and elsewhere. More often used on the command line:

perl -MCarp::Indeed 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.

This is no substitute for carefully written code with informative error messages. It may speed the development by giving fast feedback to the programmer to understand what Perl was doing when an error was found. The long mess produced does not make much sense to any user besides the developer (and neither to her/him after a little lapse of time). Printing stack traces all around is usually felt as a lousy programming style by a programmer who did not have the time or guts to write decent code. That's why Perl mature code usually employs the Carp module to tell of errors from the perspective of the caller: if an error was found, it should belong to the caller as the library code was made bullet-proof. (That's a summary of what the author thinks about "the Java paradigm to print stack traces").

Here is how a stack backtrace produced by Carp::Indeed looks for a fictional script:

Exception: event not implemented at workshop/events.pl line 26
        MyEvents::generic_event_handler() called at workshop/events.pl line 11
        MyEvents::__ANON__() called at workshop/events.pl line 22
        MyEvents::dispatch_event() called at workshop/events.pl line 17
        MyEvents::call_event() called at workshop/events.pl line 30

[after the example in Acme::JavaTrace]

In the implementation, the Carp module was used. Carp is a Perl module as old as Perl 5 (don't believe me, ask corelist). It has an option to print errors (from the perspective of caller) with stack backtrace. With a few lines of codes, this module illustrates how to make warn() and die() noisy as well.

This is done by overriding the builtin functions warn and die globally. Just as perlsub told us not to do lightly.

EXPORT

This module exports globally its own versions of warn and die.

AN ASIDE

If you take a look at some dictionary (I have used

http://dictionary.reference.com/search?q=carp

for no good reason), you find out that carp means

To find fault in a disagreeable way; complain fretfully.

To croak is no better:

To mutter discontentedly; grumble.
_Slang._ To die.

And then there is cluck and confess:

cluck
To utter the characteristic sound of a hen.

confess
To admit or acknowledge something damaging or inconvenient to oneself

These are the terminology introduced by the symbols exportable by Carp. And then you realize you are being annoying when carping, croaking, warning, dying, clucking, confessing. So don't do it all the time, nobody will tolerate and you will be all alone writing code that makes you boring (for others and yourself).

RANT

This is a rant on the Acme::JavaTrace module where the author (Sébastien Aperghis-Tramoni - saper) gave us some pearls of wisdom like

<buzzword>This module tries to improves the Perl programmer 
experience by porting the Java paradigm to print stack traces, 
which is more professional than Perl's way. </buzzword>

and

Please note that even the professionnal indentation present 
in the Java environment is included in the trace. 

It was probably meant as a joke. He even released a new module called Devel::SimpleTrace with the same code and fewer flame comments on docs.

The upsides of all this are:

• could it be a good idea to support another formats for stack backtraces? Java programmers and others could feel more comfortable in addition to the liberating experience of a cooler programming language.

• maybe it is already time to equip Carp with additional support for alternate ways of showing and dumping arguments.

• it may be time as well to add Carp support to handle exception objects

• at such occasions, one finds that more research into the core Perl library worths a lot

• sometimes one realizes that knowing Perl is like doing maths. You don't prove anything by showing that two cases satisfy the proposed solution. In the same vein, just because you didn't find a Perl module with the functionality you need, it does not mean it was not written yet.

• documentation in stupid modules can always be too long

BLAME

Who ever writes bold statements about one's favourite programming language.

SEE ALSO

• Carp

• Java::AcmeTrace, by saper

• Devel::SimpleTrace, by saper

Please report bugs via CPAN RT http://rt.cpan.org/NoAuth/Bugs.html?Dist=Carp-Indeed.

BUGS

Every (un)deserving module has its own pet bugs.

• When this module is in effect, the use of carp and croak should be verbose too. This is not working yet.

• This module does not play well with other modules which fusses around with warn, die, $SIG{'__WARN__'}, $SIG{'__DIE__' }.

• Test scripts are good. I should write more of these.

• A hord of bugs is waiting me after the CPAN release: almost no caution was taken to assure the code works faithfully. And they are fond of rising in the wild. But that is not too worrisome and complies with the Klingon Programmer's Code of Honour http://www.klingon.org/resources/klingon_code.html

AUTHOR

Adriano Ferreira, <ferreira@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Adriano R. Ferreira

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Carp::Indeed

perl -MCPAN -e shell
install Carp::Indeed