1# $EPIC: prefix,v 1.3 2002/01/13 00:27:11 anders Exp $
2Synopsis:
3   $prefix(<word list>)
4
5Technical:
6   * If the <word list> argument is omitted the empty string is returned.
7   * The return value of this function is whatever string is the common
8     initial substring (CIS) of all of the words in <word list>.  If there
9     is no CIS in <word list>, the empty string is returned.
10   * This function uses an O(M*N) algorithm where M is the number of words
11     in <word list> and N is the length of the first word in <word list>.
12     Take this into consideration when planning.
13
14Practical:
15   This function can be used to do pseudo-completion.  To explain,
16   consider if you are working on a tab completion script and the user
17   types "foo" and presses tab.  Normally you would extract from $onchannel()
18   everything that matched "foo*", but what if that returns more than one
19   word?  It is considerate to the user to complete as much as possible for
20   them and then prompt them for the rest.  So let's say that you had two
21   users, "foobar" and "foobaz".  When the user pressed <tab> after typing
22   "foo" you would do something like this:
23
24	# Some code goes here to put "foo" in $input.
25	@ users = filter($input* $onchannel())
26	@ result = prefix($users)
27	if (numwords($users) > 1) { beep }
28	# Some code goes here to remove the 'foo' from the input
29	#   line and paste $result in its place.
30
31   $result will contain "fooba" because "fooba" is the CIS of the word
32   list (foobar foobaz).  So when the user presses <tab> you will put the
33   string "fooba" in place of "foo" and beep to let them know that it is
34   not an exact match.  You could use $users to tell them what their options
35   are, if you wanted to.
36
37   If the user typed something like "boo" and there were no users on the
38   channel whose nickname started with "boo", then $result would be the
39   empty string.  You could trap that as well and give the user an error
40   message.
41
42Returns:
43   The Common Initial Substring (CIS) of all of the words in <word list>
44
45Examples:
46   $prefix(foobar foobaz foobooya)	returns "foob"
47   $prefix(one two three)               returns the empty string.
48
49See Also:
50   onchannel(6); filter(6); numwords(6); beep(2)
51