1 CPL_COMPLETE_WORD(3TECLA) Interactive Command-line Input Library Functions
2
3
4
5 NAME
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
13 SYNOPSIS
14 cc [ flag... ] file... -ltecla [ library... ]
15 #include <stdio.h>
16 #include <libtecla.h>
17
18 WordCompletion *new_WordCompletion(void);
19
20
21 WordCompletion *del_WordCompletion(WordCompletion *cpl);
22
23
24 CPL_MATCH_FN(cpl_file_completions);
25
26
27 CplFileConf *new_CplFileConf(void);
28
29
30 void cfc_file_start((CplFileConf *cfc, int start_index);
31
32
33 void cfc_literal_escapes(CplFileConf *cfc, int literal);
34
35
36 void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn,
37 void *chk_data);
38
39
40 CPL_CHECK_FN(cpl_check_exe);
41
42
43 CplFileConf *del_CplFileConf(CplFileConf *cfc);
44
45
46 CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line,
47 int word_end, void *data, CplMatchFn *match_fn);
48
49
50 CplMatches *cpl_recall_matches(WordCompletion *cpl);
51
52
53 int cpl_list_completions(CplMatches *result, FILE *fp, int term_width);
54
55
56 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
60
61 void cpl_record_error(WordCompletion *cpl, const char *errmsg);
62
63
64 const char *cpl_last_error(WordCompletion *cpl);
65
66
67 DESCRIPTION
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
72
73 Given an input line containing an incomplete word to be completed, it
74 calls a user-provided callback function (or the provided file-
75 completion callback function) to look up all possible completion
76 suffixes for that word. The callback function is expected to look
77 backward in the line, starting from the specified cursor position, to
78 find the start of the word to be completed, then to look up all
79 possible completions of that word and record them, one at a time, by
80 calling cpl_add_completion().
81
82
83 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
87
88 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
91 argument is NULL.
92
93
94 The callback functions that look up possible completions should be
95 defined with the CPL_MATCH_FN() macro, which is defined in
96 <libtecla.h>. Functions of this type are called by
97 cpl_complete_word(), and all of the arguments of the callback are those
98 that were passed to said function. In particular, the line argument
99 contains the input line containing the word to be completed, and
100 word_end is the index of the character that follows the last character
101 of the incomplete word within this string. The callback is expected to
102 look backwards from word_end for the start of the incomplete word. What
103 constitutes the start of a word clearly depends on the application, so
104 it makes sense for the callback to take on this responsibility. For
105 example, the builtin filename completion function looks backwards until
106 it encounters an unescaped space or the start of the line. Having found
107 the start of the word, the callback should then lookup all possible
108 completions of this word, and record each completion with separate
109 calls to cpl_add_completion(). If the callback needs access to an
110 application-specific symbol table, it can pass it and any other data
111 that it needs using the data argument. This removes any need for global
112 variables.
113
114
115 The callback function should return 0 if no errors occur. On failure it
116 should return 1 and register a terse description of the error by
117 calling cpl_record_error().
118
119
120 The last error message recorded by calling cpl_record_error() can
121 subsequently be queried by calling cpl_last_error().
122
123
124 The cpl_add_completion() function is called zero or more times by the
125 completion callback function to record each possible completion in the
126 specified WordCompletion object. These completions are subsequently
127 returned by cpl_complete_word(). The cpl, line, and word_end arguments
128 should be those that were passed to the callback function. The
129 word_start argument should be the index within the input line string of
130 the start of the word that is being completed. This should equal
131 word_end if a zero-length string is being completed. The suffix
132 argument is the string that would have to be appended to the incomplete
133 word to complete it. If this needs any quoting (for example, the
134 addition of backslashes before special characters) to be valid within
135 the displayed input line, this should be included. A copy of the suffix
136 string is allocated internally, so there is no need to maintain your
137 copy of the string after cpl_add_completion() returns.
138
139
140 In the array of possible completions that the cpl_complete_word()
141 function returns, the suffix recorded by cpl_add_completion() is listed
142 along with the concatenation of this suffix with the word that lies
143 between word_start and word_end in the input line.
144
145
146 The type_suffix argument specifies an optional string to be appended to
147 the completion if it is displayed as part of a list of completions by
148 cpl_list_completions. The intention is that this indicates to the user
149 the type of each completion. For example, the file completion function
150 places a directory separator after completions that are directories, to
151 indicate their nature to the user. Similarly, if the completion were a
152 function, you could indicate this to the user by setting type_suffix to
153 "()". Note that the type_suffix string is not copied, so if the
154 argument is not a literal string between speech marks, be sure that the
155 string remains valid for at least as long as the results of
156 cpl_complete_word() are needed.
157
158
159 The cont_suffix argument is a continuation suffix to append to the
160 completed word in the input line if this is the only completion. This
161 is something that is not part of the completion itself, but that gives
162 the user an indication about how they might continue to extend the
163 token. For example, the file-completion callback function adds a
164 directory separator if the completed word is a directory. If the
165 completed word were a function name, you could similarly aid the user
166 by arranging for an open parenthesis to be appended.
167
168
169 The cpl_complete_word() function is normally called behind the scenes
170 by gl_get_line(3TECLA), but can also be called separately if you
171 separately allocate a WordCompletion object. It performs word
172 completion, as described at the beginning of this section. Its first
173 argument is a resource object previously returned by
174 new_WordCompletion(). The line argument is the input line string,
175 containing the word to be completed. The word_end argument contains the
176 index of the character in the input line, that just follows the last
177 character of the word to be completed. When called by gl_get_line(),
178 this is the character over which the user pressed TAB. The match_fn
179 argument is the function pointer of the callback function which will
180 lookup possible completions of the word, as described above, and the
181 data argument provides a way for the application to pass arbitrary data
182 to the callback function.
183
184
185 If no errors occur, the cpl_complete_word() function returns a pointer
186 to a CplMatches container, as defined below. This container is
187 allocated as part of the cpl object that was passed to
188 cpl_complete_word(), and will thus change on each call which uses the
189 same cpl argument.
190
191 typedef struct {
192 char *completion; /* A matching completion */
193 /* string */
194 char *suffix; /* The part of the */
195 /* completion string which */
196 /* would have to be */
197 /* appended to complete the */
198 /* original word. */
199 const char *type_suffix; /* A suffix to be added when */
200 /* listing completions, to */
201 /* indicate the type of the */
202 /* completion. */
203 } CplMatch;
204
205 typedef struct {
206 char *suffix; /* The common initial part */
207 /* of all of the completion */
208 /* suffixes. */
209 const char *cont_suffix; /* Optional continuation */
210 /* string to be appended to */
211 /* the sole completion when */
212 /* nmatch==1. */
213 CplMatch *matches; /* The array of possible */
214 /* completion strings, */
215 /* sorted into lexical */
216 /* order. */
217 int nmatch; /* The number of elements in */
218 /* the above matches[] */
219 /* array. */
220 } CplMatches;
221
222
223
224 If an error occurs during completion, cpl_complete_word() returns NULL.
225 A description of the error can be acquired by calling the
226 cpl_last_error() function.
227
228
229 The cpl_last_error() function returns a terse description of the error
230 which occurred on the last call to cpl_complete_word() or
231 cpl_add_completion().
232
233
234 As a convenience, the return value of the last call to
235 cpl_complete_word() can be recalled at a later time by calling
236 cpl_recall_matches(). If cpl_complete_word() returned NULL, so will
237 cpl_recall_matches().
238
239
240 When the cpl_complete_word() function returns multiple possible
241 completions, the cpl_list_completions() function can be called upon to
242 list them, suitably arranged across the available width of the
243 terminal. It arranges for the displayed columns of completions to all
244 have the same width, set by the longest completion. It also appends the
245 type_suffix strings that were recorded with each completion, thus
246 indicating their types to the user.
247
248 Builtin Filename completion Callback
249 By default the gl_get_line() function passes the
250 CPL_MATCH_FN(cps_file_completions) completion callback function to
251 cpl_complete_word(). This function can also be used separately, either
252 by sending it to cpl_complete_word(), or by calling it directly from
253 your own completion callback function.
254
255 #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
256 void *data, const char *line, \
257 int word_end)
258
259 typedef CPL_MATCH_FN(CplMatchFn);
260
261 CPL_MATCH_FN(cpl_file_completions);
262
263
264
265 Certain aspects of the behavior of this callback can be changed via its
266 data argument. If you are happy with its default behavior you can pass
267 NULL in this argument. Otherwise it should be a pointer to a
268 CplFileConf object, previously allocated by calling new_CplFileConf().
269
270
271 CplFileConf objects encapsulate the configuration parameters of
272 cpl_file_completions(). These parameters, which start out with default
273 values, can be changed by calling the accessor functions described
274 below.
275
276
277 By default, the cpl_file_completions() callback function searches
278 backwards for the start of the filename being completed, looking for
279 the first unescaped space or the start of the input line. If you wish
280 to specify a different location, call cfc_file_start() with the index
281 at which the filename starts in the input line. Passing start_index=-1
282 reenables the default behavior.
283
284
285 By default, when cpl_file_completions() looks at a filename in the
286 input line, each lone backslash in the input line is interpreted as
287 being a special character which removes any special significance of the
288 character which follows it, such as a space which should be taken as
289 part of the filename rather than delimiting the start of the filename.
290 These backslashes are thus ignored while looking for completions, and
291 subsequently added before spaces, tabs and literal backslashes in the
292 list of completions. To have unescaped backslashes treated as normal
293 characters, call cfc_literal_escapes() with a non-zero value in its
294 literal argument.
295
296
297 By default, cpl_file_completions() reports all files whose names start
298 with the prefix that is being completed. If you only want a selected
299 subset of these files to be reported in the list of completions, you
300 can arrange this by providing a callback function which takes the full
301 pathname of a file, and returns 0 if the file should be ignored, or 1
302 if the file should be included in the list of completions. To register
303 such a function for use by cpl_file_completions(), call
304 cfc_set_check_fn(), and pass it a pointer to the function, together
305 with a pointer to any data that you would like passed to this callback
306 whenever it is called. Your callback can make its decisions based on
307 any property of the file, such as the filename itself, whether the file
308 is readable, writable or executable, or even based on what the file
309 contains.
310
311 #define CPL_CHECK_FN(fn) int (fn)(void *data, \
312 const char *pathname)
313
314 typedef CPL_CHECK_FN(CplCheckFn);
315
316 void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, \
317 void *chk_data);
318
319
320
321 The cpl_check_exe() function is a provided callback of the above type,
322 for use with cpl_file_completions(). It returns non-zero if the
323 filename that it is given represents a normal file that the user has
324 permission to execute. You could use this to have
325 cpl_file_completions() only list completions of executable files.
326
327
328 When you have finished with a CplFileConf variable, you can pass it to
329 the del_CplFileConf() destructor function to reclaim its memory.
330
331 Thread Safety
332 It is safe to use the facilities of this module in multiple threads,
333 provided that each thread uses a separately allocated WordCompletion
334 object. In other words, if two threads want to do word completion, they
335 should each call new_WordCompletion() to allocate their own completion
336 objects.
337
338 ATTRIBUTES
339 See attributes(5) for descriptions of the following attributes:
340
341
342
343
344 +--------------------+-----------------+
345 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
346 +--------------------+-----------------+
347 |Interface Stability | Evolving |
348 +--------------------+-----------------+
349 |MT-Level | MT-Safe |
350 +--------------------+-----------------+
351
352 SEE ALSO
353 ef_expand_file(3TECLA), gl_get_line(3TECLA), libtecla(3LIB),
354 pca_lookup_file(3TECLA), attributes(5)
355
356
357
358 January 18, 2020 CPL_COMPLETE_WORD(3TECLA)