Prev: match_regexp
match_template(template, string)This function matches the template template against the command string. The return value of
match_template() is a list of
fields resulting from the template match, or 0 if the match fails
or if template is an invalid template.
A template is a sequence of word-patterns and wildcards separated by spaces, with wildcards never occurring more than one at a time. A word-pattern is a sequence of words separated by pipe characters (|). A word is a sequence of alphanumeric characters, with an optional question mark (?) indicating the beginning of an allowed partial match. A wildcard is either a simple wildcard, represented by an asterix (*) or a coupled wildcard, represented by the three-character sequence *=*.
That definition of a template is confusing, so we will now go back and explain each component of a template in more detail.
A word-pattern is a list of words separated by pipe characters.
A word-pattern matches any of the words contained in it. The
word-pattern "look|examine" matches either of the words
"look" or "examine". The word separator for template
matching is always a space.
A word can include a question mark (?) to indicate that partial
matches that extend at least as far as the question mark are okay. The
word pattern "look|ex?amine" matches any of the words
"look", "ex", "exa", "exam", "exami",
"examin", and "examine".
When a word-pattern successfully matches a word in string, it results in a field, or string in the returned list. This field contains the word which matched the word-pattern.
A simple wildcard is represented by an asterix (*). A simple wildcard matches any number of words in string. If the wildcard is followed by a word-pattern in template, then it can also match a quoted wildcard match.
A quoted wildcard match is just like a C-- string literal: it
begins and ends with a double quote ("), and can include a
literal double quote or backslash by preceding the character with a
backslash (\). If the simple wildcard is followed by a
word-pattern, and the words in string that the wildcard would
match begin with a double quote, then the match must be a quoted
wildcard match or the match fails, even if the match would have
succeeded if the words were not treated as a quoted wildcard match.
However, if the words that the wildcard would match begin with a
backslash followed by a double quote, then the backslash is ignored and
the double quote and the text following it are treated as regular words.
The template "* bar" matches any of the following strings:
foo bar foo baz bar "foo bar \\ \" baz" bar \"foo baz barMatching against a simple wildcard produces one field, the words that the simple wildcard matched. If the wildcard matches a quoted wildcard match, then the beginning and ending double quotes are stripped out of the resulting field, as well as any backslashes used to escape characters inside the double quotes.
A coupled wildcard is represented by the three-character sequence *=*. It matches any sequence of words containing an equal sign (=), and results in two fields, the text before the equal sign and the text after it. Any spaces surrounding the equal sign are ignored and do not show up in the resulting fields. The text before the equal sign can be a quoted wildcard match (as before, if it begins with a double quote, then it must be a quoted wildcard match or the match fails, unless the initial double quote is escaped by a backslash). If the coupled wildcard is followed by a word pattern, then the text after the equal sign can also be a quoted wildcard match.
The coupled wildcard is a special feature intended for parsing TinyMUD command formats. If possible, its use should be avoided.
If template is invalid, then the match usually fails, although this is not guaranteed.
Examples:
match_template("@desc?ribe * as *", "@descr me as foobar")
=> ["@descr", "me", "as", "foobar"]
match_template("@desc?ribe * as *", "@desc \"as is\" as foobar")
=> ["@desc", "as is", "as", "foobar"]
match_template("@desc?ribe * as *", "@desc \"as\" is as foobar")
=> 0
match_template("@desc?ribe * as *", "@desc \\\"as\" is as foobar")
=> ["@desc", "\"as\" is", "as", "foobar"]
match_template("@desc?ribe *=*", "@descr me =foobar")
=> ["@descr", "me", "foobar"]
match_template("@desc?ribe *=*", "@desc \"2+2=4\"= an equation")
=> ["@desc", "2+2=4", "an equation"]
match_template("l?ook|ex?amine *", "look at rose")
=> ["look", "at rose"]