Plugins::API - Inter-plugin callback API
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);
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.
Plugins::API objects are created with the
new() method so that will be documented first:
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:
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:
If there are handlers for this callback only call the first one on the list.
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.
If there are multiple handlers for this callback, call them all in sequence and return a flattened list of all the return values.
When invoked, return an array whose elements are references to arrays which are the return values from each of the handlers for this callback.
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 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 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
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.
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.
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
Plugins::API has an
AUTOLOAD function that hands off to
invoke(). Thus all callbacks look like they're methods for Plugins::API.
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.
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:
See the code for SyslogScan::Daemon::SpamDetector.
Scalar::Util::weaken() on object referneces and on
$plugins so that it will not cause reference loops.
Since Plugins::API uses
AUTOLOAD so that you can say
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:
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.
Copyright (C) 2006, David Muir Sharnoff <email@example.com>. This module may be used and redistributed on the same terms as Perl itself.