/ 
Hook-Modular-1.101050
River stage one • 1 direct dependent • 1 total dependent
/ Hook::Modular::Plugin

NAME

Hook::Modular::Plugin - Base class for plugins

VERSION

version 1.101050

SYNOPSIS

Here is some_config.yaml:

global:
  log:
    level: error
  cache:
    base: /tmp/test-hook-modular
  # plugin_namespace: My::Test::Plugin

plugins:
  - module: Some::Printer
    config:
      indent: 4
      indent_char: '*'
      text: 'this is some printer'

here is the plugin:

package My::Test::Plugin::Some::Printer;
use warnings;
use strict;
use parent 'Hook::Modular::Plugin';

sub register {
    my ($self, $context) = @_;
    $context->register_hook($self,
      'output.print' => $self->can('do_print'));
}

sub do_print { ... }

And this is some_app.pl

use parent 'Hook::Modular';

use constant PLUGIN_NAMESPACE => 'My::Test::Plugin';

sub run {
  my $self = shift;
  $self->SUPER::run(@_);
  ...
  $self->run_hook('output.print', ...);
  ...
}

main->bootstrap(config => $config_filename);

DESCRIPTION

NOTE: This is a documentation in progress. Not all features or quirks of this class have been documented yet.

This is the base class for plugins. All plugins have to subclass this class.

If your plugin is in a different namespace than Hook::Modular::Plugin:: then your main program - the one that subclasses Hook::Modular and calls bootstrap() - has to redefine the PLUGIN_NAMESPACE constant as shown in the synopsis.

METHODS

new

Creates a new object and initializes it. Normally you don't call this method yourself, however. Instead, Hook::Modular calls it when loading the plugins specified in the configuration.

The arguments are passed as a named hash. Valid argument keys:

conf

The plugin's own configuration, taken straight from the configuration. It has to be a hash of scalars, or hash of hashes or the like. See "PLUGIN CONFIGURATION" for details.

rule

Specifies the rule to be used for this plugin's dispatch. See "RULES".

rule_op

Specifies the rule operator to be used for this plugin's dispatch. See "RULES".

After accessors have been set, any hash keys named password within the plugin's configuration are decrypted. If unencrypted passwords are found, they can be encrypted. At the moment, this encryption is more a proof-of-concept, as the only encryption supported isn't even an encryption, just base64 encoding.

This encryption and decryption is only happening if your main class, the one subclassing Hook::Modular, says it should. See SHOULD_REWRITE_CONFIG in Hook::Modular for details.

conf

Returns the plugin's configuration hash.

rule

Returns the plugin's rule settings.

assets_dir

FIXME

class_id

FIXME

decrypt_config

FIXME

dispatch_rule_on

FIXME

do_walk

FIXME

init

FIXME

load_assets

FIXME

log

FIXME

plugin_id

FIXME

walk_config_encryption

FIXME

PLUGIN CONFIGURATION

The plugin's configuration can be accessed using conf(). It is a hash whose values can be anything you like. There are a few standard keys with predefined meanings:

disable
plugins:
  - module: Some::Printer
    disable: 1
    config:
      ...

If this key is set to a true value in the plugin's configuration, the plugin is not even loaded. This is useful for temporarily disabling plugins during debugging.

assets_path
plugins:
  - module: Some::Printer
    assets_path: /path/to/assets/dir
    config:
      ...

Specifies the directory in which this particular plugin's assets can be found. See "ASSETS"

RULES

You can control whether a particular plugin is dispatched by setting rules in its configuration.

plugins:
  - module: Some::Printer
    rule:
      module: Deduped
      path: /path/to/depuped/file.db
    config:
      ...

If a rule is specified on a plugin, it is being called before a hook is run. If the rule does not veto the dispatch, the hook is run.

In the example above, the current rule namespaces (see Hook::Modular) are searched for a class Deduped and the rule config (in this case, a path) is given to the rule. The rule is then asked whether the hook should run. See Hook::Modular::Rule for details.

It is possible to specify multiple rules along with a boolean operator that says how the rule results are to be combined. Example:

plugins:
  - module: Some::Printer
    rule:
      - module: Deduped
        path: /path/to/depuped/file.db
      - module: PhaseOfMoon
        phase: waxing
    rule_op: AND
    config:
      ...

In this example, the plugin is only run if both rules are ok with it, because of the AND rule operator.

ASSETS

Plugins can have assets. You can think of them as little sub-plugins that each plugin can handle the way it wants. That is, apart from being able to find a plugin's assets in a specific directory, there is not much more that Hook::Modular::Plugin enforces or provides.

One idea for assets may be little code snippets that you can just put in the plugin's assets directory. They would be more involved than what you would normally specify in a configuration file. So you could have the configuration file point to one or more assets and the plugin could then load and eval these assets and act on them.

There are three places that plugins can look for assets. If the plugin configuration itself contains an assets_path key, this directory is used and no other directories are searched. Example:

plugins:
  - module: Some::Printer
    assets_path: /path/to/assets/dir
    config:
      ...

If there is no plugin-specific assets_path key, but there is an assets_path key in the global part of the configuration, that directory is used and no other directories are searched. Example:

global:
  assets_path: /path/to/assets/dir

If neither a plugin-specific nor a global assets path is specified, an assets directory in the same location as the current program, as determined by $FindBin::Bin, is used. The actual path used would be $Bin/assets/plugins/Foo-Bar/, where Foo-Bar is that part of the plugin's package name that comes after the plugin namespace, with double colons converted to dashes. For example, if your plugin namespace is My::Test::Plugin and your plugin package name is My::Test::Plugin::Some::Printer, then the default assets directory would be $Bin/assets/plugins/Some-Printer.

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through the web interface at http://rt.cpan.org/Public/Dist/Display.html?Name=Hook-Modular.

AVAILABILITY

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit http://www.perl.com/CPAN/ to find a CPAN site near you, or see http://search.cpan.org/dist/Hook-Modular/.

The development version lives at http://github.com/hanekomu/Hook-Modular/. Instead of sending patches, please fork this project using the standard git and github infrastructure.

AUTHORS

Marcel Gruenauer <marcel@cpan.org>
Tatsuhiko Miyagawa <miyagawa@bulknews.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2007 by Marcel Gruenauer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.