rh - find files that match a C expression
-----------------------------------------


(based on info from the original README:)
Rh was written by Ken Stauffer.
Guy Harris corrected many portability problems.
David MacKenzie revised the man page, and added getopt and regexps.
Norm Hutchinson fixed ungetit().

I (Russell Marks) ported it to Linux (pretty trivial), added support
for hex constants, wrote this README and a new Makefile, and made a
couple of other minor changes. (See ChangeLog for details.)


Description
-----------

`rh' is a useful program similar to `find', but which uses C
expressions to specify which files to match. I think these are the
main advantages rh has over find:

- for many things, it's an awful lot easier to use than find, even
  though I've been using find for years and grok it pretty well.

- you can break up complicated searches into separate functions, and
  even put commonly-used functions in a ~/.rhrc file so they're easily
  available.

- you can do certain kinds of time/date matching which are very
  awkward to do with find. For example, you can easily match files
  which were last modified between two specific dates. (With find this
  requires rather mind-bending use of the `-newer' option and
  `touch'.)

But it inevitably has some disadvantages:

- You don't have very much control over the output format (the `-x'
  option helps a bit in this regard, but not much). find's `-printf'
  option is *hugely* better for that.

- A few things can be a bit painful. The most severe and unfortunate
  example is that doing something like find's `-xdev' option involves
  knowing the device number, e.g. 0x302 for /dev/hda2. There's a
  function in sample.rhrc to make this a bit less nasty, but it's
  still not that pleasant.

- I haven't actually checked, but I suspect it's slower than find.

So it's not perfect, but it's a nice alternative to find that's worth
having. (If you ask me, it's worth having just so you can search for
files in a given date range, never mind anything else. :-))


Examples
--------

Here are some example expressions to give you the idea (mostly from
the man page):

mtime >= [1982/3/1] && mtime < [1982/4/1];

	Finds files that were modified during March 1982.

(size > 10*1024) && (mode & 0111) && (atime <= NOW-1*days);

	Finds all executable files larger than 10k that have not been
	executed (well, accessed) in the last 24 hours.

!(size % 1024);

	Matches files that are an exact multiple of 1k.

strlen >= 4 && strlen <= 10;

	Find files with names between 4 and 10 chars long, inclusive.

( "tmp" || "bin" ) ? prune : "*.c";

	A slightly more esoteric example this - it does a search for
	*.c, but doesn't recurse into any directories called `bin' or
	`tmp'.

You can give expressions on the command-line, running rh like:

	rh -e '<expression>' <directory>

The directory arg is optional; the current dir is the default. (So
that's another advantage over `find'. ;-)) There are other ways to
specify the expression, and several other options; once it's
installed, see the man page for more, and/or do `rh -h' for usage
help.


Installation
------------

On a Linux box, `make' then (as root) `make install' should be fine.
(But if you want it installed somewhere other than under /usr/local,
you'll want to edit the PREFIX and/or BINDIR/MANDIR definitions in the
Makefile first.)

It *should* still work on non-Linux systems (though I haven't tried it
on any); see README.old for details.


Example rc file
---------------

There's an example ~/.rhrc file here, `sample.rhrc', containing
various functions. Most are quite useful (though one or two are
downright silly :-)), so you might want to look through that for handy
things.


History
-------

I found `rh' in the comp.sources.unix archives, volume 21, as `rh2'.
It was posted to c.s.u in 1990. I called this version 2.1 based on
that one being version 2.0.

README.old is the original README, and Makefile.old is the original
Makefile.


-Rus.
