Summary

###########################################################################

	File:     complete.icn

	Subject:  Procedure to complete partial input string

	Author:   Richard L. Goerwitz

	Date:     August 14, 1996

###########################################################################

   This file is in the public domain.

###########################################################################

	Version:  1.7

###########################################################################

	complete(s,st)	completes a s relative to a set or list of strings, st.
			Put differently, complete() lets you supply a
			partial string, s, and get back those strings in st
			that s is either equal to or a	substring of.

###########################################################################

  Lots of command interfaces allow completion of partial input.
  Complete() simply represents my personal sentiments about how this
  might best be done in Icon.  If you strip away the profuse comments
  below, you end up with only about thirty lines of actual source
  code.

  I have arranged things so that only that portion of an automaton
  which is needed to complete a given string is actually created and
  stored.  Storing automata for later use naturally makes complete()
  eat up more memory.  The performance gains can make it worth the
  trouble, though.  If, for some reason, there comes a time when it
  is advisable to reclaim the space occupied by complete's static
  structures, you can just call it without arguments.  This
  "resets" complete() and forces an immediate garbage collection.
  
 Example code:

      commands := ["run","stop","quit","save","load","continue"]
      while line := read(&input) do {
          cmds := list()
          every put(cmds, complete(line, commands))
          case *cmds of {
              0 : input_error(line)
              1 : do_command(cmds[1])
              default : display_possible_completions(cmds)
          }
          etc...

  More Iconish methods might include displaying successive
  alternatives each time the user presses the tab key (this would,
  however, require using the nonportable getch() routine).  Another
  method might be to use the first string suspended by complete().

  NOTE: This entire shebang could be replaced with a slightly slower
  and much smaller program suggested to me by Jerry Nowlin and Bob
  Alexander.

      procedure terscompl(s, st)
          suspend match(s, p := !st) & p
      end

  This program will work fine for lists with just a few members, and
  also for cases where s is fairly large.  It will also use much less
  memory.

###########################################################################

This file is part of the (main) package.

complete(s, st)