Class-Handler - README

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:

Each class's open() method is tried in turn, since that is the name of the method called on the handler
If undef is returned, the next one in sequence is tried.
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.
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 `||':

Each handler can partially handle the request, but still return undef, deferring to the next one in line.
The handlers can be reordered internally at-will without the main program having to be redone.
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

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.