NAME

GT::Plugins - a plugin interface for Gossamer Threads products.

SYNOPSIS

    use GT::Plugins;
    $PLUGIN = GT::Plugins->new('/path/to/plugin/dir');
    $PLUGIN->dispatch(hook_name => \&code_ref => @args);
    $PLUGIN->dispatch_method(hook_name => $self => method => @args);

Old style, now deprecated in favour of the object approach above:

    use GT::Plugins;
    GT::Plugins->dispatch('/path/to/plugin/dir', hook_name => \&code_ref => @args);
    GT::Plugins->dispatch_method('/path/to/plugin/dir', hook_name => $self => method => @args);

DESCRIPTION

The plugin module supports two modes of use. The first mode involves creating and using a GT::Plugins object upon which plugin dispatch methods may be called to provide hooks. The second does not use the object, but instead uses class methods with an extra argument of the plugin path preceding the other ->dispatch() arguments.

Of the two approaches, the object approach is recommended as it is a) faster, and b) requires much less value duplication as the plugin directory needs to be specified only once. The old, class-method-based plugin interface should be considered deprecated, and all new code should attempt to use the object-based system.

A dispatch with each of the two interfaces work as follows, with differences in interfaces as noted:

  1. Loads the plugin config file. The actual file access and evaluation will be cached, but a small amount of extra overhead is required on each dispatch. This only applies to the deprecated class-method dispatch interface - the preferred object interface loads the configuration file only once.

  2. Runs any 'PRE' hooks registered in the config file. When using ->dispatch(), each hook is passed the @args arguments passed into ->dispatch. When using ->dispatch_method(), both the object ($self) and arguments (@args) are passed to the hook.

    Each plugin hook then has the ability to abort further plugins if desired by calling $PLUGIN->action(STOP) (or GT::Plugins->action(STOP) for the non-OO interface). STOP is exported by default from the GT::Plugins module. Performing a STOP will skip both any further 'PRE' hooks and the original function/method, and will use the hook's return value instead of the real code's return value.

    The current behaviour of 'PRE' hooks ignores the return value of any 'PRE' hook that does not perform a STOP, however this behaviour may change to use the return value as the arguments to the next PRE hook or actual code called. As such, it is strongly recommended to return @_ from any 'PRE' hooks.

  3. Assuming ->action(STOP) has not been called, the method (->dispatch_method) or code reference (->dispatch) will be called, and its return value stored.

  4. Any registered 'POST' hooks registered in the config file will be run. When using ->dispatch(), the list-context return value of the main code run (or, if a 'PRE' hook called STOP, the return value of that 'PRE' hook) will be passed in. When using ->dispatch_method(), the object is additionally passed in as the first argument.

    The list returned by the 'POST' hook will be used as arguments for any subsequent 'POST' hooks and as the final result returned by the ->dispatch() or ->dispatch_method() call. There is one exception to this - for ->dispatch_method() 'POST' hooks, if the first argument of the return value is the object, it will be removed; this is done to prevent a build-up of excess objects at the beginning of the 'POST' hook arguments/return values due to 'POST' hooks simply returning @_ unaltered.

  5. The return value of the final 'POST' hook, or, when no post hooks are configured, of the actual code, is returned as the result of the ->dispatch() call.

SEE ALSO

Also included as part of the plugin system are some modules for web based tools to manage plugins:

the GT::Plugins::Manager manpage - Add, remove and edit plugin files.

the GT::Plugins::Wizard manpage - Create shell plugins.

the GT::Plugins::Installer manpage - Used in installing plugins.

COPYRIGHT

Copyright (c) 2005 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

VERSION

Revision: $Id: Plugins.pm,v 1.55 2005/04/01 00:16:51 brewt Exp $