Index

NAME
SYNOPSIS
DESCRIPTION
CLASS METHODS
- new
INSTANCE METHODS
- hook_order
MISCELLANEOUS
- Methods To Be Overridden
  - _build_default_config
  - _build_hook_order
- Attributes And Handles
SEE ALSO
VERSION
AUTHOR
COPYRIGHT AND LICENSE

NAME

Newcomen::Plugin::Base - Base class for Newcomen plugins.

SYNOPSIS

package Newcomen::Plugin::MyPlugin;

use namespace::autoclean;
use Moose;

extends 'Newcomen::Plugin::Base';

# Add defaults for the plugins config options:

override '_build_default_config' => sub {{
   'foo'    => {
      'bar' => 'some stuff',
   }
}};

# Set a custom hook order value for a hook:

override '_build_hook_order' => sub {{
   'some_hook_name' => 100,
}};

__PACKAGE__ -> meta () -> make_immutable ();

1;

DESCRIPTION

Base class for Newcomen plugins. Every plugin must extend this base class.

It defines the attributes _default_config and _hook_order, including two handles _hook_order_exists() and _hook_order_get(), the private methods _build_default_config() and _build_hook_order(), and the public method hook_order() (and of course new() provided by Moose). It also consumes the core role Newcomen::Role::Attribute::Core, providing the _core() method (and the builder for the _core attribute: _build_core()).

A subclass must not override any of these, except for the methods _build_default_config() and _build_hook_order() if required. See below.

The default configuration of the plugin will be added to the global Newcomen::Config instance after construction. This is done automatically, the plugin just needs to override the builder of the default configuration, see below.

CLASS METHODS

new

my $plugin = Newcomen::Plugin::Foo -> new ();

Constructor. Expects no parameters.

INSTANCE METHODS

hook_order

Toggle source: hook_order

sub hook_order {

   my $self = shift;
   my $hook = shift;

   return $self -> _hook_order_exists ($hook) ? $self -> _hook_order_get ($hook) : 500;

}

my $order = $plugin -> hook_order ($hook_name);

Returns the order number for that plugin and hook. See _build_hook_order() below for more details. It should not be required to call this method directly, instead use Newcomen::Plugins' sort() method to get a sorted list of plugins implementing a hook.

MISCELLANEOUS

Methods To Be Overridden

The following two methods must be overridden if a plugin wants to add configuration defaults or define a custom hook order for one of the hooks it implements:

_build_default_config

Toggle source: _build_default_config

sub _build_default_config {{}}

override '_build_default_config' => sub { return $config_hashref };

If overridden, this method must return a hashref containing the default values for the plugin's configuration options. The hashref may contain other hashrefs or arrayrefs as required. It may also be empty, which is basically the same as not overriding this method. See Newcomen::Config for details on configuration handling. Also see the SYNOPSIS above for an example on how to use this method.

_build_hook_order

Toggle source: _build_hook_order

sub _build_hook_order     {{}}

override '_build_hook_order' => sub {
   return {
      $hook_name => $hook_priority,
      # ...
   };
};

If overridden, this method must return a hashref. The keys must be names of hooks, the values must be integers specifying the plugin priority for this hook, between 0 and 1000. When hooks are run, the priority of the plugin is checked for all plugins implementing the hook. Lower numbers will cause the plugin's hook to be run before plugins defining a higher number for this hook. The default for any hook is 500. Also see the SYNOPSIS for an example.

Attributes And Handles

The following attributes are defined in the base class. There is usually no need to use any of these directly in the plugins, except for the _core attribute.

_default_config

A hashref storing the plugin's default configuration settings. The builder of this attribute is the _build_default_config() method mentioned above. The attribute itself is read only and may only be set by the builder.

_hook_order

A hashref of HookOrder values (integers between 0 and 1000), the keys are the hook names. The builder of this attribute is the _build_hook_order() method mentioned above. Again, this attribute is read only. It defines two handles, _hook_order_exists() and _hook_order_get(), see below.

_hook_order_exists, _hook_order_get

Mappings for Moose's native traits exists() and get(), respectively. See Moose::Meta::Attribute::Native::Trait::Hash for more details.

_core

Returns the global Newcomen::Core instance. This attribute is provided by the role Newcomen::Role::Attribute::Core. The builder of this attribute is called _build_core().

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