Interactive Command-line Input Library Functions
cpl_complete_word(3TECLA)
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 wordSYNOPSIS
cc [ flag... ] file... -ltecla [ library... ]
#include
#include
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);
SunOS 5.11 Last change: 1 Jun 2004 1
Interactive Command-line Input Library Functions
cpl_complete_word(3TECLA)
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 thescenes by gl_get_line(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 theword to be completed, then to look up all possible comple-
tions of that word and record them, one at a time, by cal-
ling cpl_add_completion().
The new_WordCompletion() function creates the resources used
by the cpl_complete_word() function. In particular, it main-
tains the memory that is used to return the results of cal-
ling 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 completionsshould be defined with the CPL_MATCH_FN() macro, which is
defined in. 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. Inparticular, the line argument contains the input line con-
taining 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 isexpected to look backwards from word_end for the start of
SunOS 5.11 Last change: 1 Jun 2004 2
Interactive Command-line Input Library Functions
cpl_complete_word(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 tocpl_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 descriptionof the error by calling cpl_record_error().
The last error message recorded by callingcpl_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 bycpl_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 com-
pleted. 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 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 aftercpl_add_completion() returns.
In the array of possible completions that thecpl_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.
SunOS 5.11 Last change: 1 Jun 2004 3
Interactive Command-line Input Library Functions
cpl_complete_word(3TECLA)
The type_suffix argument specifies an optional string to be
appended to the completion if it is displayed as part of alist of completions by cpl_list_completions. 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 userby 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 ofcpl_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 onlycompletion. 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 cpl_complete_word() 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 performsword completion, as described at the beginning of this sec-
tion. Its first argument is a resource object previouslyreturned by new_WordCompletion(). The line argument is the
input line string, containing the word to be completed. Theword_end argument contains the index of the character in the
input line, that just follows the last character of the wordto 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 forthe application to pass arbitrary data to the callback func-
tion.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 waspassed to cpl_complete_word(), 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
cpl_complete_word(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 *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 bycalling 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_com
plete_word() or cpl_add_completion().
As a convenience, the return value of the last call tocpl_complete_word() can be recalled at a later time by cal-
ling cpl_recall_matches(). If cpl_complete_word() returned
NULL, so will cpl_recall_matches().
When the cpl_complete_word() function returns multiple pos-
sible completions, the cpl_list_completions() function can
SunOS 5.11 Last change: 1 Jun 2004 5
Interactive Command-line Input Library Functions
cpl_complete_word(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 thetype_suffix strings that were recorded with each completion,
thus indicating their types to the user. Builtin Filename completion CallbackBy default the gl_get_line() function, passes the
CPL_MATCH_FN(cps_file_completions) completion callback func-
tion 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 itsdefault behavior you can pass NULL in this argument. Other-
wise it should be a pointer to a CplFileConf object, previ-
ously allocated by calling new_CplFileConf().
CplFileConf objects encapsulate the configuration parametersof 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 com-
pleted, looking for the first unescaped space or the startof the input line. If you wish to specify a different loca-
tion, 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, suchSunOS 5.11 Last change: 1 Jun 2004 6
Interactive Command-line Input Library Functions
cpl_complete_word(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, callcfc_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. Toregister such a function for use by cpl_file_completions(),
call cfc_set_check_fn(), 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 thefile, such as the filename itself, whether the file is read-
able, 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 nor-
mal file that the user has execute permission to. You coulduse this to have cpl_file_completions() only list comple-
tions of executable files. When you have finished with a CplFileConf variable, you canpass 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 separatelySunOS 5.11 Last change: 1 Jun 2004 7
Interactive Command-line Input Library Functions
cpl_complete_word(3TECLA)
allocated WordCompletion object. In other words, if two threads want to do word completion, they should each callnew_WordCompletion() to allocate their own completion
objects.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
ef_expand_file(3TECLA), gl_get_line(3TECLA), libtecla(3LIB),
pca_lookup_file(3TECLA), attributes(5)
SunOS 5.11 Last change: 1 Jun 2004 8
Interactive Command-line Input Library Functions
cpl_complete_word(3TECLA)
SunOS 5.11 Last change: 1 Jun 2004 9