Plugins::Style1 - Generic plugins framework with linear config files
use Plugins::Style1; $plugins = Plugins::Style1->new([context => $context]) $plugins->readconfig($config_file, self => $self) $plugins->initialize() $plugins->invoke($method, @args); $plugins->invoke_until($method, sub { scalar(@_) }, @args); my $iterator = $plugins->iterator(); while (@results = &$iterator(@args)) { } for my $plugin ($plugins->plugins()) { $plugin->invoke($method); }
Plugins::Style1 is a generic plugins framwork with a simple linear-style configuration file that can support plugins of plugins in the same configuration file.
It is based on Plugins.
sleeptime 1 plugin SyslogScan::Daemon::BlacklistDetector as bld_ bld_debug 0 bld_plugin SyslogScan::Daemon::BlacklistDetector::Postfix rx_ourIP 127\.0\.0\.1 logpath /var/log/mail.log debug 0 bld_plugin SyslogScan::Daemon::BlacklistDetector::EmailNotify debug 1 notify "John <root@localhost>" renotify_time 7200 forget_time 3600 sendfrom root clean_time 1800 maxkeep 100
In addition to the parameters for new() and readconfig() documented for Plugins, the following additional parameters may be given...
new()
readconfig()
The unknown line parser can be specified here or in readconfig()'s %args.
%args
Set self to let readconfig() know who called it. With that information, readconfig() can make callbacks for the other parameters. Without a $self readconfig() uses caller() to and uses class methods instead of object methods.
self
$self
caller()
Since the configuration file can support multiple plugins at the same time, we need to distinquish what goes with what plugin. This is done by setting a configuration prefix here or when calling new(). Only config lines that start with the prefix will be parsed: everything else will be ignored. The root/parent program should have an empty string as its prefix.
If this is unspecified, $self->config_prefix() will be called. If that doesn't exist then an empty-string prefix will be assumed.
$self->config_prefix()
For configuration file readability, your prefix should probably end with an underscore (_).
_
readconfig() knows about lines that start ${prefix}plugin, but for everything else it needs help. The parse_config_line parameter should be a reference to a function to be called when there is a configuration line other than ${prefix}plugin.
${prefix}plugin
parse_config_line
If no parse_config_line parameter is specified then $self->parse_config_line() will be tried. If that doesn't exist either then an unknown configuration line is a fatal error.
$self->parse_config_line()
The arguments passed to the &$parse_config_line() function are:
&$parse_config_line()
The object or package of the caller.
The configuration prefix for the plugin being invoked.
The filename of the configuration file
The configuration line. The prefix has not been removed.
The line number of the line in the configuration file (for generating nice error messages).
An integer that increments each time the same configuration file is read.
The configuration file parser knows about four types of lines:
The hash character (#) denotes a comment and except for within quotes a hash character will end parsing for that line.
#
<prefix>plugin </file/name<gt [as <prefix_override>]>
<prefix>plugin <module_name> [as <prefix_override>]
plugin Foobar::Baz # defaults to prefix "fb_" plugin /some/file # defaults to no prefix plugin a_file # defaults to no prefix fb_plugin Foobar2::Baz as fb2_
The basic part of a configuation file is a line that starts with the word plugin. What follows on the same line is the name of a perl module. The word plugin may be preceeded by a prefix. The prefix disambiguates whose plugin it is when multiple plugins are sharing a configuration file.
plugin
The prefix is normally given by the config_prefix() class method in the plugin module, but it can be overridden (in order) by (1) the config file; or (2) by an argument to readconfig (readconfig($configfile, config_prefix => 'foobar_')) or (3) as by member data of the caller to readconfig():
config_prefix()
readconfig($configfile, config_prefix => 'foobar_')
$self->{config_prefix} = "bar_"; my $plugins = new Plugins; $plugins->readconfig($configfile, self => $self);
To override the prefix in the config file, add as prefix-name the end of a plugin line.
as prefix-name
Plugins that are fully-fledged perl modules should be named as such. Plugins that are not, (named as files) will be wrapped by Plugins into a perl module. Plugins::Style1 dis-ambiguates between files and modules by looking for the string :: in module names.
::
Plugins that are plain filenames that are not absolute paths are searched for with their own search path. The The directive to add to that path is plugin_directory.
plugin_directory
plugin_directory /some/path plugin_directory /another/path
Directory names may not have whitespace in them. Directories that do not exist will be silently ignored.
Any indented lines that follow a plugin request will set what arguments are passed to the new() when the module is initialized.
The indented lines a broken up on word boundries except that what is between double-quotes or single-quotes counts as a single word.
bld_plugin SyslogScan::Daemon::BlacklistDetector::EmailNotify notify '"David Sharnoff" <muir@idiom.com>' from root@my.poor.system
Will produce a call like:
SyslogScan::Daemon::BlacklistDetector::EmailNotify->new( 'notify', '"David Sharnoff" <muir@idiom.com>', 'from', 'root@my.poor.system');
Lines that that begin in column one that aren't plugin requests, are regular configuration lines. By default they are parsed by the parse_config_line() method of the plugin that has called readconfig(). The function called can be overridden with the %args to readconfig(). The function will be called as a object method if a $self was provided to readconfig(). It will be called as a class method otherwise.
parse_config_line()
Lines in the configuratin file that being with a plugin prefix will be parsed by that plugin's parse_config_line() method (if it has one). This will happen after new() is called so parse_config_line() will be called as a class method.
The function to call for these lines defaults to parse_config_line() but it can be overridden by passing a function to the call to readconfig:
my $plugins = new Plugins; $plugins->readconfig($configfile, parse_config_line => \&some_function);
Or it can be overridden with member data of the caller:
$self->{parse_config_line} = \&some_parse_function; my $plugins = new Plugins; $plugins->readconfig($configfile, self => $self);
If no parse_config_line() function is provided, the parser will die on any lines that aren't recognized.
The same configuration file is potentially re-read for each plugin. Generally plugins that have plugins will need to be calling readconfig().
sleeptime 10 plugin SyslogScan::Daemon::BlacklistDetector debug 1 bld_plugin SyslogScan::Daemon::BlacklistDetector::Postfix debug 1 rx_ourIP 216\.240\.47\.\d+ logpath /var/log/mail.log bld_plugin SyslogScan::Daemon::BlacklistDetector::EmailNotify debug 1 notify you@yourhost. renotify_time 7200 forget_time 3600 sendfrom root # comments are allowed here clean_time 1800 maxkeep 100 bld_plugin SyslogScan::Daemon::BlacklistDetector::KeepTrack # indented comments are allowed here debug 1 dbi_dsn DBI:mysql:database=quarentene;host=localhost username quarentene password bloorf table_prefix kt_ # comments can go nearly anywhere postcommand "(cd /etc/postfix; make)" postfile /etc/postfix/outbound-problems pool /etc/postfix/outbound-list latency 10 decay_day 3600 decay_rate 0.98 decay_done 0.2 # of course, comments are allowed in column 1. plugin SyslogScan::Daemon::BlacklistDetector as bld2_ debug 1 bld2_plugin SyslogScan::Daemon::BlacklistDetector::Postfix as x1_ debug 1 x1_rx_ourIP 216\.240\.47\.\d+ x1_logpath /tmp/mail.log bld2_plugin SyslogScan::Daemon::BlacklistDetector::EmailNotify as x2_ debug 1 x2_notify you@yourhost x2_renotify_time 7200 x2_forget_time 3600 x2_sendfrom root x2_clean_time 1800 x2_maxkeep 100 bld2_plugin SyslogScan::Daemon::BlacklistDetector::KeepTrack as x3_ debug 1 postcommand '' x3_dbi_dsn DBI:mysql:database=quarentene;host=localhost x3_username quarentene x3_password '' x3_table_prefix kt2_ x3_postfile /etc/postfix/outbound-problems2 x3_pool /etc/postfix/outbound-list x3_latency 10 x3_decay_day 3600 x3_decay_rate 0.98 x3_decay_done 0.2
Plugins should be subclasses of Plugins::Style1.
Plugins::Style1
This method is used to determine the default configuration-line prefix for the plugin. Defining this method is manditory.
If your want to be able to have configuration directives other than what is passed to new(), then you'll need to define a parse_config_line() method. Eg:
my $bar = 7; sub config_prefix { 'foo_' } sub parse_config_line { my ($self, $prefix, $configfile, $line, $lineno, $seqno) = @_; if ($line =~ /^${prefix}bar\s*=\*(\d+)) { $bar = $1; } else { die "illegal config at $configfile line $lineno\n"; } }
One way to get a simple parser like this and also something to handle arguments to new() is to use Plugins::SimpleConfig.
One subtle aspect of sharing configuration files is that plugin prefix may be overridden. This is done on a per-configuration file basis. If for some reason you want to un-override your configuration prefix then don't pass that part of the $context:
$context
$self->{plugins} = new Plugins context => $self->{context}, config_prefix => 'something_else_';
Since the child requestors's configuration file may get read twice, the parse_config_line method may get called twice. To avoid this, pass in a null function for parse_config_line:
$self->{plugins} = new Plugins context => $self->{context}, parse_config_line => sub {}
Or
$self->{plugins}->readconfig($config, self => $self, parse_config_line => sub {});
In most cases there probably isn't any harm in this double parsing.
Plugins
If you find this module useful and wish to show your appreciation to the author, please give me a Request-For-Quote on your next high-speed internet pipe order. I have good pricing for T1s, T3s, OC3s etc.
Copyright (C) 2006-2007, David Muir Sharnoff <muir@idiom.com>. This module may be used and redistributed on the same terms as Perl itself.
To install Plugins, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Plugins
CPAN shell
perl -MCPAN -e shell install Plugins
For more information on module installation, please visit the detailed CPAN module installation guide.