/ 
App-Relate-0.01
River stage zero No dependents
/ App::Relate

NAME

App::Relate - "relate" script backend

SYNOPSIS

use App::Relate;

# search the standard locate database
my $rh = App::Relate->new();
my $matches = $rh->relate( \@search_terms );

# screen the results with a named filter
my $matches = $rh->relate( \@terms, { add_filters => [':omit'] });

# using options (1) a non-standard locate db, (2) alternate filter
# storage locations, (3) case-insensitive matches

 use File::Locate::Harder;
 my  = "/tmp/special_locate.db";
 my $flh = File::Locate::Harder->new( db => undef );
 $flh->create_database( $dir_to_be_indexed,  )

 # filter storage search path consisting of:
 #   (1) yaml file (2) a DBI database connection
 my $alt_storage = { storage=> [
          $yaml_file,
          { format     => 'DBI',
            connect_to => $connect_to,
            owner      => $owner,
            password   => $password,
          },
       ];

 my $rh = App::Relate->new( {
            storage            => [ $alt_storage ],
            transform_storage  => [ $alt_tran_storage ],
            locatedb          => $db,
            modifiers          => 'i',  # all matches case insensitive
         } );
 my $matches = $rh->relate( \@terms );


 # save_filters_when_used can be used to make user-modifiable copies
 # of standard filters
 my $lfar = App::Relate->new( {
             storage                => $yaml_file,
             save_filters_when_used => 1,
           } );
 my $result = $lfar->relate( \@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 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 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, a copy of this transform is not saved.

locatedb

The "locate" database file used for primary searches. Optional, defaults to the system's main locate database. Primarily 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 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

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 (see section "the locate program"). 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( \@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

proceedural routines

merge_hash

This routine does hash addition, merging the key-value pairs of one hash into another.

It takes two hash references, and adds the values of the second into the first.

Inputs: (1) the summation href, (2) the href to be added into the first.

Return: a copy of the summation href.

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.