NAME
     Plugins::API - Inter-plugin callback API

SYNOPSIS
     use Plugins::API;

     my $api = new Plugins::API;

     $api->api( methodname1 => \%options1, methodname2 => \%options2, ... );

     $api->plugins ($plugins_object);

     @handlers = $api->handlers;

     $api->invoke('methodname', @args);

     $api->autoregister($self);

     $api->register($self, [\%options], methodname1 => \&method1, methodname2 => \&method2, ...)

     $api->disable('ClassName');
     $api->disable($object);

DESCRIPTION
    Plugins::API provides a framework for modules to rendevous with each
    other at runtime. It's designed to work with the Plugins module but it
    does not depend upon Plugins and could be used without it.

    The basic idea is that you describe a invocation interface with the
    "api()" method and then you register methods for later callback. A
    method callback requires an object (unless it's a class method) and when
    you register a method, Plugins::API keeps a reference to the object for
    use when making the callback.

    A registered method is called a *handler* in the rest of this document.

METHODS
    Plugins::API objects are created with the "new()" method so that will be
    documented first:

    new([\%options,] [@api])
        Options for "new()" are passed as a reference to a hash. It's
        optional. Also option is an interface specification like what is
        passed to the "api()" method (below).

        The options supported are:

        autoregister => $self
                       Automaticlly register class methods (see
                       "autoregister()" below).

        plugins => $plugins
                       Just like calling "plugins()" (below).

    api(%interface)
        The "api()" call creates the published interfaces that Plugins::API
        users use to invoke each other.

        Pass in key/value pairs. The key is the interface name and the value
        is a refernece to a hash of options for that callback. The supported
        options are:

        first_only => 1
            If there are handlers for this callback only call the first one
            on the list.

        first_defined => 1
            If there are multiple handlers for this callback, call them in
            sequence until one of them returns a value that is not undef.
            This only works in scalar context.

        combine_returns => 1
            If there are multiple handlers for this callback, call them all
            in sequence and return a flattened list of all the return
            values.

        array_returns => 1
            When invoked, return an array whose elements are references to
            arrays which are the return values from each of the handlers for
            this callback.

        exit_test => \&test_function
            After each call to a handler for this callback, call the
            test_function to see if we should stop invoking more handlers:

             ($quit_if_true, @return_value) = test_function(
                    \@last_handler_return, 
                    \@array_of_handler_returns,
                    \@flattend_array_of_handler_returns,
                    wantarray)

    autoregister($self)
        Autoregister will compare the methods of $self to the callbacks
        defined by "api()" and register $self's methods as handlers if any
        of $self's methods have the same name as a callback.

    register($self, [\%options,] %handlers)
        Register binds methods to the interface. Pass in callback names as
        keys and code references as values. It is not required that the API
        method name was not previously defined.

        If $self is undefined then the code references will be called as
        functions rather than methods.

        The options supported by "register()" are:

        first     Normally new handlers are added to the end of the list of
                  handlers for the callback. With this option, the handlers
                  will be added to the beginning of the list.

        replace   Normally new handlers are added to the end of the list of
                  handlers for the callback. With this option, the handlers
                  will replace the current list.

    invoke($callback, [@args)
        This causes all of the handlers for $callback to be called in turn
        and the return value from the last handler to be returned. Some of
        this behavior can be changed with calls to "api()".

        Plugins::API has an "AUTOLOAD" function that hands off to
        "invoke()". Thus all callbacks look like they're methods for
        Plugins::API.

    disable($object) =item disable('CLASS')
        Handlers can be turned off with "disable()". Turning off a class
        disables all objects in the class. There is no re-enable function at
        this time.

    plugins($plugins)
        Plugins::API works with the Plugins module. If a Pluginss object has
        been registered with "plugins()", then any "invoke()" of a callback
        also do a "Plugins::invoke()" on the $plugins object.

    handlers($callback)
        This returns a list of the un-disabled handlers for a callback.
        Handlers are objects in the Plugins::API::Handler class. They
        support the following methods:

        call(@args)
            Call the function or method with @args.

        object()
            Return the object or class that the function is a method for.
            Returns an empty list if there is no object or class.

        method()
            Returns a code reference for the function.

EXAMPLES
    See the code for SyslogScan::Daemon::SpamDetector.

MEMORY LEAKS
    Plugins::API uses "Scalar::Util::weaken()" on object referneces and on
    $plugins so that it will not cause reference loops.

RESERVED METHOD NAMES
    Since Plugins::API uses "AUTOLOAD" so that you can say

     $api->foobar()

    where "foobar" is a callback, you need to avoid naming your callbacks
    the same as Plugins::API methods. In addition to the methods documented
    above, please don't have callbacks named:

     callhandlers()
     newhandler()

SEE ALSO
    Plugins

THANK THE AUTHOR
    If you find this module useful and wish to show your appreciation to the
    author, please give me a Request-For-Quote on your next high-speed
    internet pipe order. I have good pricing for T1s, T3s, OC3s etc.

LICENSE
    Copyright (C) 2006, David Muir Sharnoff <muir@idiom.com>. This module
    may be used and redistributed on the same terms as Perl itself.