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: [email protected]
URL: http://www.proscriptum.com/

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.