Interactive Command-line Input Library Functions
cplcompleteword(3TECLA)
NAME
cplcompleteword, cfcfilestart, cfcliteralescapes,
cfcsetcheckfn, cpladdcompletion, cplfilecompletions,
cpllasterror, cpllistcompletions, cplrecallmatches,
cplrecorderror, delCplFileConf, cplcheckexe,
delWordCompletion, newCplFileConf, newWordCompletion -
look up possible completions for a word
SYNOPSIS
cc [ flag... ] file... -ltecla [ library... ]
#include
#include
WordCompletion *newWordCompletion(void);
WordCompletion *delWordCompletion(WordCompletion *cpl);
CPLMATCHFN(cplfilecompletions);
CplFileConf *newCplFileConf(void);
void cfcfilestart((CplFileConf *cfc, int startindex);
void cfcliteralescapes(CplFileConf *cfc, int literal);
void cfcsetcheckfn(CplFileConf *cfc, CplCheckFn *chkfn,
void *chkdata);
CPLCHECKFN(cplcheckexe);
CplFileConf *delCplFileConf(CplFileConf *cfc);
CplMatches *cplcompleteword(WordCompletion *cpl, const char *line,
int wordend, void *data, CplMatchFn *matchfn);
CplMatches *cplrecallmatches(WordCompletion *cpl);
int cpllistcompletions(CplMatches *result, FILE *fp, int termwidth);
SunOS 5.11 Last change: 1 Jun 2004 1
Interactive Command-line Input Library Functions
cplcompleteword(3TECLA)
int cpladdcompletion(WordCompletion *cpl, const char *line,
int wordstart, int wordend, const char *suffix,
const char *typesuffix, const char *contsuffix);
void cplrecorderror(WordCompletion *cpl, const char *errmsg);
const char *cpllasterror(WordCompletion *cpl);
DESCRIPTION
The cplcompleteword() function is part of the
libtecla(3LIB) library. It is usually called behind the
scenes by glgetline(3TECLA), but can also be called
separately.
Given an input line containing an incomplete word to be com-
pleted, 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 comple-
tions of that word and record them, one at a time, by cal-
ling cpladdcompletion().
The newWordCompletion() function creates the resources used
by the cplcompleteword() function. In particular, it main-
tains the memory that is used to return the results of cal-
ling cplcompleteword().
The delWordCompletion() function deletes the resources that
were returned by a previous call to newWordCompletion(). It
always returns NUL (that is, a deleted object). It takes no
action if the cpl argument is NUL.
The callback functions that look up possible completions
should be defined with the CPLMATCHFN() macro, which is
defined in . Functions of this type are called
by cplcompleteword(), 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 con-
taining the word to be completed, and wordend 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 wordend for the start of
SunOS 5.11 Last change: 1 Jun 2004 2
Interactive Command-line Input Library Functions
cplcompleteword(3TECLA)
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
cpladdcompletion(). 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 cplrecorderror().
The last error message recorded by calling
cplrecorderror() can subsequently be queried by calling
cpllasterror().
The cpladdcompletion() 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
cplcompleteword(). The cpl, line, and wordend arguments
should be those that were passed to the callback function.
The wordstart argument should be the index within the input
line string of the start of the word that is being com-
pleted. This should equal wordend 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
cpladdcompletion() returns.
In the array of possible completions that the
cplcompleteword() function returns, the suffix recorded by
cpladdcompletion() is listed along with the concatentation
of this suffix with the word that lies between wordstart
and wordend in the input line.
SunOS 5.11 Last change: 1 Jun 2004 3
Interactive Command-line Input Library Functions
cplcompleteword(3TECLA)
The typesuffix argument specifies an optional string to be
appended to the completion if it is displayed as part of a
list of completions by cpllistcompletions. The intention
is that this indicate to the user the type of each comple-
tion. 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 com-
pletion were a function, you could indicate this to the user
by setting typesuffix to "()". Note that the typesuffix
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
cplcompleteword() are needed.
The contsuffix 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 com-
pletion 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 com-
pleted word were a function name, you could similarly aid
the user by arranging for an open parenthesis to be
appended.
The cplcompleteword() is normally called behind the scenes
by glgetline(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 sec-
tion. Its first argument is a resource object previously
returned by newWordCompletion(). The line argument is the
input line string, containing the word to be completed. The
wordend 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 glgetline(), this is the
character over which the user pressed TAB. The matchfn
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 func-
tion.
If no errors occur, the cplcompleteword() 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 cplcompleteword(), and will thus change on each
call which uses the same cpl argument.
SunOS 5.11 Last change: 1 Jun 2004 4
Interactive Command-line Input Library Functions
cplcompleteword(3TECLA)
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 *typesuffix; /* 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 *contsuffix; /* 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, cplcompleteword()
returns NUL. A description of the error can be acquired by
calling the cpllasterror() function.
The cpllasterror() function returns a terse description of
the error which occurred on the last call to cplcom
pleteword() or cpladdcompletion().
As a convenience, the return value of the last call to
cplcompleteword() can be recalled at a later time by cal-
ling cplrecallmatches(). If cplcompleteword() returned
NUL, so will cplrecallmatches().
When the cplcompleteword() function returns multiple pos-
sible completions, the cpllistcompletions() function can
SunOS 5.11 Last change: 1 Jun 2004 5
Interactive Command-line Input Library Functions
cplcompleteword(3TECLA)
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
typesuffix strings that were recorded with each completion,
thus indicating their types to the user.
Builtin Filename completion Callback
By default the glgetline() function, passes the
CPLMATCHFN(cpsfilecompletions) completion callback func-
tion to cplcompleteword(). This function can also be used
separately, either by sending it to cplcompleteword(), or
by calling it directly from your own completion callback
function.
#define CPLMATCHFN(fn) int (fn)(WordCompletion *cpl, \
void *data, const char *line, \
int wordend)
typedef CPLMATCHFN(CplMatchFn);
CPLMATCHFN(cplfilecompletions);
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 NUL in this argument. Other-
wise it should be a pointer to a CplFileConf object, previ-
ously allocated by calling newCplFileConf().
CplFileConf objects encapsulate the configuration parameters
of cplfilecompletions(). These parameters, which start out
with default values, can be changed by calling the accessor
functions described below.
By default, the cplfilecompletions() callback function
searches backwards for the start of the filename being com-
pleted, looking for the first unescaped space or the start
of the input line. If you wish to specify a different loca-
tion, call cfcfilestart() with the index at which the
filename starts in the input line. Passing startindex=-1
reenables the default behavior.
By default, when cplfilecompletions() 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
SunOS 5.11 Last change: 1 Jun 2004 6
Interactive Command-line Input Library Functions
cplcompleteword(3TECLA)
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
cfcliteralescapes() with a non-zero value in its literal
argument.
By default, cplfilecompletions() 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 cplfilecompletions(),
call cfcsetcheckfn(), and pass it a pointer to the func-
tion, 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 read-
able, writable or executable, or even based on what the file
contains.
#define CPLCHECKFN(fn) int (fn)(void *data, \
const char *pathname)
typedef CPLCHECKFN(CplCheckFn);
void cfcsetcheckfn(CplFileConf *cfc, CplCheckFn *chkfn, \
void *chkdata);
The cplcheckexe() function is a provided callback of the
above type, for use with cplfilecompletions(). It returns
non-zero if the filename that it is given represents a nor-
mal file that the user has execute permission to. You could
use this to have cplfilecompletions() only list comple-
tions of executable files.
When you have finished with a CplFileConf variable, you can
pass it to the delCplFileConf() 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
SunOS 5.11 Last change: 1 Jun 2004 7
Interactive Command-line Input Library Functions
cplcompleteword(3TECLA)
allocated WordCompletion object. In other words, if two
threads want to do word completion, they should each call
newWordCompletion() to allocate their own completion
objects.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
MT-Level MT-Safe
SEE ALSO
efexpandfile(3TECLA), glgetline(3TECLA), libtecla(3LIB),
pcalookupfile(3TECLA), attributes(5)
SunOS 5.11 Last change: 1 Jun 2004 8
Interactive Command-line Input Library Functions
cplcompleteword(3TECLA)
SunOS 5.11 Last change: 1 Jun 2004 9
|
