view release on metacpan or  search on metacpan

bin/relate  view on Meta::CPAN

__END__


=head1 DESCRIPTION

The mnemonic is that B<relate> makes the file system a little
more relational and a little less hierarchical (but L<relate isn't really>).

Instead of typing this:

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

You can just type:

  relate this with_this and_this -but_not_this

So essentially this script is the equivalent of

  locate primary_term | egrep term2 | egrep term3 [....| termN]

Though it also has a few other features, B<relate>:

  o  screens out "uninteresting" files by default (emacs backups, CVS/RCS files)
  o  has options to restrict reports to files, directories or symlinks.

An important performance hint: you can speed up relate
tremendously by using a relatively unique first term.  For
example, if you're on a unix box, you don't want to start
with something like "home" or "lib" which is going to match
a huge number of files in the locate database. You'll find
that "relate gdk lib" is faster than "relate lib gdk".

The first term should be a simple string (unless you've used the
"-r" option), but all the following terms are perl regexps.
If you do use the "-r" option, than the first term is a POSIX
regexp (it has no effect on the following terms).

(This inelegant state of affairs is the result of working as a
wrapper around the locate command; the first term is fed to it
directly, then the output is filtered using perl pattern
matches.)

=head2 reverse match

A leading minus can be used to indicate a reverse match
(just as with many web search engines).  This is much like a
"grep -v": it filters out lines that match it.
This can't be used on the first term, only on the secondary ones.

For example:

   relate my_site index -htm$

will screen out files ending in "htm" (but not "html").

=head2 standard filter

This script has the extremely useful feature of automatically
omitting uninteresting files, but it's guaranteed that you'll
be confused by this some day, so don't say I didn't warn you.

Remember that there's a "-a" option (also called "--all")
which overrides the default filter and returns all matches.

As of this writing, by default files are ignored that match
these patterns:

      '~$'       # emacs backups
      '/\#'      # emacs autosaves
      ',v$'      # cvs/rcs repository files
      '/CVS$'
      '/CVS/'
      '/RCS$'
      '\.elc$'   # compiled elisp

The default filter can be changed by editing the ~/.relate file.
(This is created the first time you run B<relate>.  It is perl code
generated by Data::Dumper, which is evaled when you run relate
(so be careful with the permissions on this file).

=head2 directory or file types

The -f (--files) and -d (--dirs) options can restrict the reported
results to just plain files, or to just directoires, respectively.

There is also a -l (--links) option, that will restrict the listing
to just symlinks.

It's expected that you will use these type restrictions one-at-a-time.
At present, when multiple ones are used, one will always win-out.
This behavior may change in the future.

=head2 dwim upcarets

The use of a leading "^" achor in a pattern is allowed, but it is
silently transformed into a boundary match: "\b".  Otherwise "^"
wouldn't be very useful (consider that with full paths *all*
listings match "^/").  An embedded or trailing "^" is left alone.
Ditto for a "^" in front of a slash: if you ask for '^/usr/lib',
maybe that's really what you want.

This feature does not (at present) work well with a minus for
negation.

=head2 relate isn't really

I like this slogan as a mnemonic: "relate makes the file
system a little more relational", though really this is an
abuse of the term "relational".

The point though, is that using "relate" is something like
doing a database query where you specify certain constraints in
any order and get all records that match them. But if you can't
relate, that's okay.

(Just be glad I don't think of it as "feeling your way
around".)

=head2 database option