.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "match 1"
.TH match 1 "2018-10-09" "Mail Avenger 0.8.5" "Mail Avenger 0.8.5"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
match \- Match strings against glob paterns
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
match [\-gilrqs] [\-n <n>] [\-c \fIcmd\fR] [\-x \fIcode\fR] {[\-p] \fIpattern\fR | \-f <file>} \fIstr1\fR [\fIstr2\fR ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
match checks strings against \fIpattern\fR, which should be a shell-like
glob pattern.  \fIpattern\fR may contain the following special
characters:
.IP "\fB?\fR" 4
.IX Item "?"
A \f(CW\*(C`?\*(C'\fR character in \fIpattern\fR matches any single character in the
string, except that the \f(CW\*(C`/\*(C'\fR character is only matched if match was
given the \fB\-s\fR option.
.IP "\fB*\fR" 4
.IX Item "*"
A \f(CW\*(C`*\*(C'\fR character in \fIpattern\fR matches zero or more characters in the
string.  The exception is that it will only match \f(CW\*(C`/\*(C'\fR characters if
match was given the \fB\-s\fR option.
.IP "\fB[...]\fR" 4
.IX Item "[...]"
A set of characters between square brackets matches any character in
the set.  In addition, the \f(CW\*(C`\-\*(C'\fR character can be used to specify a
range.  For example \f(CW\*(C`[+e0\-3]\*(C'\fR would match any of the characters \f(CW\*(C`+\*(C'\fR,
\&\f(CW\*(C`e\*(C'\fR, \f(CW0\fR, \f(CW1\fR, \f(CW2\fR, or \f(CW3\fR in the input string.  To include a
hyphen (\f(CW\*(C`\-\*(C'\fR) in the set of characters matched, either include the
hyphen first or last, or escape it with a \f(CW\*(C`\e\*(C'\fR.
.IP "\fB[!...]\fR" 4
.IX Item "[!...]"
A character class preceded by a \f(CW\*(C`!\*(C'\fR matches any character but those
specified in the class.  The exception is that the negated character
class will match a \f(CW\*(C`/\*(C'\fR only if match was given the \fB\-s\fR option.
.IP "\fB\e\fR\fIc\fR" 4
.IX Item "c"
The backslash character escapes the next character \fIc\fR.  Thus, to
match a literal \f(CW\*(C`*\*(C'\fR, you would use the pattern \f(CW\*(C`\e*\*(C'\fR.
.PP
match prints each string that matches \fIpattern\fR, one per line, and
exits 0 if one or more strings matched.  If no string matches, match
exits with status 67 (or whatever alternate status was specified by
the \fB\-x\fR flag).  If the \fB\-n\fR \fIn\fR flag was specified, match prints
only the text that matched the \fIn\fRth occurrence of \f(CW\*(C`*\*(C'\fR in the
patten.
.SS "\s-1OPTIONS\s0"
.IX Subsection "OPTIONS"
.IP "\fB\-f\fR \fIfile\fR" 4
.IX Item "-f file"
Specifies that the pattern should be read from \fIfile\fR.  match will
read each line of the file and consider it as pattern to match against
the argument strings.  For each argument string, match stops when it
hits the first matching line of the file.  If \fIfile\fR does not exist,
match exits 67, or whatever code was specified by \fB\-x\fR.
.IP "\fB\-g\fR" 4
.IX Item "-g"
Normally, the \fB\-n\fR option selects text matching particular \f(CW\*(C`*\*(C'\fR
characters in the patern.  \fB\-g\fR changes this behavior to use
parentheses for grouping.  Thus, for instance, the text \f(CW\*(C`foo.c\*(C'\fR would
match pattern \f(CW\*(C`*(.[ch])\*(C'\fR, and the output with option \fB\-n 1\fR would be
\&\f(CW\*(C`.c\*(C'\fR.  To include a literal \f(CW\*(C`(\*(C'\fR or \f(CW\*(C`)\*(C'\fR in the pattern with the
\&\fB\-g\fR option, you must precede the character with a \f(CW\*(C`\e\*(C'\fR.
.IP "\fB\-i\fR" 4
.IX Item "-i"
Makes the match case insensitive.  \fIstr\fR will be considered to match
if any variation on its capitalization would match.  For example,
string \f(CW\*(C`G\*(C'\fR would match pattern \f(CW\*(C`[f\-h]\*(C'\fR.
.IP "\fB\-l\fR" 4
.IX Item "-l"
When a pattern matches the string in more than one way, the \fB\-l\fR flag
says to assign as much text as possible to the leftmost \f(CW\*(C`*\*(C'\fRs in the
pattern.  For example, pattern \f(CW\*(C`*+*\*(C'\fR would match text \f(CW\*(C`a+b+c\*(C'\fR, and
the first \f(CW\*(C`*\*(C'\fR would match \f(CW\*(C`a+b\*(C'\fR.  This behavior is the default, thus
\&\fB\-l\fR's effect is only to undo a previous \fB\-r\fR flag.
.IP "\fB\-n\fR \fIn\fR" 4
.IX Item "-n n"
With this flag, match prints the text that matched the \fIn\fRth \f(CW\*(C`*\*(C'\fR in
the pattern, as opposed to printing the whole string.  The leftmost
\&\f(CW\*(C`*\*(C'\fR corresponds to \fB\-n 1\fR.  Specifying \fB\-n 0\fR causes match to print
the whole matching string.  Specifying \fB\-n \-1\fR or using a value
greater than the number of \f(CW\*(C`*\*(C'\fRs in the pattern causes match not to
print anything, in which case you can still use the exit status to see
if there is a match.  The default value for \fIn\fR is 0, unless \fB\-g\fR
has also been specified, in which case the default is 1.
.IP "\fB\-c\fR \fIcommand\fR" 4
.IX Item "-c command"
When \fB\-c\fR is specified, match runs \fIcommand\fR with the system shell
(\fI/bin/sh\fR), giving it as argument \f(CW$0\fR the full string that matched,
and as arguments \f(CW$1\fR, \f(CW$2\fR, etc., the parts of the string that matched
any \f(CW\*(C`*\*(C'\fRs in \fIpattern\fR.  If the command does not exit with status 0,
match will exit immediately, before processing further matches, with
whatever status \fIcommand\fR returned.  The \fB\-c\fR and \fB\-n\fR flags are
mutually exclusive.
.IP "\fB\-p\fR \fIpattern\fR" 4
.IX Item "-p pattern"
Specifies the pattern to match against.  The \fB\-p\fR flag is optional;
you can specify \fIpattern\fR as the first argument following the
options.  However, if you want to try matching the same input string
against multiple patterns, then you must specify each pattern with a
\&\fB\-p\fR flag.
.IP "\fB\-q\fR" 4
.IX Item "-q"
This option is synonymous with \fB\-n \-1\fR; it suppresses output when
there is a match.  You can still determine whether a match occurred by
the exit status.
.IP "\fB\-r\fR" 4
.IX Item "-r"
When a pattern matches the string in more than one way, the \fB\-r\fR flag
says to assign as much text as possible to the rightmost \f(CW\*(C`*\*(C'\fRs in the
pattern.  For example, with \fB\-r\fR, pattern \f(CW\*(C`*+*\*(C'\fR would match text
\&\f(CW\*(C`a+b+c\*(C'\fR with the \f(CW\*(C`*\*(C'\fR matching \f(CW\*(C`a\*(C'\fR, and the second matching \f(CW\*(C`b+c\*(C'\fR.
.IP "\fB\-s\fR" 4
.IX Item "-s"
Ordinarily, \f(CW\*(C`*\*(C'\fR, \f(CW\*(C`?\*(C'\fR, and negated character classes (\f(CW\*(C`[!...]\*(C'\fR) do
not match \f(CW\*(C`/\*(C'\fR characters.  \fB\-s\fR changes this behavior to match
slashes.
.IP "\fB\-x\fR \fIcode\fR" 4
.IX Item "-x code"
By default, when there is no match, match exits with status 67.  With
this option, match exits with status \fIcode\fR, instead.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Suppose you have a directory with a bunch of files ending \fI.c\fR and
\&\fI.o\fR.  If, for each file named \fIfoo.c\fR you want to attempt to delete
the file \fIfoo.o\fR, you can run the following command:
.PP
.Vb 1
\&     match \-p \*(Aq*.c\*(Aq \-c \*(Aqrm \-f $1.o\*(Aq *.c
.Ve
.PP
Servers running the mailman list manager often send mail from bounce
addresses of the form \fIlistname\fR\fB\-bounces@host.com\fR.  If you
subscribe to multiple lists on the same server, the mailman interface
makes it easier if you subscribe under the same address.  To split the
mail into multiple folders based on the bounce address in the
environment variable \fB\s-1SENDER\s0\fR, you might chose a mailbox with the
following shell code:
.PP
.Vb 2
\&     name=\`match \-n1 "*\-bounces@host.com" "$SENDER"\` \e
\&          && echo "$HOME/Mail/incoming/host\-$name.spool"
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBavenger\fR\|(1),
\&\fBavenger.local\fR\|(8)
.PP
The Mail Avenger home page: <http://www.mailavenger.org/>.
.SH "AUTHOR"
.IX Header "AUTHOR"
David Mazie\*`res