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.


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/question s/etc. Hell, drop me a line to let
	me know that you're using the module and that it's made your life
	easier. :-)