2.6.2 Completion Functions

Here is the complete list of callable completion functions present in Readline.

Function: int rl_complete_internal (int what_to_do)

Complete the word at or before point. what_to_do says what to do with the completion. A value of ‘?’ means list the possible completions. ‘TAB’ means do standard completion. ‘*’ means insert all of the possible completions. ‘!’ means to display all of the possible completions, if there is more than one, as well as performing partial completion. ‘@’ is similar to ‘!’, but possible completions are not listed if the possible completions share a common prefix.

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() and rl_completion_entry_function). The default is to do filename completion. This calls rl_complete_internal() with an argument depending on invoking_key.

Function: int rl_possible_completions (int count, int invoking_key)

List the possible completions. See description of rl_complete (). This calls rl_complete_internal() with an argument of ‘?’.

Function: int rl_insert_completions (int count, int invoking_key)

Insert the list of possible completions into the line, deleting the partially-completed word. See description of rl_complete(). This calls rl_complete_internal() with an argument of ‘*’.

Function: int rl_completion_mode (rl_command_func_t *cfunc)

Returns the apppriate value to pass to rl_complete_internal() depending on whether cfunc was called twice in succession and the values of the show-all-if-ambiguous and show-all-if-unmodified variables. Application-specific completion functions may use this function to present the same interface as rl_complete().

Function: char ** rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)

Returns an array of strings which is a list of completions for text. If there are no completions, returns NULL. The first entry in the returned array is the substitution for text. The remaining entries are the possible completions. The array is terminated with a NULL pointer.

entry_func is a function of two args, and returns a char *. The first argument is text. The second is a state argument; it is zero on the first call, and non-zero on subsequent calls. entry_func returns a NULL pointer to the caller when there are no more matches.

Function: char * rl_filename_completion_function (const char *text, int state)

A generator function for filename completion in the general case. text is a partial filename. The Bash source is a useful reference for writing application-specific completion functions (the Bash completion functions call this and other Readline functions).

Function: char * rl_username_completion_function (const char *text, int state)

A completion generator for usernames. text contains a partial username preceded by a random character (usually ‘~’). As with all completion generators, state is zero on the first call and non-zero for subsequent calls.