Name
---------

Errors::Errors - Module for error/die/exit/abort proceeding.


Synopsis
-------------

use Errors::Errors;
$obj = Errors::Errors->new();

$obj->attach('some'); # Attach sub object for error of type 'some'

$obj->install('onTerm',\&custom);
$obj->install('onError',\&anysub,'some');
$obj->install('onExit',\&leave);
$obj->exit();
sub custom {
my $obj = shift; # 'Errors' object
my $err = shift; # Error number/message (for TERM it has value 'term')
my $name = shift; # 'name' of error (for TERM it has empty value)
# ...blah...blah...
}
sub leave {
my $obj = shift; # 'Errors' object
my $err = shift; # Last error number/message
my $name = shift; # 'name' of error
my $how = shift; # can be: 'exit','die' or 'destroy'
# ...blah...blah...
}
sub anysub {
my $obj = shift; # 'Errors' object
my $err = shift; # Error number/message
my $name = shift; # 'name' of error
if($name =~ m/some/si)
{
$obj->print ("Error in some!");
}
else
{
$obj->print ("Error in ... I don't know :-)!!!");
}
}


Install
---------

As any other 'CPAN' module you just have to do follow simple steps to complete 
installation:

tar -zxvf Errors-1.00.tar.gz
cd Errors-1.00
perl Makefile.PL
make
make test
make install
make clean

After successful installation you can get explore all these pretty stuff :-)


Getting started
---------------------

First question is: Why I have to use Errors module in my Perl program?
In large projects you have to use many libraries, modules and of course you have 
to catch all errors in, also in some cases you need to make some finalize 
procedures at the end of your scripts. To do that you may need to write subs for 
different errors, to write code for interrupts/events/signals but what structure 
you use? None? Huh! You just write code and grubby you program! It's a disgrace. 

This module offer to you and your scripts centralize errors handling and 
proceeding.


How it's works?
----------------------

First you must to create one object for your program:

use Errors::Errors;
$obj = Errors::Errors->new();

This object will contain pointers to your subs that handle occurred errors.
This module can handle follow base errors/events:

exit(onExit), die(onExit), TERM/STOP/PIPE/QUIT(onTerm), ALRM(onTimeout), and 
custom errors(onError).

If you want to do something when your script ends, set your custom sub:

$obj->install('onExit',\&leave);

where \&leave is pointer to your sub 'leave'. When your script ends your sub 

program 'leave' will be executed before the end. That will be happened at the 
end of $obj scope i.e. in DESTROY section of module. Also you can provoke 
execution of 'leave' if you write follow line in program:

$obj->exit($code_error);
or
$obj->die($code_error);

If you want to handle ALRM signal write line like this:

$obj->install('onTimeout',\&custom);
where 'custom' is your custom sub that handle ALRM signal.

To handle TERM/STOP/PIPE/QUIT signals use follow like:

$obj->install('onTerm',\&custom);

where 'custom' is your custom sub that handle listed signals.

If you want to initialize your custom errors write code bellow:

$obj->install('onError',\&anysub);

So when you call method bellow, somewhere in script, you will rise execution of 
'anysub'!

$obj->error($code_error);

Of course all your subs will receive additional parameters so you will be able 
to find reason for errors (and respective error codes). See SYSNOPSIS above.
In single script these methods are strong enough, but if you have a complex 
program with lot of libraries/modules you may want to have a single 'errors' 
object for all your libraries/modules. But how you can handle TERM signal for 
all yours different libraries??? The idea is quite simple, we will still 
continue to use our global (single) object, but we will create "sub objects" for 
all additional libraries/modules! 

To add new sub object do follow:

$obj->attach('some');

This will create sub object called 'some'. To install 'onTerm' signal for this 
sub object (SObject) do follow:

$obj->install('onTerm',\&custom,'some');

Also to catch 'exit' for SObject call:

$obj->install('onExit,',\&leave,'some');

To rise custom error for 'some' SObject, call:

$obj->error($code_error,'some');

To exit…:

$obj->exit($code_error,'some');
… and so on.

Note:
$obj->error($code_error,'some');
will rise error in 'some' sub object
$obj->error($code_error);

will rise error in 'main' object!!! (Think about that like parent object and 
respective children)!

Let imagine that we have a lot of children (SObjects) and one parent object. 
Also let for all these objects we have sub programs that catch exit event. And 
now let our program gone to the end of code, so program must quit and Perl must 
destroy and unload our program!
However Errors module have job to do, it must call all subs that are joined into 
'exit' chain!

See follow block:

foreach $obj call {
| SObject 1 | -> onExit sub
| SObject 2 | -> onExit sub
…
| SObject n | -> onExit sub
| Main object | -> onExit sub
}

All this will be happened with all other events/signals! So you have to check 
reason and decide whether you must do anything into respective sub! See simple 

example:

sub anysub {
my $obj = shift; # 'Errors' object
my $err = shift; # Error number/message
my $name = shift; # 'name' of error
if($name =~ m/some/si)
{
$obj->print ("Error in some!");
}
else
{
$obj->print ("Error in ... I don't know :-)!!!");
}
}

If name is 'some' we can do something, but when the error is somewhere else you 
may want to miss it! You have to decide!

To delete SObject call:

$obj->detach('some');
To uninstall event/signal:
$obj->uninstall('onError','some'); # for some SObject
or
$obj->uninstall('onError'); # for main object

At the end I would like to notice that this module was originally written for 
Web and more correct for WebTools Perl sub system (look at 
http://www.proscriptum.com/)

So to allow Errors object to let know, whether content type is sent use follow 
line:

$obj->content($state); # $state can be '1' - yes and '0' - is not sent yet!

If you want to send default content (HTTP) header use:

$obj->header();

Note: If $obj->content() is '1' then $obj->header() will return immediately 
without printing default header, but if you are not still sent header (or if you 
forgot to tell that to Error object via $obj->content(1) ) then $obj->header() 
will sent default header.

To overwrite default header function use statement bellow:

$obj->install('header',\&your_header_sub);

All this (header and content functions) is needful because if this script is WEB 
based and error occurred you may want to print some text into browser, but if 
you forgot to print content, error will occurred (Internal Error). And vice 
versa: If content is already sent and you print it again then second content 
header will appear in browser :-(

For more information, look at Errors::Errors module.

Author
---------

Julian Lishev,

E-mail: julian@proscriptum.com
URL: http://www.proscriptum.com/