Hook::Modular::Plugin - Base class for plugins
version 1.101050
Here is some_config.yaml:
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
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);
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.
Hook::Modular::Plugin::
bootstrap()
PLUGIN_NAMESPACE
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.
password
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.
SHOULD_REWRITE_CONFIG
Returns the plugin's configuration hash.
Returns the plugin's rule settings.
FIXME
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:
conf()
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"
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.
Deduped
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.
AND
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:
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
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.
$FindBin::Bin
$Bin/assets/plugins/Foo-Bar/
Foo-Bar
My::Test::Plugin
My::Test::Plugin::Some::Printer
$Bin/assets/plugins/Some-Printer
See perlmodinstall for information and options on installing Perl modules.
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.
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.
Marcel Gruenauer <marcel@cpan.org> Tatsuhiko Miyagawa <miyagawa@bulknews.net>
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.
To install Hook::Modular, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Hook::Modular
CPAN shell
perl -MCPAN -e shell install Hook::Modular
For more information on module installation, please visit the detailed CPAN module installation guide.