% $Id: grep.tex 1.8 1998/02/07 19:38:45 brian Exp $

\chapter{grep---Search for regular expression}

The \textbf{grep} (get regular expression and print) command is an
subset of the Unix \textbf{grep} command and even smaller subset of
the superb GNU \textbf{grep}. It searches one or more files for a
pattern, can descend into subdirectories when searching, and can write
its output (matching lines along with optional file name, line number,
and column number) in one of a user-defined set of customizable
formats.

\section{Usage}

\verb+grep [ -flags ] [ -- ] "pattern" [ fspec ... ]+
\medskip

The \textbf{grep} command searches for the specified pattern. It
writes each line that contains the pattern to standard output. The
pattern is a regular expression as described later in this document.

One or more file specifications may be present on the command line. If
no file specifications are present, then \textbf{grep} reads lines
from standard input.

A file specification consists of an optional drive, optional path
information, and a filename. The filename may consist of Bourne shell
pattern-matching characters.

Binary files (such as \textbf{*.obj} and \textbf{*.exe}) can be
searched in addition to text files.

\section{Flags}

The flags that are supported are a subset of those supported by the
standard Unix \textbf{grep} and of course an even smaller subset of
those supported by GNU \textbf{grep}:

\begin{itemize}

    \item[\texttt{-c}]  Display only a count of matching lines.

    \item[\texttt{-i}] Ignore case when making comparisons (same as
        \texttt{-y}).

    \item[\texttt{-l}] (letter el) List just the names of files (once)
        with matching lines. Each file name is separated by a new-line
        character.

    \item[\texttt{-n}] Preceed each line with the file name and line
        number, in the following default form: \texttt{filename(line)}

    \item[\texttt{-\#}] (where \texttt{\#} is a digit from 0 through
        9, inclusive): If the \texttt{-n} flag is also specified, then
        a specifying a digit will select a pattern to use when showing
        the file name, line number, and starting column. If no digit
        is specified, then \texttt{0} (zero) is assumed.

    \item[\texttt{-s}] Descend subdirectories, also.

    \item[\texttt{-v}] Display lines that don't contain the pattern.

    \item[\texttt{-y}] Ignore case when making comparisons (compatible
        with the RS/6000).

\end{itemize}

\section{Customizing the Output}

Normally, the Unix platform, GNU tools, and Emacs editor family
support the standard Unix-style \textbf{grep} output format. However,
the DOS, Windows, and OS/2 platforms have widely varying (and often
uneven) requirements for the output of \textbf{grep} and grep-like
tools. Of course, GNU Emacs can be customized for different styles,
but most other tools are not nearly as accomodating.

Therefore, the output of \textbf{grep} can be customized to include
the filename, line number, column number, and other characters in the
order required by different programs.
If the \texttt{-n} flag is specified, then a format pattern number may
also be specified. If no pattern number is specified, then \texttt{-0}
(zero) is used as the default.

The \textbf{grep} program looks in the \texttt{GREPn} environment
variable, where \texttt{n} is the pattern number. If there is no
\texttt{GREPn} variable in the environment (for instance, if
\texttt{-n5} is specified but there is no \texttt{GREP5} environment
variable defined), then the ``\verb+$n($l) : +''\ pattern is assumed.

The characters from the formatting pattern defined by the environment
variable are copied to the output and then the text from the line is
added. If a dollar sign \texttt{\$} meta character is encountered,
then it and the next character are interpreted as follows:

\begin{itemize}

    \item[\texttt{\$n}] specifies the name of the file.
    \item[\texttt{\$l}] (letter el) specifies the line number within the file.
    \item[\texttt{\$c}] specifies the starting column within the line.
    \item[\texttt{\$\$}] specifies the dollar sign itself.
    \item[\texttt{\$"}] specifies a double quote character.

\end{itemize}

With the exception of \texttt{\$"}, double quotes within or
surrounding a format pattern are ignored.

If no format pattern is found, the ``\verb+$n($l) : +''\ pattern
is assumed. This causes the following information to be shown:

\begin{itemize}
        \item[{}] \verb+filename(linenumber) : text from line+
\end{itemize}

Some useful format patterns that may be specified are:

\begin{itemize}

        \item[{}] \verb+set GREP0="$n($l) : "+
        \item[{}] \verb+set GREP1="$n($l:$c) : "+
        \item[{}] \verb+set GREP2="$n:$l:"+
        \item[{}] \verb+set GREP3="$n/$l/$c "+
        \item[{}] \verb+set GREP4="$n,$l,$c "+

\end{itemize}

When specified with the \texttt{-n} flag, the format patterns shown
above are used as follows:

        \texttt{-n0} is the default that this package's \textbf{grep} has shown from the
        beginning. It mimics the format of error messages from many PC
        compilers:

                \begin{itemize}
                \item[{}] \verb+filename(linenumber) : text from line+
                \end{itemize}

        The \texttt{GREP0} environment variable can be changed to another pattern
        so that -n by itself uses that pattern instead.

        \texttt{-n1} mimics the format of error messages from some
        modern C/C++ compilers that also include the column number:

                \begin{itemize}
                \item[{}] \texttt{filename(line:column) :\ text from line}
                \end{itemize}

        \texttt{-n2} is the Unix and GNU \textbf{grep}'s style:

                \begin{itemize}
                \item[{}] \texttt{filename:linenumber:text from line}
                \end{itemize}

        \texttt{-n3} and \texttt{-n4} mimic the format used by the
        UltraEdit32 editor (for Windows platforms only) allows you to
        select a filename, open it, and put the cursor at the
        specified line and column within the file. UltraEdit is a very
        capable shareware editor available from the
        \textit{www.idmcomp.com} Web site. It's a spectacular bargain
        with a low shareware price and with capabilities, ease-of-use,
        and company responsiveness far beyond that of many other
        editors at any price.

\section{Notes}

Lines are limited to a length of 512 characters. Longer lines are split
into pieces of 512 characters or less.

A dot within a filename is treated as just another character and not
assumed to be the beginning of a file extension. Therefore, you should
specify \texttt{*} instead of \texttt{*.*} when searching all files in
a specific directory.

Errors are listed on standard error.

\section{Regular Expressions}

The \textbf{grep} command supports regular expressions that are
combinations of one or more of the following:

\begin{itemize}

\item The following expressions match a single character:

    \begin{flushright}
    \begin{tabular}{l p{3.3in}}

        \verb+c+ & Any ordinary character, other than one of the
                   special pattern-matching characters, matches
                   itself. \\ \\

        \verb+.+ & A \texttt{.}\ (period) matches any single
                   character. \\ \\

        \verb+[string]+ & A string enclosed in square brackets matches
                   any one character in the string. \\ \\

        \verb+[.-.]+ & A range is two characters separated by a dash
                   and enclosed in square brackets. It matches any
                   character that is within the range. \\ \\

        \verb+[^string]+ & A string (or range) enclosed in square
                   brackets and preceeded by a \verb+^+ (circumflex)
                   matches any character except for the characters in
                   the string (or range). \medskip

                   Strings and ranges may be combined as needed, as
                   in: \verb+[a-m0-9xyz]+, which matches a through
                   \texttt{m}, \texttt{0} through \texttt{9},
                   \texttt{x}, \texttt{y}, or \texttt{z}. \\ \\

        \verb+\c+ & The \verb+\+ (backslash) followed by any character
                   matches that character. This is useful for matching
                   the following special characters:
                   \verb+. * [ ] { } ^ $ \+ \\

    \end{tabular}
    \end{flushright}

\item The single-character expressions can be combined into regular
expressions as follows:

    \begin{flushright}
    \begin{tabular}{l p{3.3in}}

        \verb+*+ & Matches zero or more occurences of the previous
                   character. \\ \\

        \verb+{m}+ & Matches exactly \texttt{m} occurrences of the
                   previous character. \\ \\

        \verb+{m,}+ & Matches at least \texttt{m} occurrences of the
                   previous character. \\ \\

        \verb+{m,n}+ & Matches at least \texttt{m} but no more than
                   \texttt{n} occurrences of the previous character.
                   \texttt{m} and \texttt{n} must be integers from 0
                   to 255, inclusive. \\

    \end{tabular}
    \end{flushright}

\item A regular expression can be restricted to match a string that begins on
the first character of the line, ends on the last character of the
line, or both, as follows:

    \begin{flushright}
    \begin{tabular}{l p{3.3in}}

        \verb+^pattern+ & The pattern matches a string that begins on
                   the first character of a line. \\ \\

        \verb+pattern$+ & The pattern matches a string that ends on
                   the last character of a line. \\ \\

        \verb+^pattern$+ & The pattern matches an entire line. \\

    \end{tabular}
    \end{flushright}

\end{itemize}

\section{Examples}

\begin{enumerate}

\item \verb+grep "the cat" *.txt /*.bat+

        This command searches the files in the current directory that
        end in \textbf{.txt} and the \textbf{.bat} files in the root
        directory for the string \texttt{the cat}. Only exact case
        matches are listed on standard output: occurrences of
        \texttt{The cat} and \texttt{the Cat} are not listed.


\item \verb+grep -i "the cat" *.txt /*.bat+

        This command is similar to the previous one except that it
        performs a case-insensitive search. Occurrences of \texttt{The
        cat} and \texttt{the CAT} would be listed in addition to any
        occurrences of \texttt{the cat}.


\item \verb+grep -sn "the {1,}cat" *.txt+

        This command searches all \textbf{.txt} files in the current
        directory and in all subdirectories (recursively) for the
        pattern. The pattern consists of the word \texttt{the},
        followed by one or more spaces, and followed by the word
        \texttt{cat}. Therefore, it would match lines that contain
        \texttt{the cat} or \texttt{the\ \ \ cat}. The
        ``\verb+filename(linenumber) : +'' string is prepended to
        each line of each file in which the pattern is found.


\item \verb+grep -i "[a-z][a-z0-9_]{0,}(" *.c+

        This command searches all \textbf{.c} files in the current
        directory for function prototypes and function declarations.
        The pattern matches any string that begins with a letter, is
        followed by zero or more letters, numbers, or underscores, and
        ends with an open parenthesis.


\item \verb+foo | grep "&cont\."+

        This command searches the output of \textbf{foo} for the
        ``\verb+&cont.+'' string. Note that the period in the pattern
        was escaped with a backslash. The \textbf{grep} command would
        interpret the ``\verb+&cont.+'' pattern as meaning the
        ``\verb+&cont+'' string followed by any character.


\item \verb+grep "^Usage$" *.doc+

        This command searches all \texttt{.doc} files in the current
        directory for lines that consist of nothing but the string
        ``\verb+Usage+''.


\item \verb+grep "streams\[" *.c+

        This command searches all C files in the current directory for
        lines that contain the "streams[" string. Note that the
        ``\verb+[+'' character has to be escaped in the pattern so
        that it is interpreted by \textbf{grep} as a bracket and not
        as the beginning of a set or range.


\item \verb+grep -v "^$" *.doc+

        This command searches all .doc files in the current directory
        and lists all lines that are not blank. Note that the
        \verb+^$+ pattern matches any blank line.

\end{enumerate}
