Index

NAME
SYNOPSIS
DESCRIPTION
CLASS METHODS
- new
INSTANCE METHODS
- Plugin Access
- Hook Related
MISCELLANEOUS
SEE ALSO
VERSION
AUTHOR
COPYRIGHT AND LICENSE

NAME

Newcomen::Plugins - Manages the Newcomen plugins.

SYNOPSIS

use Newcomen::Plugins;

my $plugins = Newcomen::Plugins -> new ();

# Get a single plugin instance:
my $plugin = $plugins -> plugin ($plugin_name);

# Run a hook:
$plugins -> run_hooks ($hook_name);

DESCRIPTION

This is a container that provides access to the plugin instances. On first access, the plugins that are enabled (see the configuration section in Newcomen::Manual) will be instantiated, in alphabetical order (Perl's sort() function is used, with no custom sorting, it may depend on the locale). Plugins may be accessed using their full (!) module name as the key. Newcomen::Plugins also provides methods to run hooks and filter hooks for all plugins implementing them, and a method to get a sorted list of plugins implementing a specific hook (to run it manually from another component if the hook is not using a standard or filter hook syntax).

Note: Though only plugins that are enabled in the configuration will be instantiated, all plugins found will be used.

Plugins themselves may use Newcomen::Role::Attribute::Plugins to access the main instance of this class (usually not required).

CLASS METHODS

new

my $plugins = Newcomen::Plugins -> new ();

Constructor. Expects no parameters.

INSTANCE METHODS

Plugin Access

Newcomen::Plugins uses a hashref to store the plugin instances, with the full module names as keys, and the instances as values. It uses the hash methods of Newcomen::Util::Traits, with the following exceptions and additions:

The methods delete(), set() and wipe() are not available.
The Newcomen::Plugins method names() is an alias for the keys() method.
The Newcomen::Plugins method plugin() is an alias for the get() method.
The Newcomen::Plugins method plugins() is an alias for the values() method.

Please see Newcomen::Util::Traits for a complete list of methods and more details.

Hook Related

run_hooks

Toggle source: run_hooks

sub run_hooks {

   my $self  = shift;
   my $hooks = ref $_ [0] eq 'ARRAY' ? shift : [shift];
   my @args  = @_;

   for my $hook (@$hooks) {
      $self -> plugin ($_) -> $hook (@args) for ($self -> sort ($hook));
   }

}

# Run a single hook:
$plugins -> run_hooks ($hook, @parameters);

# Run multiple hooks with one call:
$plugins -> run_hooks ([$hook_1, $hook_2], @parameters);

Runs the hook(s) specified by the first parameter (either a single hook name or an arrayref containing multiple hook names). If multiple hooks are supplied, they will be run in the specified order. Hook return values are ignored. All parameters following the first one will be passed to the hooks. Plugins will be called in the order defined by them (see sort()).

run_filter

Toggle source: run_filter

sub run_filter {

   my $self   = shift;
   my $filter = shift;
   my @args   = @_;

   for my $plugin ($self -> sort ($filter)) {
      return undef unless $self -> plugin ($plugin) -> $filter (@args);
   }

   return 1;

}

$plugins -> run_filter ($filter, @parameters);

This method will run the hook (specified by the first parameter) of all plugins implementing it. If one plugin's hook returns a false value, processing will stop (i.e. pending plugin's hooks will not be called) and the method itself will return a false value. If all hooks return a true value, run_filter() will return a true value after all hooks have been run. All parameters following the hook name will simply be passed to the plugin hooks. Plugins will be called in the order defined by them (see sort()).

sort

Toggle source: sort

sub sort {

   my $self = shift;
   my $hook = shift;
   my %sort = ();

   for my $plugin ($self -> elements ()) {

      my $name = $plugin -> [0];
      my $inst = $plugin -> [1];

      $sort {$name} = $inst -> hook_order ($hook) if $name -> can ($hook);

   }

   my @keys = sort keys %sort;
   return sort { $sort {$a} <=> $sort {$b} } @keys;

}

my @order = $plugins -> sort ($hook);

Returns a list of plugins implementing the hook specified as first parameter. Hook order is defined by the plugins, see Newcomen::Plugin::Base. If two (or more) plugins define the same priority for one hook, the order of these plugins is determined by standard string comparison of the module names (may be locale dependent).

MISCELLANEOUS

Plugins must use Newcomen::Plugin::Base as their base class. They must be placed in the Newcomen::Plugin namespace. For more details, see Newcomen::Plugin::Base.

VERSION

This is version 2014052501.

AUTHOR

Stefan Goebel - newcomen {at} subtype {dot} de

COPYRIGHT AND LICENSE

This file is part of Newcomen.

Newcomen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the license, or (at your option) any later version.

Newcomen is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Newcomen. If not, see <http://www.gnu.org/licenses/>.

Newcomen