cpl_complete_word cpl_complete_word
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);
DESCRIPTION
The cpl_complete_word() function is part of the tecla library (see the
libtecla man page). It is usually called behind the
scenes by gl_get_line, but can also be called sepa-
rately.
Given an input line containing an incomplete word to be completed, it
calls a user-provided callback function (or the provided file-comple-
tion 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_comple-
tion().
Descriptions of the functions of this module are as follows:
CompleteWord *new_CompleteWord(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().
CompleteWord *del_CompleteWord(CompleteWord *cpl)
This function deletes the resources that were returned by a previous
call to new_CompleteWord(). 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 func-
tion. In particular, the line argument contains the input line contain-
ing the word to be completed, and word_end is the index of the charac-
ter 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 com-
pletion function looks backwards until it hits an unescaped space, or
the start of the line. Having found the start of the word, the call-
back 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 call-
ing cpl_record_error().
void cpl_record_error(WordCompletion *cpl,
const char *errmsg);
The last error message recorded by calling cpl_record_error(), can sub-
sequently 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 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.
Note that in the array of possible completions which the cpl_com-
plete_word() function returns, the suffix recorded by cpl_add_comple-
tion() 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_com-
plete_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 some-
thing 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 separa-
tor 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, but can also be called separately if you
separately allocate a WordCompletion object. It performs word comple-
tion, as described at the beginning of this section. Its first argument
is a resource object previously returned by new_CompleteWord(). The
line argument is the input line string, containing the word to be com-
pleted. 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 allo-
cated 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_com-
pletion().
CplMatches *cpl_recall_matches(WordCompletion *cpl);
As a convenience, the return value of the last call to cpl_com-
plete_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 comple-
tions, 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 function, passes the follow-
ing completion callback function to cpl_complete_word(). This function
can also be used separately, either by sending it to cpl_com-
plete_word(), or by calling it directly from your own completion call-
back 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 CplFile-
Conf 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 back-
wards 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 file-
name that it is given represents a normal file that the user has exe-
cute 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_comple-
tions().
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, gl_get_line, ef_expand_file,
pca_lookup_file
AUTHOR
Martin Shepherd (mcs@astro.caltech.edu)
cpl_complete_word