(readline.info.gz) How Completing Works

Info Catalog

(readline.info.gz) Custom Completers

(readline.info.gz) Completion Functions

 
 2.6.1 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 bindable Readline
      functions: COUNT and INVOKING_KEY.  It isolates the word to be
      completed and calls `rl_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 `rl_completion_matches()' uses an
      application-supplied "generator" function to generate the list of
      possible matches, and then returns the array of these matches.
      The caller should place the address of its generator function in
      `rl_completion_entry_function'.
 
   3. The generator function is called repeatedly from
      `rl_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.  The generator function returns `(char *)NULL' to
      inform `rl_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.  Such a
      generator function is referred to as an "application-specific
      completion function".
 
 
  -- 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 `rl_completion_matches()').  The default is to do filename
      completion.
 
  -- Variable: rl_compentry_func_t * rl_completion_entry_function
      This is a pointer to the generator function for
      `rl_completion_matches()'.  If the value of
      `rl_completion_entry_function' is `NULL' then the default filename
      generator function, `rl_filename_completion_function()', is used.
      An "application-specific completion function" is a function whose
      address is assigned to `rl_completion_entry_function' and whose
      return values are used to  generate possible completions.
 

Info Catalog

(readline.info.gz) Custom Completers

(readline.info.gz) Completion Functions