How Completing Works
--------------------

   In order to complete some text, the full list of possible completions
must be available.  That is, it is not possible to accurately expand a
partial word without knowing all of the possible words which make sense
in that context.  The Readline library provides the user interface to
completion, and two of the most common completion functions:  filename
and username.  For completing other types of text, you must write your
own completion function.  This section describes exactly what such
functions must do, and provides an example.

   There are three major functions used to perform completion:

  1. The user-interface function `rl_complete ()'.  This function is
     called with the same arguments as other Readline functions
     intended for interactive use:  COUNT and INVOKING_KEY.  It
     isolates the word to be completed and calls `completion_matches
     ()' to generate a list of possible completions.  It then either
     lists the possible completions, inserts the possible completions,
     or actually performs the completion, depending on which behavior
     is desired.

  2. The internal function `completion_matches ()' uses your
     "generator" function to generate the list of possible matches, and
     then returns the array of these matches.  You should place the
     address of your generator function in
     `rl_completion_entry_function'.

  3. The generator function is called repeatedly from
     `completion_matches ()', returning a string each time.  The
     arguments to the generator function are TEXT and STATE.  TEXT is
     the partial word to be completed.  STATE is zero the first time
     the function is called, allowing the generator to perform any
     necessary initialization, and a positive non-zero integer for each
     subsequent call.  When the generator function returns `(char
     *)NULL' this signals `completion_matches ()' that there are no
     more possibilities left.  Usually the generator function computes
     the list of possible completions when STATE is zero, and returns
     them one at a time on subsequent calls.  Each string the generator
     function returns as a match must be allocated with `malloc()';
     Readline frees the strings when it has finished with them.


 - Function: int rl_complete (int ignore, int invoking_key)
     Complete the word at or before point.  You have supplied the
     function that does the initial simple matching selection algorithm
     (see `completion_matches ()').  The default is to do filename
     completion.

 - Variable: Function * rl_completion_entry_function
     This is a pointer to the generator function for `completion_matches
     ()'.  If the value of `rl_completion_entry_function' is `(Function
     *)NULL' then the default filename generator function,
     `filename_entry_function ()', is used.