List::Filter - named, persistent, shared lists of patterns
use List::Filter; my $filter = List::Filter->new( { name => 'skip_boring_stuff', terms => ['-\.vb$', '\-.js$'], method => 'skip_boring_stuff', description => "Skip the really boring stuff", modifiers => "xi", } ); # If non-standard behavior is desired in locating the methods via plugins my $filter = List::Filter->new( { name => 'skip_boring_stuff', terms => ['-\.vb$', '\-.js$'], method => 'skip_boring_stuff', description => "Skip the really boring stuff", modifiers => "xi", plugin_root => 'List::Filter::Filters', plugin_exceptions => ["List::Filter::Transforms::NotThisOne"], } ); # Alternately: my $filter = List::Filter->new(); # creates an *empty* filter my @terms = ['-\.vb$', '-\.js$']; $filter->set_name('skip_dull'); $filter->set_terms( \@terms ); $filter->set_method('skip_boring_stuff'); $filter->set_description( "Skip the really boring stuff"); $filter->set_modifiers( "xi" ); # using a filter (using it's internally defined "method") my $output_items = $filter->apply( \@input_items ); # using a filter, specifying an alternate "method" my $output_items = $filter->apply( \@input_items, "do_it_like_this" );
The List::Filter system is a generalized, extensible way of filtering a list of items by apply a stack of perl regular expressions, with a persistant storage mechanism to allow the sharing of filters between different applications.
A List::Filter filter would just be a container object (a hashref with some accessor code), except that it also has an internally generated "dispatcher" object, so that it knows how to "apply" itself.
The "method" attribute of a filter object is indeed the name of a method, but not one defined inside this module. Instead there's a "plug-in" system that allows the definition of new methods without modification of the existing code.
See List::Filter::Project for documentation of the system.
The name of the search filter.
A list of filter items, e.g. search terms (essentially regexps).
The default method used to apply the search terms.
Default modifiers to be applied to the search terms (essentially, regexp modifiers, e.g. "i").
A short description of the search filter.
Internally used field that stores the dispatcher object, a handle used to apply the filter according to it's "method".
### TODO weirdly enough, I can't figure out where this gets set. ### if it isn't set, then the save method can't work. ### but if the following flag is set, the apply method calls ### the save method... do I ever set this flag at this level?
### TODO
Instantiates a new List::Filter object.
Takes an optional hashref as an argument, with named fields identical to the names of the object attributes:
name description terms method modifiers
With no arguments, the newly created filter will be empty.
There is also the attribute:
storage_handler
which is intended to point to the storage handler set-up so that the filter has the capbility of saving itself to storage later. See "MOTIVATION" below.
There's a related flag (typically set by the storage handler):
save_filters_when_used
There are two additional optional arguments,
plugin_root plugin_exceptions
That are used in creating the dispatcher object which locates the code used to apply the filter (typically as specified by the "method" attribute):
List::Filter::Dispatcher
Initialize object attributes and then lock them down to prevent accidental creation of new ones.
Note: there is no leading underscore on name "init", though it's arguably an "internal" routine (i.e. not likely to be of use to client code).
Generate the dispatcher object, used to apply a filter's method
Apply applies the filter object, typically acting as a filter.
Inputs: (1) aref of input items to be operated on (2) method to use to apply filter to input items (optional) defaults to method specified inside the filter
Return: aref of output items
Saves a copy of the filter to the using the storage_handler stored inside the object.
Getter for object attribute name
Setter for object attribute set_name
Getter for object attribute method
Setter for object attribute set_method
Getter for object attribute description
Setter for object attribute set_description
Getter for object attribute terms
Setter for object attribute set_terms
Getter for object attribute modifiers
Setter for object attribute set_modifiers
Getter for object attribute dispatcher
Setter for object attribute set_dispatcher
Getter for object attribute storage_handler
Setter for object attribute set_storage_handler
Getter for object attribute save_filters_when_used
Setter for object attribute set_save_filters_when_used
Why do we have List::Filter objects instead of just filter hash references? There's the usual reasoning of using abstraction to preserve flexibility (later, implementation can be changed from href to aref, qualification code might be added to the accessors, and so on).
It also makes a convenient place to ensure that a "lock_keys" has been done before the href is used (to help catch typos during development).
A more interesting question is why is there a "method" attribute for each filter? A more standard OOP approach to this kind of polymorphism (each filter is supposed to know it should be used) would be to simply have a class for each type of filter.
This would be inelegant for a few reasons:
(1) it would make the use of the filters more rigid. the internally specified "method" name is only the default way the filter should be applied, there are cases where you might like to deviate from it (e.g. you might invert an "omit" filter to do a "select" to check just what it is you've been skipping).
(2) it would multiply classes for no good reason, and I think it would make it a little clumsier to add new Filter "methods".
Each filter can hold a pointer to it's "storage handler", which is intended to be set by the "lookup" method of that handler as the filter is returned. This gives the filter the capability to save itself later, and that's not as crazy as it sounds (not quite) because there's a path of storage locations, and the place it's read from need not be where it's saved to).
The way it works normally (?) is that the storage handler instructs the filter that when it is applied it will save a copy of itself. The storage write location is most likely going to be a yaml file that the user has access to, but the storage read location can be somewhere else (e.g. a "standard" filter, which is defined in the code, and hence not writeable). The idea here is that any filter that you've used, you get an accessible copy of, suitable for editing if you'd like to make changes.
List::Filter::Project List::Filter::Dispatcher
Joseph Brenner, <doom@kzsu.stanford.edu>
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.
None reported... yet.
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
To install List::Filter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm List::Filter
CPAN shell
perl -MCPAN -e shell install List::Filter
For more information on module installation, please visit the detailed CPAN module installation guide.