Provided by: libtecla-dev_1.6.3-1_amd64 
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, del_WordCompletion,
new_CplFileConf, new_WordCompletion - lookup possible completions for a word
SYNOPSIS
#include <stdio.h>
#include <libtecla.h>
WordCompletion *new_WordCompletion(void);
WordCompletion *del_WordCompletion(WordCompletion *cpl);
#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);
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);
#define CPL_CHECK_FN(fn) int (fn)(void *data, \
const char *pathname)
typedef CPL_CHECK_FN(CplCheckFn);
CPL_CHECK_FN(cpl_check_exe);
CplFileConf *new_CplFileConf(void);
CplFileConf *del_CplFileConf(CplFileConf *cfc);
void cfc_literal_escapes(CplFileConf *cfc, int literal);
void cfc_file_start(CplFileConf *cfc, int start_index);
void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn,
void *chk_data);
DESCRIPTION
The cpl_complete_word() function is part of the tecla library (see the libtecla(3) man
page). It is usually called behind the scenes by gl_get_line(3), 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().
Descriptions of the functions of this module are as follows:
WordCompletion *new_WordCompletion(void)
This 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().
WordCompletion *del_WordCompletion(WordCompletion *cpl)
This function deletes the resources that were returned by a previous call to
new_WordCompletion(). It always returns NULL (ie. a deleted object). It does nothing if
the cpl argument is NULL.
The callback functions which lookup possible completions should be defined with the
following macro (which is defined in libtecla.h).
#define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
void *data, \
const char *line, \
int word_end)
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 hits 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 via 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, via the data argument. This
removes any need for globals.
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().
void cpl_record_error(WordCompletion *cpl,
const char *errmsg);
The last error message recorded by calling cpl_record_error(), can subsequently be queried
by calling cpl_last_error(), as described later.
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);
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(), as described later. 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 (eg. 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.
Note that in the array of possible completions which 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 isn't copied, so if the argument isn't 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 is a continuation suffix to append to the completed word in the input line
if this is the only completion. This is something that isn't 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.
CplMatches *cpl_complete_word(WordCompletion *cpl,
const char *line,
int word_end, void *data,
CplMatchFn *match_fn);
The cpl_complete_word() is normally called behind the scenes by gl_get_line(3), 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.
const char *cpl_last_error(WordCompletion *cpl);
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().
CplMatches *cpl_recall_matches(WordCompletion *cpl);
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().
int cpl_list_completions(CplMatches *result, FILE *fp,
int terminal_width);
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.
THE BUILT-IN FILENAME-COMPLETION CALLBACK
By default the gl_get_line(3) function, passes the following 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.
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 *new_CplFileConf(void);
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 un-escaped 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 re-
enables the default behavior.
void cfc_file_start(CplFileConf *cfc, int start_index);
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.
void cfc_literal_escapes(CplFileConf *cfc, int literal);
By default, cpl_file_completions() reports all files who's 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 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.
CplFileConf *del_CplFileConf(CplFileConf *cfc);
THREAD SAFETY
In multi-threaded programs, you should use the libtecla_r.a version of the library. This
uses POSIX reentrant functions where available (hence the _r suffix), and disables
features that rely on non-reentrant system functions. In the case of this module, the only
disabled feature is username completion in ~username/ expressions, in
cpl_file_completions().
Using the libtecla_r.a version of the library, 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.
FILES
libtecla.a - The tecla library
libtecla.h - The tecla header file.
SEE ALSO
libtecla(3), gl_get_line(3), ef_expand_file(3),
pca_lookup_file(3)
AUTHOR
Martin Shepherd (mcs@astro.caltech.edu)
cpl_complete_word(3)