LIST match_template(STRING string, STRING template)
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.
General information on matching can be found in the section Matching Conventions. Templates are composed of word-patterns and wildcards. Word-patterns may contain a mix of the partial-match operator and the or operator.
A word-pattern is any sequence of characters bounded by spaces, or the beginning or end of the string. The pattern may include a question mark ('?'), which is the partial-match operator; or it may include any number of pipe characters ('|'), which is the or operator. The result from a word-pattern match is the string which matched the word-pattern.
The partial-match operator is used to indicate that partial matches that extend at least as far as the question mark are ok. For instance, the word-pattern "ex?am" matches any of the words "ex", "exa" and "exam".
The or operator is used to group more than one word where any of the words in the group can be matched as one word. For instance, the template "this|that|there" would match "this" OR "that" OR "there".
Wildcards can be either simple or coupled. A simple wildcard is represented by an asterix ('*'). A simple wildcard matches any number of words in string, and must be bounded by spaces or the beginning or end of the template. If the wildcard is followed in the template by a word-pattern, then it can also match a quoted wildcard match.
A quoted wildcard match is just like a ColdC 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 following template using a simple wildcard "* bar" matches any of the following strings:
foo bar
foo baz bar
"foo bar " baz" bar
"foo baz bar
Matching against a simple wildcard produces one result per wildcard--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 result, 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 strings, the text before the equal sign and the text after it. Any spaces surrounding the equal sign in the matched string are ignored and do not show up in the results. 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.
Examples:
match_template("@descr me as foobar", "@desc?ribe * as *")
=> ["@descr", "me", "as", "foobar"]
match_template("@desc \"as is\" as foobar", "@desc?ribe * as *")
=> ["@desc", "as is", "as", "foobar"]
match_template("@desc \"as\" is as foobar", "@desc?ribe * as *")
=> 0
match_template("@desc \"as" is as foobar", "@desc?ribe * as *")
=> ["@desc", "\"as\" is", "as", "foobar"]
match_template("@descr me =foobar", "@desc?ribe *=*")
=> ["@descr", "me", "foobar"]
match_template("@desc "2+2=4"= an equation", "@desc?ribe *=*")
=> ["@desc", "2+2=4", "an equation"]
match_template("look at rose", "l?ook|ex?amine *")
=> ["look", "at rose"]
crypt() | explode() | lowercase() | match_begin() | match_pattern() | match_regexp() | match_template() | pad() | regexp() | strcmp() | strfmt() | strgraft() | strlen() | strsed() | strsub() | substr() | uppercase() | match_crypted() | split() | stridx()