Functions for matching text from the start of the input stream.
Matching functions are the main way of processing a string input
stream sin. Each matching function can recognize and extract some
particular kind of input from the start of the input stream. We say that some
matchers are strong and some are weak:
- Strong Matcher
- On success, always matches at least some text.
- Signature: (match-foo ... sin) → (mv match sin)
- Examples: sin-match-lit, sin-match-charset*, ...
- Weak Matcher
- May succeed even without matching any text.
- Signature: (match-foo ... sin) → (mv okp match sin)
- Example: sin-match-until-lit
In either case, the match returned is either
- nil, to indicate that no text is matched, or
- a non-empty string with text extracted from the start of the stream,
and the resulting sin is the updated input stream: when no text was
matched, sin is unchanged; otherwise it is advanced just past whatever
text was matched.
Matching functions generally satisfy several basic properties that are
described in def-match-thms.
- Match anything that occurs up until the first occurrence of a
particular string literal.
- Match exactly some particular string literal.
- Match all leading characters in some charset-p.
- Match any one of several string literals.
- Match anything that occurs up to, and including, the first occurrence
of a particular string literal.
- Prove basic properties about a matching function.
- Match everything that remains, no matter what it is.