/ 
Plugins-0.41
River stage one • 1 direct dependent • 3 total dependents
/ Plugins::Style1

NAME

Plugins::Style1 - Generic plugins framework with linear config files

SYNOPSIS

 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);
 }

DESCRIPTION

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.

EXAMPLE CONFIG FILE (SIMPLE)

 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

CONSTRUCTION AND INITIALIAZATION

In addition to the parameters for new() and readconfig() documented for Plugins, the following additional parameters may be given...

%args for new()

parse_config_line => \&func

The unknown line parser can be specified here or in readconfig()'s %args.

%args for readconfig()

self => $self

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.

config_prefix => "prefix_"

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.

For configuration file readability, your prefix should probably end with an underscore (_).

parse_config_line => \&func

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.

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.

The arguments passed to the &$parse_config_line() function are:

$self/$pkg

The object or package of the caller.

$config_prefix

The configuration prefix for the plugin being invoked.

$configfile

The filename of the configuration file

$line

The configuration line. The prefix has not been removed.

$line_number

The line number of the line in the configuration file (for generating nice error messages).

$seqno

An integer that increments each time the same configuration file is read.

CONFIGURATION FILE FORMAT

The configuration file parser knows about four types of lines:

Comments

The hash character (#) denotes a comment and except for within quotes a hash character will end parsing for that line.

Plugin requests

<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.

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():

$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.

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.

Plugin search directory directive

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 /some/path
plugin_directory /another/path

Directory names may not have whitespace in them. Directories that do not exist will be silently ignored.

Arguments to new()

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');
Freestanding configuration lines.

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.

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().

EXAMPLE CONFIG FILE (NOT SO SIMPLE)

 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

WRITING PLUGINS

Plugin-defined methods

Plugins should be subclasses of Plugins::Style1.

config_prefix()

This method is used to determine the default configuration-line prefix for the plugin. Defining this method is manditory.

parse_config_line($prefix, $configfile, $line, $lineno, $seqno)

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.

Plugins with plugins

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:

$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.

SEE ALSO

Plugins

THANK THE AUTHOR

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.

LICENSE

Copyright (C) 2006-2007, David Muir Sharnoff <muir@idiom.com>. This module may be used and redistributed on the same terms as Perl itself.