NAME

Carp::Notify - Loudly complain in lots of places when things break badly

AUTHOR

Jim Thomason thomasoniii@yahoo.com

SYNOPSIS

Use it in place of die or croak, or warn or carp.

#with Carp;
use Carp;
if ($something_a_little_bad) { carp("Oh no, a minor error!")};
if ($something_bad) { croak ("Oh no an error!")};


#with Carp::Notify;
use Carp::Notify;
if (something_a_little_bad) {notify("Oh no, a minor error!")};
if ($something_bad) { explode ("Oh no an error!")};

REQUIRES

Perl 5.004, Socket (for emailing)

DESCRIPTION

Carp::Notify is an error reporting module designed for applications that are running unsupervised (a CGI script, for example, or a cron job). If a program has an explosion, it terminates (same as die or croak or exit, depending on preference) and then emails someone with useful information about what caused the problem. Said information can also be logged to a file. If you want the program to tell you something about an error that's non fatal (disk size approaching full, but not quite there, for example), then you can have it notify you of the error but not terminate the program.

Defaults are set up within the module, but they can be overridden once the module is used, or as individual explosions take place.

BUILT IN STUFF

Using the module

use Carp::Notify;

will require and import the module, same as always. What you decide to import it with is up to you. You can choose to import additional functions into your namespace, set up new default values, or give it a list of variables to store.

Carp::Notify will always export the explode function and the notify function. Carp always exports carp, croak, and confess, so I figure that I can get away with always exporting explode and notify. Nyaah.

Be sure that you set your default variables before using it!

make_storable

if this is an import argument, it will export the make_storable function into your namespace. See make_storable, below.

make_unstorable

If this is an import argument, it will export the make_unstorable function into your namespce. See make_unstorable, below.

croak

If this is an import argument, it will override the croak function in your namespace and alias it to explode. That way you can switch all of your croaks to explodes by just changing how you use your module, and not all of your code.

carp

If this is an import argument, it will override the carp function in your namespace and alias it to notify. That way you can switch all of your carps to notifies by just changing which module you use, and not all of your code.

(log_it|email_it|store_vars|stack_trace|store_env|email|log_file|smtp|die_to_stdout|die_quietly|death_message)

Example:

use Carp::Notify (
	"log_it" => 1,
	"email_it => 0,
	"email" => 'thomasoniii@yahoo.com'
);

These are hash keys that allow you to override the Carp::Notify's module defaults. These can also all be overloaded explicitly in your explode() calls, but this allows a global modification.

log_it

Flag that tells Carp::Notify whether or not to log the explosions to the log file

log_file

Overrides the default log file. This file will be opened in append mode and the error message will be stored in it, if log_it is true.

If you'd like, you can give log_file a reference to a glob that is an open filehandle instead of a scalar containing the log name. This is most useful if you want to redirect your error log to STDERR or to a pipe to a program.

Be sure to use globrefs only explicitly in your call to explode, or to wrap the definition of the filehandle in a begin block before using the module. Otherwise, you'll be trying to log to a non-existent file handle and consequently won't log anything. That'd be bad.

email_it

Flag that tells Carp::Notify whether or not to email a user to let them know something broke

email

Overrides the default email address. This is whoever the error message will get emailed to if email_it is true.

smtp

Allows you to set a new SMTP relay for emailing

store_vars

Flag that tells Carp::Notify whether or not to list any storable variables in the error message. See storable variables, below.

stack_trace

Flag that tells Carp::Notify whether or not to do a call stack trace of every function call leading up to the explosion.

store_env

Flag that tells Carp::Notify whether or not to store the environment variables in the error message.

die_to_stdout

Allows you to terminate your program by displaying an error to STDOUT, not to STDERR.

die_quietly

Terminates your program without displaying any message to STDOUT or STDERR. =back

death_message

The message that is printed to the appropriate location, unless we're dying quietly. =back

(storable variable)

A variable name within single quotes will tell the Carp::Notify module that you want to report the current value of that variable when the explosion occurs. Carp::Notify will report an error if you try to store a value that is undefined, if you had accidentally typed something in single quotes, for instance. For example,

use Carp::Notify ('$scalar', '@array');

$scalar = "some_value";
@array = qw(val1 val2 val3);

explode("An error!");

will write out the values "$scalar : some_value" and "@array : val1 val2 val3" to the log file.

This can also only be used to store global variables. Dynamic or lexical variables need to be explicitly placed in explode() calls.

You can store variables from other packages if you'd like:

use Carp::Notify ('$other_package::scalar', '@some::nested::package::array');

Only global scalars, arrays, and hashes may be stored.

make_storable

Makes whatever variables it's given storable. See storable variables, above.

make_storable('$new_scalar', '@different_array');

make_unstorable

Stops whatever variables it's given from being stored. See storable variables, above.

make_unstorable('$scalar', '@different_array');

explode

explode is where the magic is. It's exported into the calling package by default (no point in using this module if you're not gonna use this function, after all).

You can override your default values here (see Using the module above), if you'd like, and otherwise specify as many error messages as you'd like to show up in your logs.

#override who the mail's going to, and the log file.
explode("email" => "thomasoniii@yahoo.com", log_file => "/home/jim/jim_explosions.log", "A terrible error: $!");

#Same thing, but with a globref to the same file
open (LOG, ">>/home/jim/jim_explosions.log");
explode("email" => "thomasoniii@yahoo.com", log_file => \*LOG, "A terrible error: $!");


#don't log.
explode ("log_it" => 0, "A terrible error: $!");

#keep the defaults
explode("A terrible error: $!", "And DBI said:  $DBI::errstr");

notify

notify is to explode as warn is to die. It does everything exactly the same way, but it won't terminate your program the way that an explode would.

FAQ

So what's the point of this thing?

It's for programs that need to keep running and that need to be fixed quickly when they break.

But I like Carp

I like Carp too. :)

This isn't designed to replace Carp, it serves a different purpose. Carp will only tell you the line on which your error occurred. While this i helpful, it doesn't get your program running quicker and it doesn't help you to find an error that you're not aware of in a CGI script that you think is running perfectly.

Carp::Notify tells you ASAP when your program breaks, so you can inspect and correct it quicker. You're going to have less downtime and the end users will be happier with your program because there will be fewer bugs since you ironed them out quicker.

Wow. That was a real run-on sentence

Yeah, I know. That's why I'm a programmer and not an author. :)

What about CGI::Carp?

That's a bit of a gray area. Obviously, by its name, CGI::Carp seems designed for CGI scripts, whereas Carp::Notify is more obvious for anything (cron jobs, command line utilities, as well as CGIs).

Carp::Notify also can store more information with less interaction from the programmer. Plus it will email you, if you'd like to let you know that something bad happened.

As I understand it, CGI::Carp is a subset feature-wise of Carp::Notify. If CGI::Carp is working fine for you, great continue to use it. If you want more flexible error notification, then try out Carp::Notify.

But I can send email with CGI::Carp by opening up a pipe to send mail and using that as my error log. What do you have to say about that?

Good for you. I can too. But most people that I've interacted with either don't have the know-how to do that or just plain wouldn't have thought of it. Besides, it's still more of a hassle than just using Carp::Notify.

Why are your stored variables kept in an array instead of a hash? Hashes are quicker to delete from, after all

While it is definitely true that variables can be unstored a little quicker in a hash, I figured that stored variables will only rarely be unstored later. Arrays are quicker for storing and accessing the items later. I'll live with the slight performance hit for the rarer case.

Can I store variables that are in another package from the one that called Carp::Notify?

You betcha. Just prepend the classpath to the variable name, same as you always have to to access variables not in your name space. If the variable is already in your name space (you imported it), you don't need the classpath since explode will just pick it up within your own namespace.

Can I store local or my variables?

Not in the use statement, but you can in an explicit explode.

Are there any bugs I should be aware of?

Only if you're annoying. If you import explode into your package, then subclass it and export explode back out it won't correctly pick up your stored variables unless you fully qualified them with the class path ($package::variable instead of just $variable)

Solution? Don't re-export Carp::Notify. But you already knew that you should juse re-use it in your subclass, right?

Could I see some more examples?

Sure, that's the next section.

Okay, you've convinced me. What other nifty modules have you distributed?

Mail::Bulkmail and Text::Flowchart.

Was that a shameless plug?

Why yes, it was.

Examples

#store $data, do email the errors, and alias croak => explode
use Carp::Notify ('$data', 'email_it' => 1, "croak");

#email it to a different address, and don't log it.
use Carp::Notify ("email" => 'thomasoniii@yahoo.com', 'log_it' => 0);

#die with an explosion.
explode("Ye gods!  An error!");

#explode, but do it quietly.
explode ("die_quietly" => 1, "Ye gods!  An error!");

#notify someone of a problem, but keep the program running
notify ("Ye gods!  A little error!");

Version History

v1.00 - August 10, 2000 - Changed the name from Explode to Carp::Notify. It's more descriptive and I don't create a new namespace.

v1.00 FC1 - June 9, 2000 - First publically available version.

COPYRIGHT (again)

Copyright (c) 2000 James A Thomason III (thomasoniii@yahoo.com). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

CONTACT INFO

So you don't have to scroll all the way back to the top, I'm Jim Thomason (thomasoniii@yahoo.com) and feedback is appreciated. Bug reports/suggestions/questions/etc. Hell, drop me a line to let me know that you're using the module and that it's made your life easier. :-)

cpanm Carp::Notify

perl -MCPAN -e shell
install Carp::Notify