Tribblix: manual page: cpl_complete

CPL_COMPLETE_WORD(3TECLA) Interactive Command-line Input Library Functions

NAME

cpl_complete_word, cfc_file_start, cfc_literal_escapes,
cfc_set_check_fn, cpl_add_completion, cpl_file_completions,
cpl_last_error, cpl_list_completions, cpl_recall_matches,
cpl_record_error, del_CplFileConf, cpl_check_exe, del_WordCompletion,
new_CplFileConf, new_WordCompletion - look up possible completions
for a word

SYNOPSIS

cc [ flag... ] file... -ltecla [ library... ]
#include <stdio.h>
#include <libtecla.h>

WordCompletion *new_WordCompletion(void);

WordCompletion *del_WordCompletion(WordCompletion *cpl);

CPL_MATCH_FN(cpl_file_completions);

CplFileConf *new_CplFileConf(void);

void cfc_file_start((CplFileConf *cfc, int start_index);

void cfc_literal_escapes(CplFileConf *cfc, int literal);

void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn,
void *chk_data);

CPL_CHECK_FN(cpl_check_exe);

CplFileConf *del_CplFileConf(CplFileConf *cfc);

CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line,
int word_end, void *data, CplMatchFn *match_fn);

CplMatches *cpl_recall_matches(WordCompletion *cpl);

int cpl_list_completions(CplMatches *result, FILE *fp, int term_width);

int cpl_add_completion(WordCompletion *cpl, const char *line,
int word_start, int word_end, const char *suffix,
const char *type_suffix, const char *cont_suffix);

void cpl_record_error(WordCompletion *cpl, const char *errmsg);

const char *cpl_last_error(WordCompletion *cpl);

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
characters) 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 concatenation 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 indicates 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. Similarly, 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() function 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.

typedef struct {
char *completion; /* A matching completion */
/* string */
char *suffix; /* The part of the */
/* completion string which */
/* would have to be */
/* appended to complete the */
/* original word. */
const char *type_suffix; /* A suffix to be added when */
/* listing completions, to */
/* indicate the type of the */
/* completion. */
} CplMatch;

typedef struct {
char *suffix; /* The common initial part */
/* of all of the completion */
/* suffixes. */
const char *cont_suffix; /* Optional continuation */
/* string to be appended to */
/* the sole completion when */
/* nmatch==1. */
CplMatch *matches; /* The array of possible */
/* completion strings, */
/* sorted into lexical */
/* order. */
int nmatch; /* The number of elements in */
/* the above matches[] */
/* array. */
} CplMatches;

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_complete_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.

#define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
void *data, const char *line, \
int word_end)

typedef CPL_MATCH_FN(CplMatchFn);

CPL_MATCH_FN(cpl_file_completions);

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
backslashes in the list of completions. To have unescaped backslashes
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.

#define CPL_CHECK_FN(fn) int (fn)(void *data, \
const char *pathname)

typedef CPL_CHECK_FN(CplCheckFn);

void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, \
void *chk_data);

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
permission to execute. 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.