NAME
Class::Handler - Create Apache-like pseudoclass event handlers
SYNOPSIS
use Class::Handler;
handler http => 'My::Module';
handler http => 'My::OtherModule';
http->dostuff(@args); # Tries My::Module->dostuff,
# then My::OtherModule->dostuff
# if it fails or is not found
nohandler http => 'My::Module'; # Remove My::Module from the
# list of modules to try
nohandler http; # Remove http handler entirely
DESCRIPTION
Overview
This module can be used to create and maintain pseudoclass event
handlers, which are simply special classes which inherit from multiple
modules but provide no methods of their own. These handlers can be used
just like normal classes, with the added benefit that they are able to
decline or partially handle requests, allowing multiple classes to act
on the same data through the same interface.
This serves the dual purpose of acting as both a complete Perl 5 module
as well as a prototype for a proposed Perl 6 feature.
Adding and Using Handlers
To add a handler, you simply use the handler() method which is
automatically exported by this module. handler() takes two arguments,
the first being the name of the handler and the second the name of a
class which should be added to that handler:
handler signal => 'Signal::DoStuff';
This would install a new handler called `signal' which would have one
class, `Signal::DoStuff', in it. You can install multiple handlers at
the same time:
handler exception => 'My::Catch', 'Site::Failsafe';
or as multiple subsequent commands:
handler exception => 'My::Catch';
handler exception => 'Site::Failsafe';
The theory behind these handlers is much like the theory behind Apache
handlers. Whatever the name of the method is that is called on the
pseudoclass, is the name of the method that is called on the actual
classes. For example, assuming this code:
handler http => 'My::HTTP';
handler http => 'LWP::UserAgent';
$FH = http->open("
http://www.yahoo.com");
Then the following sequence of events would occur:
$FH http->open undef
^ | ^
| | |
| Does My::HTTP->open exist? |
| YES/ \NO |
| / \ |
| Try it Does LWP::UserAgent->open exist? |
| / \ ^ YES/ \NO |
| OK/ \UNDEF / / ----------------
------- ------ Try it |
| / \ |
| OK/ \UNDEF |
------------------------- ---------------------
Some highlights:
1. Each class's open() method is tried in turn, since
that is the name of the method called on the handler
2. If undef is returned, the next one in sequence is
tried.
3. If 'OK' (simply meaning 1 or some other true value,
like $FH) is returned, that is propagated out and
returned by the top-level handler.
4. All classes are tried until 'OK' is returned or the
last one is reached.
This allows you to easily chain classes and methods together with a
couple key benefits over an inline `||':
1. Each handler can partially handle the request, but
still return undef, deferring to the next one in line.
2. The handlers can be reordered internally at-will
without the main program having to be redone.
3. Different class open() methods can use internal
rules, such as "only open .com URLs", without
you having to put checks for this all over the
place in the top-level program.
For more details, please see the Perl 6 RFC listed below.
Removing Handlers
In addition to handlers being added, they need to be removed as well.
This is where nohandler() comes in:
nohandler http => 'My::HTTP'; # remove My::HTTP from list
nohandler http; # remove http handler
The first example removes `My::HTTP' from the list of classes used by
the `http' handler. The second syntax removes the `http' handler
entirely, meaning that this call:
$FO = http->open("
http://www.yahoo.com");
will result in the familiar error:
Can't locate object method "open" via package "http"
Currently, there is no way to reorder handlers without removing and then
re-adding them.
Automatic Handler Registration and Removal
Sometimes, you may find that you want a class to automatically register
as a member of a given handler. To do so, you simply need to `use
Class::Handler' in your module and then prefix the package `main::' (or
whatever package you want to affect) to the start of the handler name:
package Custom::Module;
use Class::Handler;
handler 'main::stuff' => 'Custom::Module';
This will make it so that in your main script you can now do this:
use Custom::Module;
stuff->method(@args);
And it will call the Custom::Module->method function as expected.
However, this feature should be used with caution. It borders right on
the edge of scary action-at-a-distance.
REFERENCES
For more details on the complete Perl 6 proposal, please visit
http://dev.perl.org/rfc/101.html. Comments are welcome.
AUTHOR
Copyright (c) 2000, Nathan Wiger <
[email protected]>. All Rights Reserved.
This module is free software; you may copy this under the terms of the
GNU General Public License, or the Artistic License, copies of which
should have accompanied your Perl kit.
