\chapter{Searching Image Metadata With {\kw igrep}}
\label{chap:igrep}
\indexapi{igrep}

%\section{Overview}

The {\cf igrep} program search one or more image files for metadata
that match a string or regular expression.



\section{Using {\cf igrep}}

The {\cf igrep} utility is invoked as follows:

\bigskip

\hspace{0.25in} {\cf igrep} [\emph{options}] \emph{pattern} \emph{filename} ...

\medskip

Where \emph{pattern} is a POSIX.2 regular expression (just like the
Unix/Linux {\cf grep(1)} command), and \emph{filename} (and any
following names) specify images or directories that should be searched.
An image file will ``match'' if any of its metadata contains values
contain substring that are recognized regular expression.  The image
files may be of any format recognized by \product (i.e., for which
\ImageInput plugins are available).

Example:

\begin{code}
    $ igrep Jack *.jpg 
    bar.jpg: Keywords = Carly; Jack
    foo.jpg: Keywords = Jack
    test7.jpg: ImageDescription = Jack on vacation
\end{code}

% $



\section{{\cf igrep} command-line options}

\apiitem{--help}
Prints usage information to the terminal.
\apiend

\apiitem{-d}
Print directory names as it recurses.  This only happens if the {\cf -r}
option is also used.
\apiend

\apiitem{-E}
Interpret the pattern as an extended regular expression (just like
{\cf egrep} or {\cf grep -E}).
\apiend

\apiitem{-f}
Match the expression against the filename, as well as the metadata
within the file.
\apiend

\apiitem{-i}
Ignore upper/lower case distinctions.  Without this flag, the expression
matching will be case-sensitive.
\apiend

\apiitem{-l}
Simply list the matching files by name, surpressing the normal output
that would include the metadata name and values that matched.
For example:

\begin{code}
    $ igrep Jack *.jpg 
    bar.jpg: Keywords = Carly; Jack
    foo.jpg: Keywords = Jack
    test7.jpg: ImageDescription = Jack on vacation

    $ igrep -l Jack *.jpg
    bar.jpg
    foo.jpg
    test7.jpg
\end{code}

\apiend

\apiitem{-r}
Recurse into directories.  If this flag is present, any files specified
that are directories will have any image file contained therein to be
searched for a match (an so on, recursively).
\apiend

\apiitem{-v}
Invert the sense of matching, to select image files that \emph{do not}
match the expression.
\apiend

