Provided by: agrep_4.17-9_amd64 
NAME
agrep - search a file for a string or regular expression, with approximate matching
capabilities
SYNOPSIS
agrep [ -#cdehiklnpstvwxBDGIS ] pattern [ -f patternfile ] [ filename... ]
DESCRIPTION
agrep searches the input filenames (standard input is the default, but see a warning under
LIMITATIONS) for records containing strings which either exactly or approximately match a
pattern. A record is by default a line, but it can be defined differently using the -d
option (see below). Normally, each record found is copied to the standard output.
Approximate matching allows finding records that contain the pattern with several errors
including substitutions, insertions, and deletions. For example, Massechusets matches
Massachusetts with two errors (one substitution and one insertion). Running agrep -2
Massechusets foo outputs all lines in foo containing any string with at most 2 errors from
Massechusets.
agrep supports many kinds of queries including arbitrary wild cards, sets of patterns, and
in general, regular expressions. See PATTERNS below. It supports most of the options
supported by the grep family plus several more (but it is not 100% compatible with grep).
For more information on the algorithms used by agrep see Wu and Manber, "Fast Text
Searching With Errors," Technical report #91-11, Department of Computer Science,
University of Arizona, June 1991 (available by anonymous ftp from cs.arizona.edu in
agrep/agrep.ps.1), and Wu and Manber, "Agrep -- A Fast Approximate Pattern Searching
Tool", To appear in USENIX Conference 1992 January (available by anonymous ftp from
cs.arizona.edu in agrep/agrep.ps.2).
As with the rest of the grep family, the characters `$', `^', `∗', `[', `]', `^', `|',
`(', `)', `!', and `\' can cause unexpected results when included in the pattern, as these
characters are also meaningful to the shell. To avoid these problems, one should always
enclose the entire pattern argument in single quotes, i.e., 'pattern'. Do not use double
quotes (").
When agrep is applied to more than one input file, the name of the file is displayed
preceding each line which matches the pattern. The filename is not displayed when
processing a single file, so if you actually want the filename to appear, use /dev/null as
a second file in the list.
OPTIONS
-# # is a non-negative integer (at most 8) specifying the maximum number of errors
permitted in finding the approximate matches (defaults to zero). Generally, each
insertion, deletion, or substitution counts as one error. It is possible to adjust
the relative cost of insertions, deletions and substitutions (see -I -D and -S
options).
-c Display only the count of matching records.
-d 'delim'
Define delim to be the separator between two records. The default value is '$',
namely a record is by default a line. delim can be a string of size at most 8
(with possible use of ^ and $), but not a regular expression. Text between two
delim's, before the first delim, and after the last delim is considered as one
record. For example, -d '$$' defines paragraphs as records and -d '^From ' defines
mail messages as records. agrep matches each record separately. This option does
not currently work with regular expressions.
-e pattern
Same as a simple pattern argument, but useful when the pattern begins with a `-'.
-f patternfile
patternfile contains a set of (simple) patterns. The output is all lines that
match at least one of the patterns in patternfile. Currently, the -f option works
only for exact match and for simple patterns (any meta symbol is interpreted as a
regular character); it is compatible only with -c, -h, -i, -l, -s, -v, -w, and -x
options. see LIMITATIONS for size bounds.
-h Do not display filenames.
-i Case-insensitive search — e.g., "A" and "a" are considered equivalent.
-k No symbol in the pattern is treated as a meta character. For example, agrep -k
'a(b|c)*d' foo will find the occurrences of a(b|c)*d in foo whereas agrep
'a(b|c)*d' foo will find substrings in foo that match the regular expression
'a(b|c)*d'.
-l List only the files that contain a match. This option is useful for looking for
files containing a certain pattern. For example, " agrep -l 'wonderful' * " will
list the names of those files in current directory that contain the word
'wonderful'.
-n Each line that is printed is prefixed by its record number in the file.
-p Find records in the text that contain a supersequence of the pattern. For example,
agrep -p DCS foo will match "Department of Computer Science."
-s Work silently, that is, display nothing except error messages. This is useful for
checking the error status.
-t Output the record starting from the end of delim to (and including) the next delim.
This is useful for cases where delim should come at the end of the record.
-v Inverse mode — display only those records that do not contain the pattern.
-w Search for the pattern as a word — i.e., surrounded by non-alphanumeric characters.
The non-alphanumeric must surround the match; they cannot be counted as errors.
For example, agrep -w -1 car will match cars, but not characters.
-x The pattern must match the whole line.
-y Used with -B option. When -y is on, agrep will always output the best matches
without giving a prompt.
-B Best match mode. When -B is specified and no exact matches are found, agrep will
continue to search until the closest matches (i.e., the ones with minimum number of
errors) are found, at which point the following message will be shown: "the best
match contains x errors, there are y matches, output them? (y/n)" The best match
mode is not supported for standard input, e.g., pipeline input. When the -#, -c,
or -l options are specified, the -B option is ignored. In general, -B may be
slower than -#, but not by very much.
-Dk Set the cost of a deletion to k (k is a positive integer). This option does not
currently work with regular expressions.
-G Output the files that contain a match.
-Ik Set the cost of an insertion to k (k is a positive integer). This option does not
currently work with regular expressions.
-Sk Set the cost of a substitution to k (k is a positive integer). This option does
not currently work with regular expressions.
PATTERNS
agrep supports a large variety of patterns, including simple strings, strings with classes
of characters, sets of strings, wild cards, and regular expressions.
Strings
any sequence of characters, including the special symbols `^' for beginning of line
and `$' for end of line. The special characters listed above ( `$', `^', `∗', `[',
`^', `|', `(', `)', `!', and `\' ) should be preceded by `\' if they are to be
matched as regular characters. For example, \^abc\\ corresponds to the string
^abc\, whereas ^abc corresponds to the string abc at the beginning of a line.
Classes of characters
a list of characters inside [] (in order) corresponds to any character from the
list. For example, [a-ho-z] is any character between a and h or between o and z.
The symbol `^' inside [] complements the list. For example, [^i-n] denote any
character in the character set except character 'i' to 'n'. The symbol `^' thus
has two meanings, but this is consistent with egrep. The symbol `.' (don't care)
stands for any symbol (except for the newline symbol).
Boolean operations
agrep supports an `and' operation `;' and an `or' operation `,', but not a
combination of both. For example, 'fast;network' searches for all records
containing both words.
Wild cards
The symbol '#' is used to denote a wild card. # matches zero or any number of
arbitrary characters. For example, ex#e matches example. The symbol # is
equivalent to .* in egrep. In fact, .* will work too, because it is a valid
regular expression (see below), but unless this is part of an actual regular
expression, # will work faster.
Combination of exact and approximate matching
any pattern inside angle brackets <> must match the text exactly even if the match
is with errors. For example, <mathemat>ics matches mathematical with one error
(replacing the last s with an a), but mathe<matics> does not match mathematical no
matter how many errors we allow.
Regular expressions
The syntax of regular expressions in agrep is in general the same as that for
egrep. The union operation `|', Kleene closure `*', and parentheses () are all
supported. Currently '+' is not supported. Regular expressions are currently
limited to approximately 30 characters (generally excluding meta characters). Some
options (-d, -w, -f, -t, -x, -D, -I, -S) do not currently work with regular
expressions. The maximal number of errors for regular expressions that use '*' or
'|' is 4.
EXAMPLES
agrep -2 -c ABCDEFG foo
gives the number of lines in file foo that contain ABCDEFG within two errors.
agrep -1 -D2 -S2 'ABCD#YZ' foo
outputs the lines containing ABCD followed, within arbitrary distance, by YZ, with
up to one additional insertion (-D2 and -S2 make deletions and substitutions too
"expensive").
agrep -5 -p abcdefghij /path/to/dictionary/words
outputs the list of all words containing at least 5 of the first 10 letters of the
alphabet in order. (Try it: any list starting with academia and ending with
sacrilegious must mean something!)
agrep -1 'abc[0-9](de|fg)*[x-z]' foo
outputs the lines containing, within up to one error, the string that starts with
abc followed by one digit, followed by zero or more repetitions of either de or fg,
followed by either x, y, or z.
agrep -d '^From ' 'breakdown;internet' mbox
outputs all mail messages (the pattern '^From ' separates mail messages in a mail
file) that contain keywords 'breakdown' and 'internet'.
agrep -d '$$' -1 '<word1> <word2>' foo
finds all paragraphs that contain word1 followed by word2 with one error in place
of the blank. In particular, if word1 is the last word in a line and word2 is the
first word in the next line, then the space will be substituted by a newline symbol
and it will match. Thus, this is a way to overcome separation by a newline. Note
that -d '$$' (or another delim which spans more than one line) is necessary,
because otherwise agrep searches only one line at a time.
agrep '^agrep' <this manual>
outputs all the examples of the use of agrep in this man pages.
SEE ALSO
ed(1), ex(1), grep(1V), sh(1), csh(1).
BUGS/LIMITATIONS
Any bug reports or comments will be appreciated! Please mail them to sw@cs.arizona.edu or
udi@cs.arizona.edu
Regular expressions do not support the '+' operator (match 1 or more instances of the
preceding token). These can be searched for by using this syntax in the pattern:
'pattern(pattern)*'
(search for strings containing one instance of the pattern, followed by 0 or more
instances of the pattern).
The following can cause an infinite loop: agrep pattern * > output_file. If the number of
matches is high, they may be deposited in output_file before it is completely read leading
to more matches of the pattern within output_file (the matches are against the whole
directory). It's not clear whether this is a "bug" (grep will do the same), but be
warned.
The maximum size of the patternfile is limited to be 250Kb, and the maximum number of
patterns is limited to be 30,000.
Standard input is the default if no input file is given. However, if standard input is
keyed in directly (as opposed to through a pipe, for example) agrep may not work for some
non-simple patterns.
There is no size limit for simple patterns. More complicated patterns are currently
limited to approximately 30 characters. Lines are limited to 1024 characters. Records
are limited to 48K, and may be truncated if they are larger than that. The limit of
record length can be changed by modifying the parameter Max_record in agrep.h.
DIAGNOSTICS
Exit status is 0 if any matches are found, 1 if none, 2 for syntax errors or inaccessible
files.
AUTHORS
Sun Wu and Udi Manber, Department of Computer Science, University of Arizona, Tucson, AZ
85721. {sw|udi}@cs.arizona.edu.
Jan 17, 1992 AGREP(1)