1cpl_complete_worIdn(t3eTrEaCcLtAi)ve Command-line Input LibrarycFpuln_cctoimopnlsete_word(3TECLA)
2
6 cpl_complete_word, cfc_file_start, cfc_literal_escapes,
7 cfc_set_check_fn, cpl_add_completion, cpl_file_completions,
8 cpl_last_error, cpl_list_completions, cpl_recall_matches,
9 cpl_record_error, del_CplFileConf, cpl_check_exe, del_WordCompletion,
10 new_CplFileConf, new_WordCompletion - look up possible completions for
11 a word
12
14 cc [ flag... ] file... -ltecla [ library... ]
15 #include <stdio.h>
16 #include <libtecla.h>
17 WordCompletion *new_WordCompletion(void);
19 WordCompletion *del_WordCompletion(WordCompletion *cpl);
22 CPL_MATCH_FN(cpl_file_completions);
25 CplFileConf *new_CplFileConf(void);
28 void cfc_file_start((CplFileConf *cfc, int start_index);
31 void cfc_literal_escapes(CplFileConf *cfc, int literal);
34 void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn,
37 void *chk_data);
38 CPL_CHECK_FN(cpl_check_exe);
41 CplFileConf *del_CplFileConf(CplFileConf *cfc);
44 CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line,
47 int word_end, void *data, CplMatchFn *match_fn);
48 CplMatches *cpl_recall_matches(WordCompletion *cpl);
51 int cpl_list_completions(CplMatches *result, FILE *fp, int term_width);
54 int cpl_add_completion(WordCompletion *cpl, const char *line,
57 int word_start, int word_end, const char *suffix,
58 const char *type_suffix, const char *cont_suffix);
59 void cpl_record_error(WordCompletion *cpl, const char *errmsg);
62 const char *cpl_last_error(WordCompletion *cpl);
65
68 The cpl_complete_word() function is part of the libtecla(3LIB) library.
69 It is usually called behind the scenes by gl_get_line(3TECLA), but can
70 also be called separately.
71 Given an input line containing an incomplete word to be completed, it
74 calls a user-provided callback function (or the provided file-comple‐
75 tion callback function) to look up all possible completion suffixes for
76 that word. The callback function is expected to look backward in the
77 line, starting from the specified cursor position, to find the start of
78 the word to be completed, then to look up all possible completions of
79 that word and record them, one at a time, by calling cpl_add_comple‐
80 tion().
81 The new_WordCompletion() function creates the resources used by the
84 cpl_complete_word() function. In particular, it maintains the memory
85 that is used to return the results of calling cpl_complete_word().
86 The del_WordCompletion() function deletes the resources that were
89 returned by a previous call to new_WordCompletion(). It always returns
90 NULL (that is, a deleted object). It takes no action if the cpl argu‐
91 ment is NULL.
92 The callback functions that look up possible completions should be
95 defined with the CPL_MATCH_FN() macro, which is defined in <libte‐
96 cla.h>. Functions of this type are called by cpl_complete_word(), and
97 all of the arguments of the callback are those that were passed to said
98 function. In particular, the line argument contains the input line con‐
99 taining the word to be completed, and word_end is the index of the
100 character that follows the last character of the incomplete word within
101 this string. The callback is expected to look backwards from word_end
102 for the start of the incomplete word. What constitutes the start of a
103 word clearly depends on the application, so it makes sense for the
104 callback to take on this responsibility. For example, the builtin file‐
105 name completion function looks backwards until it encounters an
106 unescaped space or the start of the line. Having found the start of the
107 word, the callback should then lookup all possible completions of this
108 word, and record each completion with separate calls to cpl_add_comple‐
109 tion(). If the callback needs access to an application-specific symbol
110 table, it can pass it and any other data that it needs using the data
111 argument. This removes any need for global variables.
112 The callback function should return 0 if no errors occur. On failure it
115 should return 1 and register a terse description of the error by call‐
116 ing cpl_record_error().
117 The last error message recorded by calling cpl_record_error() can sub‐
120 sequently be queried by calling cpl_last_error().
121 The cpl_add_completion() function is called zero or more times by the
124 completion callback function to record each possible completion in the
125 specified WordCompletion object. These completions are subsequently
126 returned by cpl_complete_word(). The cpl, line, and word_end arguments
127 should be those that were passed to the callback function. The
128 word_start argument should be the index within the input line string of
129 the start of the word that is being completed. This should equal
130 word_end if a zero-length string is being completed. The suffix argu‐
131 ment is the string that would have to be appended to the incomplete
132 word to complete it. If this needs any quoting (for example, the addi‐
133 tion of backslashes before special charaters) to be valid within the
134 displayed input line, this should be included. A copy of the suffix
135 string is allocated internally, so there is no need to maintain your
136 copy of the string after cpl_add_completion() returns.
137 In the array of possible completions that the cpl_complete_word() func‐
140 tion returns, the suffix recorded by cpl_add_completion() is listed
141 along with the concatentation of this suffix with the word that lies
142 between word_start and word_end in the input line.
143 The type_suffix argument specifies an optional string to be appended to
146 the completion if it is displayed as part of a list of completions by
147 cpl_list_completions. The intention is that this indicate to the user
148 the type of each completion. For example, the file completion function
149 places a directory separator after completions that are directories, to
150 indicate their nature to the user. Similary, if the completion were a
151 function, you could indicate this to the user by setting type_suffix to
152 "()". Note that the type_suffix string is not copied, so if the argu‐
153 ment is not a literal string between speech marks, be sure that the
154 string remains valid for at least as long as the results of cpl_com‐
155 plete_word() are needed.
156 The cont_suffix argument is a continuation suffix to append to the com‐
159 pleted word in the input line if this is the only completion. This is
160 something that is not part of the completion itself, but that gives the
161 user an indication about how they might continue to extend the token.
162 For example, the file-completion callback function adds a directory
163 separator if the completed word is a directory. If the completed word
164 were a function name, you could similarly aid the user by arranging for
165 an open parenthesis to be appended.
166 The cpl_complete_word() is normally called behind the scenes by
169 gl_get_line(3TECLA), but can also be called separately if you sepa‐
170 rately allocate a WordCompletion object. It performs word completion,
171 as described at the beginning of this section. Its first argument is a
172 resource object previously returned by new_WordCompletion(). The line
173 argument is the input line string, containing the word to be completed.
174 The word_end argument contains the index of the character in the input
175 line, that just follows the last character of the word to be completed.
176 When called by gl_get_line(), this is the character over which the user
177 pressed TAB. The match_fn argument is the function pointer of the call‐
178 back function which will lookup possible completions of the word, as
179 described above, and the data argument provides a way for the applica‐
180 tion to pass arbitrary data to the callback function.
181 If no errors occur, the cpl_complete_word() function returns a pointer
184 to a CplMatches container, as defined below. This container is allo‐
185 cated as part of the cpl object that was passed to cpl_complete_word(),
186 and will thus change on each call which uses the same cpl argument.
187 typedef struct {
189 char *completion; /* A matching completion */
190 /* string */
191 char *suffix; /* The part of the */
192 /* completion string which */
193 /* would have to be */
194 /* appended to complete the */
195 /* original word. */
196 const char *type_suffix; /* A suffix to be added when */
197 /* listing completions, to */
198 /* indicate the type of the */
199 /* completion. */
200 } CplMatch;
201 typedef struct {
203 char *suffix; /* The common initial part */
204 /* of all of the completion */
205 /* suffixes. */
206 const char *cont_suffix; /* Optional continuation */
207 /* string to be appended to */
208 /* the sole completion when */
209 /* nmatch==1. */
210 CplMatch *matches; /* The array of possible */
211 /* completion strings, */
212 /* sorted into lexical */
213 /* order. */
214 int nmatch; /* The number of elements in */
215 /* the above matches[] */
216 /* array. */
217 } CplMatches;
218 If an error occurs during completion, cpl_complete_word() returns NULL.
222 A description of the error can be acquired by calling the
223 cpl_last_error() function.
224 The cpl_last_error() function returns a terse description of the error
227 which occurred on the last call to cpl_com plete_word() or cpl_add_com‐
228 pletion().
229 As a convenience, the return value of the last call to cpl_com‐
232 plete_word() can be recalled at a later time by calling
233 cpl_recall_matches(). If cpl_complete_word() returned NULL, so will
234 cpl_recall_matches().
235 When the cpl_complete_word() function returns multiple possible comple‐
238 tions, the cpl_list_completions() function can be called upon to list
239 them, suitably arranged across the available width of the terminal. It
240 arranges for the displayed columns of completions to all have the same
241 width, set by the longest completion. It also appends the type_suffix
242 strings that were recorded with each completion, thus indicating their
243 types to the user.
244 Builtin Filename completion Callback
246 By default the gl_get_line() function, passes the
247 CPL_MATCH_FN(cps_file_completions) completion callback function to
248 cpl_complete_word(). This function can also be used separately, either
249 by sending it to cpl_complete_word(), or by calling it directly from
250 your own completion callback function.
251 #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
253 void *data, const char *line, \
254 int word_end)
255 typedef CPL_MATCH_FN(CplMatchFn);
257 CPL_MATCH_FN(cpl_file_completions);
259 Certain aspects of the behavior of this callback can be changed via its
263 data argument. If you are happy with its default behavior you can pass
264 NULL in this argument. Otherwise it should be a pointer to a CplFile‐
265 Conf object, previously allocated by calling new_CplFileConf().
266 CplFileConf objects encapsulate the configuration parameters of
269 cpl_file_completions(). These parameters, which start out with default
270 values, can be changed by calling the accessor functions described
271 below.
272 By default, the cpl_file_completions() callback function searches back‐
275 wards for the start of the filename being completed, looking for the
276 first unescaped space or the start of the input line. If you wish to
277 specify a different location, call cfc_file_start() with the index at
278 which the filename starts in the input line. Passing start_index=-1
279 reenables the default behavior.
280 By default, when cpl_file_completions() looks at a filename in the
283 input line, each lone backslash in the input line is interpreted as
284 being a special character which removes any special significance of the
285 character which follows it, such as a space which should be taken as
286 part of the filename rather than delimiting the start of the filename.
287 These backslashes are thus ignored while looking for completions, and
288 subsequently added before spaces, tabs and literal back slashes in the
289 list of completions. To have unescaped back slashes treated as normal
290 characters, call cfc_literal_escapes() with a non-zero value in its
291 literal argument.
292 By default, cpl_file_completions() reports all files whose names start
295 with the prefix that is being completed. If you only want a selected
296 subset of these files to be reported in the list of completions, you
297 can arrange this by providing a callback function which takes the full
298 pathname of a file, and returns 0 if the file should be ignored, or 1
299 if the file should be included in the list of completions. To register
300 such a function for use by cpl_file_completions(), call
301 cfc_set_check_fn(), and pass it a pointer to the function, together
302 with a pointer to any data that you would like passed to this callback
303 whenever it is called. Your callback can make its decisions based on
304 any property of the file, such as the filename itself, whether the file
305 is readable, writable or executable, or even based on what the file
306 contains.
307 #define CPL_CHECK_FN(fn) int (fn)(void *data, \
309 const char *pathname)
310 typedef CPL_CHECK_FN(CplCheckFn);
312 void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, \
314 void *chk_data);
315 The cpl_check_exe() function is a provided callback of the above type,
319 for use with cpl_file_completions(). It returns non-zero if the file‐
320 name that it is given represents a normal file that the user has exe‐
321 cute permission to. You could use this to have cpl_file_completions()
322 only list completions of executable files.
323 When you have finished with a CplFileConf variable, you can pass it to
326 the del_CplFileConf() destructor function to reclaim its memory.
327 Thread Safety
329 It is safe to use the facilities of this module in multiple threads,
330 provided that each thread uses a separately allocated WordCompletion
331 object. In other words, if two threads want to do word completion, they
332 should each call new_WordCompletion() to allocate their own completion
333 objects.
334
336 See attributes(5) for descriptions of the following attributes:
337 ┌─────────────────────────────┬─────────────────────────────┐
342 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
343 ├─────────────────────────────┼─────────────────────────────┤
344 │Interface Stability │Evolving │
345 ├─────────────────────────────┼─────────────────────────────┤
346 │MT-Level │MT-Safe │
347 └─────────────────────────────┴─────────────────────────────┘
348
350 ef_expand_file(3TECLA), gl_get_line(3TECLA), libtecla(3LIB),
351 pca_lookup_file(3TECLA), attributes(5)
352SunOS 5.11 1 Jun 2004 cpl_complete_word(3TECLA)