view release on metacpan or  search on metacpan

lib/App/Relate.pm  view on Meta::CPAN

package App::Relate;
#                                doom@kzsu.stanford.edu
#                                15 Mar 2010


=head1 NAME

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

=head1 SYNOPSIS

   use App::Relate ':all';

   relate( \@search, \@filter );

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

=head1 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 L<relate> for user documentation.

=head2 EXPORT

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

=over

=cut

use 5.008;
use strict;
use warnings;
my $DEBUG = 0;
use Carp;
use Data::Dumper;

require Exporter;

our @ISA = qw(Exporter);
our %EXPORT_TAGS = ( 'all' => [
  qw(
      relate
    ) ] );
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
our @EXPORT = qw(  ); # items to export into callers namespace by default.
                      # (don't use this without a very good reason.)
our $VERSION = '0.10';

=item 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 );