NAME

List::Filter::Dispatcher -

SYNOPSIS

   use List::Filter::Dispatcher;
   my $dispatcher = List::Filter::Dispatcher->new(
             { plugin_root       => 'List::Filter::Filters',
               plugin_exceptions => 'List::Filter::Filters::Ext::Nogoodnik',
               } );
   my $aref_out = $dispatcher->apply( $filter, $aref_in );

DESCRIPTION

The Dispatcher object is told where to look for modules that contain the methods that can apply a List::Filter filter. During it's init phase the dispatcher does the necessary requires of each of those method-supplying modules, which must be designed to export these methods to the Dispatcher's namespace.

It's expected that when a new Filter object (or one of it's inheritors) is created, it will be assigned a dispatcher so that it will be able to execute the filter's methods. See List::Filter.

MOTIVATION

This is part of an extension mechanism to allow the creation of additional filter filter methods that the existing code framework will be able to use without modification.

One advantage of this approach is that each filter object has a default method (accessed via the apply method), and yet it can be applied with a different method if that seems desireable.

For example: an "omit" filter could be inverted to display only the items that are usually omitted.

See "Extension mechanisms"" in "List::Filter::Project for instructions on writing methods, and creating filters that use them.

METHODS

new

Instantiates a new List::Filter::Dispatcher object.

Takes an optional hashref as an argument, with named fields identical to the names of the object attributes:

plugin_root

The location to look for the "plugins" that define the actual "methods" that tasks are dispatched to.

plugin_exceptions

A list of modules in the plugin_root that will be ignored.

Note: if you absolutely must use inheritence to create a variant of an existing plugin, the original parent class should be entered in this list to avoid namespace collisions.

init

Initialize object attributes and then lock them down to prevent accidental creation of new ones.

do_require_of_plugins

An internally used routine that loads all of the subs defined in all of the plugins/extensions found in perl's module namespace at or under the "plugin_root" location.

Returns: the number of sucessfully loaded plugin modules.

apply

Applies the filter object, typically acting as a filter.

Inputs: (1) filter object (note: contains an array of patterns) (2) aref of input items to be operated on (3) an options hash reference:

Supported option(s):

  "method" -- routine to use to apply filter to input items
    (defaults to method specified inside the filter).

Return: aref of output items

Note: The options href is also passed through to the "method" routine.

accessors (setters and getters)

Note: because of the oddities of the current architecture, accessors must be provided for any fields needed by either the Filter or the Transform routines, since those are imported into the Dispatcher namespace, they become Dispatcher methods.

I'm making an effort to document them here, for that reason (though in general I think they should be avoided, period).

plugin_root

Getter for object attribute plugin_root

set_plugin_root

Setter for object attribute set_plugin_root

plugin_exceptions

Getter for object attribute plugin_exceptions

set_plugin_exceptions

Setter for object attribute set_plugin_exceptions

SEE ALSO

List::Filter Module::List::Pluggable

AUTHOR

Joseph Brenner, <doom@kzsu.stanford.edu>

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Joseph Brenner

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.

BUGS

None reported... yet.