NAME

App::Relate - simple form of the "relate" script (wrapper around locate)

SYNOPSIS

use App::Relate ':all';

relate( \@search, \@filter );

relate( \@search, \@filter, $opts );

DESCRIPTION

relate simplifies the use of locate.

Instead of:

locate this | egrep "with_this" | egrep "and_this" | egrep -v "but_not_this"

You can type:

relate this with_this and_this -but_not_this

This module is a simple back-end to implement the relate script. See relate for user documentation.

EXPORT

None by default. The following, on request (or via ':all' tag):

relate

The relate routine searches the filesystem for items whose fullpath matches all of the terms specified the search terms aref (first argument), and filters out any that match a term in the filters aref (second argument). It's behavior can be modified by options supplied in the options hashref (the third argument).

The options hashref may have values:

ignore_case   do case insensitive searches

dirs_only     return only matching directories
files_only    return only matching plain files
links_only    return only matching symlinks

all_results   ignore any filter supplied as a second argument.
              A convenience to script usage: idential to using an undef second arg.

test_data      For test purposes: an aref of strings to be searched and filtered.
               Suppresses use of L<locate>.

locate         Alternate 'locate' invocation string. See L<locate> routine.
locatedb       Specify non-standard locate db file.  See L<locate> routine.

Example usage:

my $results = relate( \@search_terms, \@filter_terms, $opts );

Example usage (searching a test data set):

my $skipdull = ['~$', '\bRCS\b', '\bCVS\b', '^#', '\.elc$' ];
my $results =
   relate( [ 'whun' ], $skipdull,
     { test_data => [ '/tmp/whun',
                      '/tmp/tew',
                      '/tmp/thruee',
                      '/etc/whun',
                  ],
       } );

locate

Runs the locate command on the given search term, the "seed". Also accepts a hashref of options as a second argument.

Makes use of options fields "DEBUG", "locate", and "locatedb" (aka "database").

The "locate" option defaults simply to "locate". Define it as something else if you want to use a different program internally. (note: you may include the path).

Example:

my $hits = locate( $seed, { locate => '/usr/local/bin/slocate' } );

my $hits = locate( $seed, { locatedb => '/tmp/slocate.db' } );

SEE ALSO

See the man page for "locate".

App::Relate is a more complicated version of this project. It's based on List::Filter, which was intended to allow the sharing of filters between different projects.

NOTES

TODO

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Joseph Brenner

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

BUGS

See relate.