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 <nate@sun.com>. 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.