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.