# $EPIC: match.txt,v 1.2 2006/08/01 05:15:58 sthalik Exp $
======Synopsis:======
$__match__(<pattern> <word list>)

======Technical:======
   * If the <pattern> argument is omitted the empty string is returned.
   * <word list> contains zero or more space separated "extended words"
   * Each word in <word list> is taken as literal text, and each are matched against <pattern>.
   * If none of the words in <word list> are matched by <pattern>, then the return value of __match__ is 0 (zero).
   * Otherwise, the return value is the index of the first word in <word list> that is matched by <pattern>, COUNTING FROM ONE, AND NOT COUNTING FROM ZERO.
   * It is important to remember that other word functions, such as $[[word]]() count from zero.  You must subtract one from the return value of this function before you can use it in some other functions.
   * If <pattern> does not contain any wildcards, you should use the $[[findw]]() function instead.
   * If <word list> contains only one word, you should use the =~ operator instead.

======Practical:======
This function can be used to match a pattern against a list of words
to see if any of them match.  Since ircII does not include the =~ operator,
this was the standard way to do pattern matching of one pattern to one
string in scripts.  Also, since ircII does not include the [[findw]]
function, this was the standard way to determine if a literal word was
present in a literal word list.  In many cases, the __match__ function 
has been superseded by other functions that do the job better.

======Returns:======
<file>
 0   no matches found
>0   index to first match in list -- counting from one!
</file>

======Examples:======
<file>
$match(*oo* blah foo booya)                              returns 2
$match(*oo* blah fubar erf)                              returns 0
</file>

======History:======
This function first appeared in ircII-2.1.5