=head1 NAME

uwildmat, uwildmat_simple, uwildmat_poison - Perform wildmat matching

=head1 SYNOPSIS

B<#include E<lt>libinn.hE<gt>>

B<bool uwildmat(const char *>I<text>B<, const char *>I<pattern>B<);>

B<bool uwildmat_simple(const char *>I<text>B<, const char *>I<pattern>B<);>

B<enum uwildmat uwildmat_poison(const char *>I<text>B<,
const char *>I<pattern>B<);>

=head1 DESCRIPTION

B<uwildmat> compares I<text> against the wildmat expression I<pattern>,
returning true if and only if the expression matches the text.  C<@> has
no special meaning in I<pattern> when passed to B<uwildmat>.  Both I<text>
and I<pattern> are assumed to be in the UTF-8 character encoding, although
malformed UTF-8 sequences are treated in a way that attempts to be mostly
compatible with single-octet character sets like ISO 8859-1.  (In other
words, if you try to match ISO 8859-1 text with these routines everything
should work as expected unless the ISO 8859-1 text contains valid UTF-8
sequences, which thankfully is somewhat rare.)

B<uwildmat_simple> is identical to B<uwildmat> except that neither C<!>
nor C<,> have any special meaning and I<pattern> is always treated as a
single pattern.  This function exists solely to support legacy interfaces
like NNTP's XPAT command, and should be avoided when implementing new
features.

B<uwildmat_poison> works similarly to B<uwildmat>, except that C<@> as the
first character of one of the patterns in the expression (see below)
"poisons" the match if it matches.  B<uwildmat_poison> returns
B<UWILDMAT_MATCH> if the expression matches the text, B<UWILDMAT_FAIL> if
it doesn't, and B<UWILDMAT_POISON> if the expression doesn't match because
a poisoned pattern matched the text.  These enumeration constants are
defined in the B<libinn.h> header.

=head1 WILDMAT EXPRESSIONS

A wildmat expression follows rules similar to those of shell filename
wildcards but with some additions and changes.  A wildmat I<expression> is
composed of one or more wildmat I<patterns> separated by commas.  Each
character in the wildmat pattern matches a literal occurance of that same
character in the text, with the exception of the following metacharacters:

=over 8

=item ?

Matches any single character (including a single UTF-8 multibyte
character, so C<?> can match more than one byte).

=item *Z<>

Matches any sequence of zero or more characters.

=item \

Turns off any special meaning of the following character; the following
character will match itself in the text.  C<\> will escape any character,
including another backslash or a comma that otherwise would separate a
pattern from the next pattern in an expression.  Note that C<\> is not
special inside a character range (no metacharacters are).

=item [...]

A character set, which matches any single character that falls within that
set.  The presence of a character between the brackets adds that character
to the set; for example, C<[amv]> specifies the set containing the
characters C<a>, C<m>, and C<v>.  A range of characters may be specified
using C<->; for example, C<[0-5abc]> is equivalent to C<[012345abc]>.  The
order of characters is as defined in the UTF-8 character set, and if the
start character of such a range falls after the ending character of the
range in that ranking the results of attempting a match with that pattern
are undefined.

In order to include a literal C<]> character in the set, it must be the
first character of the set (possibly following C<^>); for example, C<[]a]>
matches either C<]> or C<a>.  To include a literal C<-> character in the
set, it must be either the first or the last character of the set.
Backslashes have no special meaning inside a character set, nor do any
other of the wildmat metacharacters.

=item [^...]

A negated character set.  Follows the same rules as a character set above,
but matches any character B<not> contained in the set.  So, for example,
C<[^]-]> matches any character except C<]> and C<->.

=back

In addition, C<!> (and possibly C<@>) have special meaning as the first
character of a pattern; see below.

When matching a wildmat expression against some text, each comma-separated
pattern is matched in order from left to right.  In order to match, the
pattern must match the whole text; in regular expression terminology, it's
implicitly anchored at both the beginning and the end.  For example, the
pattern C<a> matches only the text C<a>; it doesn't match C<ab> or C<ba>
or even C<aa>.  If none of the patterns match, the whole expression
doesn't match.  Otherwise, whether the expression matches is determined
entirely by the rightmost matching pattern; the expression matches the
text if and only if the rightmost matching pattern is not negated.

For example, consider the text C<news.misc>.  The expression C<*> matches
this text, of course, as does C<comp.*,news.*> (because the second pattern
matches).  C<news.*,!news.misc> does not match this text because both
patterns match, meaning that the rightmost takes precedence, and the
rightmost matching pattern is negated.  C<news.*,!news.misc,*.misc> does
match this text, since the rightmost matching pattern is not negated.

Note that the expression C<!news.misc> can't match anything.  Either the
pattern doesn't match, in which case no patterns match and the expression
doesn't match, or the pattern does match, in which case because it's
negated the expression doesn't match.  C<*,!news.misc>, on the other hand,
is a useful pattern that matches anything except C<news.misc>.

C<!> has significance only as the first character of a pattern; anywhere
else in the pattern, it matches a literal C<!> in the text like any other
non-metacharacter.

If the B<uwildmat_poison> interface is used, then C<@> behaves the same as
C<!> except that if an expression fails to match because the rightmost
matching pattern began with C<@>, B<UWILDMAT_POISON> is returned instead of
B<UWILDMAT_FAIL>.

If the B<uwildmat_simple> interface is used, the matching rules are the
same as above except that none of C<!>, C<@>, or C<,> have any special
meaning at all and only match those literal characters.

=head1 BUGS

All of these functions internally convert the passed arguments to const
unsigned char pointers.  The only reason why they take regular char
pointers instead of unsigned char is for the convenience of INN and other
callers that may not be using unsigned char everywhere they should.  In a
future revision, the public interface should be changed to just take
unsigned char pointers.

=head1 HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> in 1986, and posted to Usenet
several times since then, most notably in comp.sources.misc in
March, 1991.

Lars Mathiesen <thorinn@diku.dk> enhanced the multi-asterisk failure
mode in early 1991.

Rich and Lars increased the efficiency of star patterns and reposted it to
comp.sources.misc in April, 1991.

Robert Elz <kre@munnari.oz.au> added minus sign and close bracket handling
in June, 1991.

Russ Allbery <rra@stanford.edu> added support for comma-separated patterns
and the C<!> and C<@> metacharacters to the core wildmat routines in July,
2000.  He also added support for UTF-8 characters, changed the default
behavior to assume that both the text and the pattern are in UTF-8, and
largely rewrote this documentation to expand and clarify the description
of how a wildmat expression matches.

Please note that the interfaces to these functions are named B<uwildmat>
and the like rather than B<wildmat> to distinguish them from the
B<wildmat> function provided by Rich $alz's original implementation.
While this code is heavily based on Rich's original code, it has
substantial differences, including the extension to support UTF-8
characters, and has noticable functionality changes.  Any bugs present in
it aren't Rich's fault.

$Id: uwildmat.pod 5533 2002-08-10 18:51:37Z rra $

=head1 SEE ALSO

grep(1), fnmatch(3), regex(3), regexp(3).

=cut