========================================================================

                             Introduction

ernie is a grep-like script written in 100% Emacs Lisp.  It should
just work.  The hope is that this will solve the problem of grepping
under Windows, and that ernie will get picked up by the official emacs
distribution and used as the fallback if a compiled grep cannot be
found.  For inclusion with the main GNU Emacs source, permission is
hereby given in advance to switch to any GPL license.

Another advantage of ernie is that you only have to learn one regular
expression syntax.  The same is basically true of the built-in grep
front-ends which can now share the same regular expression syntax with
the grep back-end.

The main disadvantage of ernie is that it is not as fast as a compiled
grep, but it is infinitely faster than no grep.

========================================================================

                                Usage

For stand-alone operation, run this script as follows:

    emacs -Q --batch --load ernie -f ernie/main \
          -- [<options>] <regexp> <file> [<file> ... ]

If you choose to start emacs directly, remember that the options for
this script should be proceeded by "--" to prevent emacs from trying
to consume them.

Two types of wrappers are provided to help hide the details of the raw
command above that is needed to start emacs in batch mode.  These
wrappers are called "grep" and "ernie" respectively.  The "grep" type
wrapper is what you would expect from any grep:

    # Unix
    grep.sh -r -n -i -e <regexp> <dir>

    # Windows
    grep.bat -r -n -i -e <regexp> <dir>

But typing "grep -r -n -i e" at the command line is a little slow.
So, the second type of wrapper is called "ernie" which gets its name
from the most common way of starting grep:

    grep -r -n -i -e
      ^   ^  ^  ^  ^

The "ernie" wrappers are equivalent to "grep -r -n -i e" so you would
typically use them on the command line as follows:

    ernie <regexp> <dir>

Other options can follow like --include or --exclude, but the first
positional parameter for ernie must be a regular expression.  For
example, the following works to exclude the .git directory:

    ernice <regexp> <dir> --exclude .git

If you want the "ernie" type of wrapper to print the version, "ernie
-V" will not work because the -V is in the "-e <regexp>", and the -e
option says to allow leading dashes as part of the regexp.  To get
ernie to print its version, do something like the following:

    ernie -- -V

Lastly, single quotes under Windows do not act like single quotes
under bash.  If in doubt, use double quotes under Windows.

========================================================================

                             Installation

To install, just download the source and unpack somewhere convenient.
If you use the included "ernie.bat" or "grep.bat" wrapper, it is not
necessary for the directory containing "ernie.el" to be added to your
EMACSLOADPATH.  It is helpful though to have both "emacs" and the
provided wrappers in your system PATH.

ernie is designed (within reason) to be a drop-in replacement for the
grep command.  As such, this script is designed to be run as a
separate program.  If you are having trouble shelling out under
Windows, try using Emacs's "cmdproxy.exe" as your shell as follows:

    ;; For Windows,
    (setq explicit-shell-file-name
          (concat exec-directory "cmdproxy.exe"))

Then, update your ~/.emacs file to point to the "grep.bat" wrapper as
follows:

    (setq grep-command "grep.bat -H -r -n -i -e ")
    (setq grep-find-command "grep.bat -H -r -n -i -e ")

You will probably also want to add the following which is not
necessary provided you use the -H option as shown above:

    ;; Prevent emacs from silently adding NUL to the grep command line.
    (setq grep-use-null-device nil)

========================================================================

                                Extras

The following command-line options are extras:

                     --abspath : Print absolute paths.
  --line-length-limit <length> : Truncate long lines.
           --size-limit <size> : Skip large files.

========================================================================