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
#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);
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.
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);
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.
libtecla.a - The tecla library
libtecla.h - The tecla header file.
libtecla(3), gl_get_line(3), ef_expand_file(3),
pca_lookup_file(3)
Martin Shepherd (
[email protected])