bool uwildmat(const char *text, const char *pattern);
bool uwildmat_simple(const char *text, const char *pattern);
enum uwildmat uwildmat_poison(const char *text, const char *pattern);
uwildmat_simple is identical to uwildmat except that neither "!" nor "," have any special meaning and 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.
uwildmat_poison works similarly to uwildmat, except that "@" as the first character of one of the patterns in the expression (see below) ``poisons'' the match if it matches. uwildmat_poison returns UWILDMAT_MATCH if the expression matches the text, UWILDMAT_FAIL if it doesn't, and UWILDMAT_POISON if the expression doesn't match because a poisoned pattern matched the text. These enumeration constants are defined in the inn/libinn.h header.
In order to include a literal "]" character in the set, it must be the first character of the set (possibly following "^"); for example, "a]" matches either "]" or "a". To include a literal "-" 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.
In addition, "!" (and possibly "@") 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 "a" matches only the text "a"; it doesn't match "ab" or "ba" or even "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 "news.misc". The expression "*" matches this text, of course, as does "comp.*,news.*" (because the second pattern matches). "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. "news.*,!news.misc,*.misc" does match this text, since the rightmost matching pattern is not negated.
Note that the expression "!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. "*,!news.misc", on the other hand, is a useful pattern that matches anything except "news.misc".
"!" has significance only as the first character of a pattern; anywhere else in the pattern, it matches a literal "!" in the text like any other non-metacharacter.
If the uwildmat_poison interface is used, then "@" behaves the same as "!" except that if an expression fails to match because the rightmost matching pattern began with "@", UWILDMAT_POISON is returned instead of UWILDMAT_FAIL.
If the uwildmat_simple interface is used, the matching rules are the same as above except that none of "!", "@", or "," have any special meaning at all and only match those literal characters.
Lars Mathiesen <firstname.lastname@example.org> 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 <email@example.com> added minus sign and close bracket handling in June, 1991.
Russ Allbery <firstname.lastname@example.org> added support for comma-separated patterns and the "!" and "@" 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 uwildmat and the like rather than wildmat to distinguish them from the 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 8567 2009-08-15 07:03:37Z iulius $