Custom Completers Completion Functions

2.5.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 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_completion_function (), is used.

Custom Completers

Completion Functions