Description

The cpl_complete_word() function is part of the libtecla(3LIB) library. It is usually
called behind the scenes by gl_get_line(3TECLA), but can also be called separately.

Given an input line containing an incomplete word to be completed, it
calls a user-provided callback function (or the provided file-completion callback function) to
look up all possible completion suffixes for that word. The callback function
is expected to look backward in the line, starting from the specified cursor
position, to find the start of the word to be completed, then
to look up all possible completions of that word and record them,
one at a time, by calling cpl_add_completion().

The new_WordCompletion() function creates the resources used by the cpl_complete_word() function. In
particular, it maintains the memory that is used to return the results
of calling cpl_complete_word().

The del_WordCompletion() function deletes the resources that were returned by a previous
call to new_WordCompletion(). It always returns NULL (that is, a deleted object).
It takes no action if the cpl argument is NULL.

The callback functions that look up possible completions should be defined with
the CPL_MATCH_FN() macro, which is defined in <libtecla.h>. Functions of this type
are called by cpl_complete_word(), and all of the arguments of the callback are
those that were passed to said function. In particular, the line argument
contains the input line containing the word to be completed, and word_end
is the index of the character that follows the last character of
the incomplete word within this string. The callback is expected to look
backwards from word_end for the start of the incomplete word. What constitutes
the start of a word clearly depends on the application, so it
makes sense for the callback to take on this responsibility. For example,
the builtin filename completion function looks backwards until it encounters an unescaped space
or the start of the line. Having found the start of the
word, the callback should then lookup all possible completions of this word,
and record each completion with separate calls to cpl_add_completion(). If the callback
needs access to an application-specific symbol table, it can pass it and
any other data that it needs using the data argument. This removes
any need for global variables.

The callback function should return 0 if no errors occur. On failure
it should return 1 and register a terse description of the error
by calling cpl_record_error().

The last error message recorded by calling cpl_record_error() can subsequently be queried
by calling cpl_last_error().

The cpl_add_completion() function is called zero or more times by the completion
callback function to record each possible completion in the specified WordCompletion object.
These completions are subsequently returned by cpl_complete_word(). The cpl, line, and word_end arguments
should be those that were passed to the callback function. The word_start
argument should be the index within the input line string of the
start of the word that is being completed. This should equal word_end if
a zero-length string is being completed. The suffix argument is the string
that would have to be appended to the incomplete word to complete
it. If this needs any quoting (for example, the addition of backslashes before
special charaters) to be valid within the displayed input line, this should
be included. A copy of the suffix string is allocated internally, so
there is no need to maintain your copy of the string after
cpl_add_completion() returns.

In the array of possible completions that the cpl_complete_word() function returns, the
suffix recorded by cpl_add_completion() is listed along with the concatentation of this
suffix with the word that lies between word_start and word_end in the
input line.

The type_suffix argument specifies an optional string to be appended to the
completion if it is displayed as part of a list of completions
by cpl_list_completions. The intention is that this indicate to the user the
type of each completion. For example, the file completion function places a directory
separator after completions that are directories, to indicate their nature to the
user. Similary, if the completion were a function, you could indicate this
to the user by setting type_suffix to “()”. Note that the type_suffix string
is not copied, so if the argument is not a literal string
between speech marks, be sure that the string remains valid for at
least as long as the results of cpl_complete_word() are needed.

The cont_suffix argument is a continuation suffix to append to the completed
word in the input line if this is the only completion. This
is something that is not part of the completion itself, but that
gives the user an indication about how they might continue to extend the
token. For example, the file-completion callback function adds a directory separator if
the completed word is a directory. If the completed word were a
function name, you could similarly aid the user by arranging for an
open parenthesis to be appended.

The cpl_complete_word() is normally called behind the scenes by gl_get_line(3TECLA), but can
also be called separately if you separately allocate a WordCompletion object. It performs
word completion, as described at the beginning of this section. Its first
argument is a resource object previously returned by new_WordCompletion(). The line argument
is the input line string, containing the word to be completed. The word_end
argument contains the index of the character in the input line, that
just follows the last character of the word to be completed. When
called by gl_get_line(), this is the character over which the user pressed TAB.
The match_fn argument is the function pointer of the callback function which
will lookup possible completions of the word, as described above, and the
data argument provides a way for the application to pass arbitrary data
to the callback function.

If no errors occur, the cpl_complete_word() function returns a pointer to a
CplMatches container, as defined below. This container is allocated as part of
the cpl object that was passed to cpl_complete_word(), and will thus change on
each call which uses the same cpl argument.

If an error occurs during completion, cpl_complete_word() returns NULL. A description of
the error can be acquired by calling the cpl_last_error() function.

The cpl_last_error() function returns a terse description of the error which occurred
on the last call to cpl_com plete_word() or cpl_add_completion().

As a convenience, the return value of the last call to cpl_complete_word()
can be recalled at a later time by calling cpl_recall_matches(). If cpl_complete_word()
returned NULL, so will cpl_recall_matches().

When the cpl_complete_word() function returns multiple possible completions, the cpl_list_completions() function can
be called upon to list them, suitably arranged across the available width
of the terminal. It arranges for the displayed columns of completions to all
have the same width, set by the longest completion. It also appends
the type_suffix strings that were recorded with each completion, thus indicating their
types to the user.

Builtin Filename completion Callback

By default the gl_get_line() function, passes the CPL_MATCH_FN(cps_file_completions) completion callback function to
cpl_complete_word(). This function can also be used separately, either by sending it
to cpl_complete_word(), or by calling it directly from your own completion callback
function.

Certain aspects of the behavior of this callback can be changed via
its data argument. If you are happy with its default behavior you
can pass NULL in this argument. Otherwise it should be a pointer
to a CplFileConf object, previously allocated by calling new_CplFileConf().

CplFileConf objects encapsulate the configuration parameters of cpl_file_completions(). These parameters, which start
out with default values, can be changed by calling the accessor functions
described below.

By default, the cpl_file_completions() callback function searches backwards for the start of
the filename being completed, looking for the first unescaped space or the
start of the input line. If you wish to specify a different
location, call cfc_file_start() with the index at which the filename starts in the
input line. Passing start_index=-1 reenables the default behavior.

By default, when cpl_file_completions() looks at a filename in the input line,
each lone backslash in the input line is interpreted as being a
special character which removes any special significance of the character which follows
it, such as a space which should be taken as part of the
filename rather than delimiting the start of the filename. These backslashes are
thus ignored while looking for completions, and subsequently added before spaces, tabs
and literal back slashes in the list of completions. To have unescaped
back slashes treated as normal characters, call cfc_literal_escapes() with a non-zero value in
its literal argument.

By default, cpl_file_completions() reports all files whose names start with the prefix
that is being completed. If you only want a selected subset of
these files to be reported in the list of completions, you can
arrange this by providing a callback function which takes the full pathname of
a file, and returns 0 if the file should be ignored, or
1 if the file should be included in the list of completions.
To register such a function for use by cpl_file_completions(), call cfc_set_check_fn(), and
pass it a pointer to the function, together with a pointer to any
data that you would like passed to this callback whenever it is
called. Your callback can make its decisions based on any property of
the file, such as the filename itself, whether the file is readable,
writable or executable, or even based on what the file contains.

The cpl_check_exe() function is a provided callback of the above type, for
use with cpl_file_completions(). It returns non-zero if the filename that it is
given represents a normal file that the user has execute permission to.
You could use this to have cpl_file_completions() only list completions of executable
files.

When you have finished with a CplFileConf variable, you can pass it
to the del_CplFileConf() destructor function to reclaim its memory.

Thread Safety

It is safe to use the facilities of this module in multiple
threads, provided that each thread uses a separately allocated WordCompletion object. In
other words, if two threads want to do word completion, they should
each call new_WordCompletion() to allocate their own completion objects.