NAME
App::Relate::Complex - backend for "relate" script (filtered locate)
SYNOPSIS
use App::Relate::Complex;
# search the standard locate database
my $rh = App::Relate::Complex->new();
my $matches = $rh->relate_complex( \@search_terms );
# screen the results with a named filter
my $matches = $rh->relate_complex( \@terms, { add_filters => [':omit'] });
# using options (1) a non-standard locate db, (2) alternate filter storage,
# (3) case-insensitive matches
# generating a newly created locate database
use File::Locate::Harder;
my $db_file = "/tmp/special_locate.db";
my $flh = File::Locate::Harder->new( db => undef );
$flh->create_database( $dir_to_be_indexed, $db_file );
# filter storage search path consisting of:
# (1) yaml file (2) a DBI database connection
my $alt_storage_aref = [
$yaml_file,
{ format => 'DBI',
connect_to => $connect_to,
owner => $owner,
password => $password,
},
];
my $rh = App::Relate::Complex->new( {
storage => $alt_storage_aref,
locatedb => $db_file,
modifiers => 'i', # force case-insensitive matches
} );
my $matches = $rh->relate_complex( \@terms );
# save_filters_when_used can be used to make user-modifiable copies
# of standard filters
my $lfar = App::Relate::Complex->new( {
storage => $yaml_file,
save_filters_when_used => 1,
} );
my $result = $lfar->relate_complex( \@search_terms ); # by default uses ':skipdull'
# A copy of the ":skipdull" filter should now be found in
# $yaml_file, where it can be edited: it will take precedence
# over the default definition on later runs.
DESCRIPTION
Implements the functionality for the relate_complex script, which uses the system's "locate" database to find file names that match multiple search terms.
This version uses the List::Filter modules to get some flexibility and persistance advantages.
It tries to access the locate database through File::Locate::Harder in order to be relatively portable.
METHODS
- new
-
Instantiates a new App::Relate::Complex object.
Takes an optional hashref as an argument, with named fields, which are very similar but not quite identical to those of List::Filter::Storage.
- storage
-
Search path for List::Filter filters, but with an automatically appended handle for the standard filters (defined in the code libraries List::Filter::Library::*)
- write_storage
-
The location (typically a yaml file) that filters are saved to. When we run with "save_filters_when_used" on, accessible copies will be exist here for any filter that's been invoked, even the standard filters.
- transform_storage
-
Like "storage", except for List::Filter::Transform "transforms". Used internally to access one standard filter (the "dwim" transform of "^" into a boundary match). Unlike the case with filter storage, copies of standard transforms are not saved to the write_storage.
- locatedb
-
The "locate" database file used for primary searches. Optional, defaults to the system's main locate database. Setting this is typically done only for testing purposes.
- modifiers
-
Yet another place where perl regexp modifiers can be specified. E.g. a "i" will force case-insensitive matches, overriding any internal modifier settings.
- save_filters_when_used
-
Option to create accessible copies of standard filters that are used (gives the user an easy way to make modifications that override the standard definitions).
- search_filter_name
-
An internally used, temporary filter name, defaults to a value which should be unique to the user (to avoid collisons if shared filter storage is in use). Note: List::Filter at present lacks "anonymous filter" features, this is a work around. Default: _prev_relate_<user>.
- init
-
Initialize object attributes and then lock them down to prevent accidental creation of new ones.
- setup_filter_names
-
Routine used internally to setup fitler names from options settings and so on.
- setup_locate_options
-
Routine used internally (by the relate_complex routine) to set up the string of option switches that need to be used with the locate command (now handled by File::Locate::Harder).
- relate_complex
-
Searches for matching items in the output from the system's "locate" command, using some named filters (List::Filter) to winnow the results.
The list of search patterns may all be perl regexp's (where \x should be assumed), except for the first term, which must be a simple string that can be fed into the locate command (locate). Efficiency is greatly improved if this string is relatively unique.
This defaults to using the standard ":skipdull" filter on the search results. If the "save_filters_when_used" option has been enabled, a copy of this will be found in the "write_location": it can be edited, and the modified version will take precedence over the default definition on later runs.
Input: (1) (aref) list of search patterns (with the first item simple, but unique) (2) (href) options:
- no_default_filters
-
supresses the default filter(s) (cf. ':skipdull')
- add_filters
-
list of filter names to use (in addition to the defaults unless, those have been supressed): this is a space seperated string (not an aref)
- regexp
-
The first item is a POSIX regexp.
Returns: (aref) matching items that pass the filters
Example:
@terms = qw( china www var images ); $china_pics = $self->relate_complex( \@terms, { filters => [":jpeg"] } );
- list_filters
-
Returns a list of all avaliable named filters.
basic setters and getters
- storage
-
Getter for object attribute storage
- set_storage
-
Setter for object attribute set_storage
- locatedb
-
Getter for object attribute locatedb
- set_locatedb
-
Setter for object attribute locatedb
- modifiers
-
Getter for object attribute modifiers
- set_modifiers
-
Setter for object attribute set_modifiers
- filter_storage
-
Getter for object attribute filter_storage
- set_filter_storage
-
Setter for object attribute set_filter_storage
- lfth
-
Getter for object attribute lfth
- set_lfth
-
Setter for object attribute set_lfth
- flh
-
Getter for object attribute flh
- set_flh
-
Setter for object attribute set_flh
- search_filter_name
-
Getter for object attribute search_filter_name
- set_search_filter_name
-
Setter for object attribute set_search_filter_name
SEE ALSO
List::Filter List::Filter::Project
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.