# $EPIC: rmatch,v 1.5 2002/01/13 00:27:11 anders Exp $
Synopsis:
   $rmatch(<word> <pattern list>)

Technical:
   * If the <word> argument is omitted the empty string is returned.
   * <pattern list> contains zero or more space separated "extended words"
   * Each pattern in <pattern list> is taken as a wildcard pattern, which is
     matched against <word>, which is taken as literal text.
   * If none of the patterns in <pattern list> match <word>, then the return
     value of rmatch is 0 (zero).
   * Otherwise, the return value is the word from <pattern list> for the
     pattern which "best" matches <word>.  A pattern's "value" is the number
     of literal (non-wildcard) characters it contains.  The pattern that
     matches <word> and has the most "value" is the "best" match.
   * The return value begins counting words FROM ONE, like match.  You
     will have to subtract one from the return value before using it in some
     other functions, like $word().
   * If none of the patterns in <pattern list> contain wildcards, then you
     should use the $findw() function instead.
   * If <pattern list> contains only one word, you should use the =~ operator
     instead.

Practical:
   This function can be used to match a bunch of patterns against a single
   literal word.  This is often used to match the $userhost() value against
   a list of userhosts in an access list.  Since ircII does not include the
   =~ operator, this was the standard way to do pattern matching on one word
   against 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.  The rmatch function is still
   generally useful for matching one word against a list of patterns.

Returns:
    0   no matches found
   >0   index to "best" pattern in list -- counting from one!

Examples:
   $rmatch(one o* t* f*)				returns 1
   $rmatch(one z* t* f*)				returns 0
   $rmatch(one o* on* t* f*)				returns 2

History:
   This function first appeared in ircII.

See Also:
   match(6); filter(6); pattern(6); rfilter(6); 
   rpattern(6); findw(6)