uwildmat(3)

📦 version 2.6.4, in ubuntu jammy

✨ NAME ✨

uwildmat, uwildmat_simple, uwildmat_poison — bestie, these three do wildmat matching 💖 and honestly? they ate.

This is the uwildmat(3) page, straight out of the InterNetNews Documentation set. Sit down, grab a strawberry 🍓, we're gonna get through all of it together.

🦋 SYNOPSIS 🦋

#include <inn/libinn.h>

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);

Look at those signatures. Immaculate. ✨

🌸 DESCRIPTION 🌸

uwildmat compares text against the wildmat expression pattern, and it returns true if and only if the expression matches the text. That "if and only if" is doing heavy lifting, so clock it. 👑

Okay but here's the tea: "@" has no special meaning in pattern when you pass it to uwildmat. None. It's just a lil guy. 🙈

Both text and pattern are assumed to be in UTF-8 character encoding, although malformed UTF-8 sequences are treated in a way that tries to be mostly compatible with single-octet character sets like ISO 8859-1. In other words (and this is straight from the source, bestie, I'm not improvising): 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. 😮‍💨 so we're fine. probably.

uwildmat_simple is identical to uwildmat except that neither "!" nor "," have any special meaning, and pattern is always treated as a single pattern. She's giving legacy. 💀 This function exists solely to support legacy interfaces like NNTP's XPAT command, and it should be avoided when you're implementing new features. No cap. If you're building something fresh, do not reach for this one. 🙅‍♀️

uwildmat_poison works similarly to uwildmat, except that "@" as the first character of one of the patterns in the expression (scroll down for what "one of the patterns" means, bestie) "poisons" the match if it matches. Toxicity!! ☠️

And what does she return? Glad you asked:

  • UWILDMAT_MATCH — when the expression matches the text.
  • UWILDMAT_FAIL — when it doesn't.
  • UWILDMAT_POISON — when the expression doesn't match because a poisoned pattern matched the text.

These enumeration constants are defined in the inn/libinn.h header. 📌

🎀 WILDMAT EXPRESSIONS 🎀

A wildmat expression follows rules similar to those of shell filename wildcards, but with some additions and changes. She's the wildcard's cooler older sister. 💅

A wildmat expression is composed of one or more wildmat patterns separated by commas. Each character in the wildmat pattern matches a literal occurrence of that same character in the text, with the exception of the following metacharacters:

  • ? — Matches any single character (including a single UTF-8 multibyte character, so ? can match more than one byte). One char but make it spicy. ✨
  • * — Matches any sequence of zero or more characters. Zero!! She can match nothing at all and still be iconic.
  • \ — Turns off any special meaning of the following character; the following character will match itself in the text. \ 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 \ is not special inside a character range (no metacharacters are). 🚫
  • [...] — 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, [amv] specifies the set containing the characters "a", "m", and "v". A range of characters may be specified using -; for example, [0-5abc] is equivalent to [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. So like… don't do that. 🫠

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. Inside the brackets it's a whole different world, bestie. 🌈

  • [^...] — A negated character set. Follows the same rules as a character set above, but matches any character not contained in the set. So, for example, [^]-] matches any character except "]" and "-". She's the "everyone except y'all" of character sets. 💅

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". No partial credit. 😤

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. Rightmost wins. Periodt. 👑

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. slay.

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. She's a paradox, bestie. 💀

"*,!news.misc", on the other hand, is a useful pattern that matches anything except "news.misc". That one's the queen. 👑

"!" 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. Don't let her fool you from the middle of the pattern. 🙈

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. Poisoned. Contaminated. Rude. ☠️✨

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. Simple girl, simple life. 🎀

💀 BUGS 💀

Okay so, 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. Noted. Filed. On the list. 📝

🧚 HISTORY 🧚

A whole saga, honestly. The lore:

  • 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 <eagle@eyrie.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. king behavior. 👑

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 noticeable functionality changes. Any bugs present in it aren't Rich's fault. 🫶 Protect that man's reputation at all costs.

$Id: uwildmat.pod 10283 2018-05-14 12:43:05Z iulius $

🌈 SEE ALSO 🌈

Go read those too, bestie, they're all part of the family. 🦋

Okay that's the whole page!! 💖 This was uwildmat(3) from INN 2.6.4, dated 2018-05-14 — that's the version and the date, keep them in your notes, iykyk. Thanks for reading all the way to the bottom, you're genuinely the bestie of all time. Mwah. 💅✨🎀

📦 where this page comes from