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 charaters) 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 concatentation 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 indicate 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. Similary, 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() is normally called behind the scenes by
170 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
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_com plete_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
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 back slashes in the
292 list of completions. To have unescaped back slashes 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 execute permission to. 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 June 1, 2004 CPL_COMPLETE_WORD(3TECLA)
|
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
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
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)
|