7 .\" to whom the Software is furnished to do so, provided that the above
8 .\" copyright notice(s) and this permission notice appear in all copies of
9 .\" the Software and that both the above copyright notice(s) and this
10 .\" permission notice appear in supporting documentation.
11 .\"
12 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
13 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
14 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
15 .\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
16 .\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
17 .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
18 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
19 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
20 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21 .\"
22 .\" Except as contained in this notice, the name of a copyright holder
23 .\" shall not be used in advertising or otherwise to promote the sale, use
24 .\" or other dealings in this Software without prior written authorization
25 .\" of the copyright holder.
26 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
27 .TH CPL_COMPLETE_WORD 3TECLA "Jun 1, 2004"
28 .SH NAME
29 cpl_complete_word, cfc_file_start, cfc_literal_escapes, cfc_set_check_fn,
30 cpl_add_completion, cpl_file_completions, cpl_last_error, cpl_list_completions,
31 cpl_recall_matches, cpl_record_error, del_CplFileConf, cpl_check_exe,
32 del_WordCompletion, new_CplFileConf, new_WordCompletion \- look up possible
33 completions for a word
34 .SH SYNOPSIS
35 .LP
36 .nf
37 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
38 #include <stdio.h>
39 #include <libtecla.h>
40
41 \fBWordCompletion *\fR\fBnew_WordCompletion\fR(\fBvoid\fR);
42 .fi
43
44 .LP
45 .nf
46 \fBWordCompletion *\fR\fBdel_WordCompletion\fR(\fBWordCompletion *\fR\fIcpl\fR);
47 .fi
48
49 .LP
50 .nf
51 \fBCPL_MATCH_FN\fR(\fBcpl_file_completions\fR);
52 .fi
53
54 .LP
55 .nf
99 .fi
100
101 .LP
102 .nf
103 \fBint\fR \fBcpl_add_completion\fR(\fBWordCompletion *\fR\fIcpl\fR, \fBconst char *\fR\fIline\fR,
104 \fBint\fR \fIword_start\fR, \fBint\fR \fIword_end\fR, \fBconst char *\fR\fIsuffix\fR,
105 \fBconst char *\fR\fItype_suffix\fR, \fBconst char *\fR\fIcont_suffix\fR);
106 .fi
107
108 .LP
109 .nf
110 \fBvoid\fR \fBcpl_record_error\fR(\fBWordCompletion *\fR\fIcpl\fR, \fBconst char *\fR\fIerrmsg\fR);
111 .fi
112
113 .LP
114 .nf
115 \fBconst char *\fR\fBcpl_last_error\fR(\fBWordCompletion *\fR\fIcpl\fR);
116 .fi
117
118 .SH DESCRIPTION
119 .sp
120 .LP
121 The \fBcpl_complete_word()\fR function is part of the \fBlibtecla\fR(3LIB)
122 library. It is usually called behind the scenes by \fBgl_get_line\fR(3TECLA),
123 but can also be called separately.
124 .sp
125 .LP
126 Given an input line containing an incomplete word to be completed, it calls a
127 user-provided callback function (or the provided file-completion callback
128 function) to look up all possible completion suffixes for that word. The
129 callback function is expected to look backward in the line, starting from the
130 specified cursor position, to find the start of the word to be completed, then
131 to look up all possible completions of that word and record them, one at a
132 time, by calling \fBcpl_add_completion()\fR.
133 .sp
134 .LP
135 The \fBnew_WordCompletion()\fR function creates the resources used by the
136 \fBcpl_complete_word()\fR function. In particular, it maintains the memory that
137 is used to return the results of calling \fBcpl_complete_word()\fR.
138 .sp
139 .LP
140 The \fBdel_WordCompletion()\fR function deletes the resources that were
164 .LP
165 The callback function should return 0 if no errors occur. On failure it should
166 return 1 and register a terse description of the error by calling
167 \fBcpl_record_error()\fR.
168 .sp
169 .LP
170 The last error message recorded by calling \fBcpl_record_error()\fR can
171 subsequently be queried by calling \fBcpl_last_error()\fR.
172 .sp
173 .LP
174 The \fBcpl_add_completion()\fR function is called zero or more times by the
175 completion callback function to record each possible completion in the
176 specified \fBWordCompletion\fR object. These completions are subsequently
177 returned by \fBcpl_complete_word()\fR. The \fIcpl\fR, \fIline\fR, and
178 \fIword_end\fR arguments should be those that were passed to the callback
179 function. The \fIword_start\fR argument should be the index within the input
180 line string of the start of the word that is being completed. This should equal
181 \fIword_end\fR if a zero-length string is being completed. The \fIsuffix\fR
182 argument is the string that would have to be appended to the incomplete word to
183 complete it. If this needs any quoting (for example, the addition of
184 backslashes before special charaters) to be valid within the displayed input
185 line, this should be included. A copy of the suffix string is allocated
186 internally, so there is no need to maintain your copy of the string after
187 \fBcpl_add_completion()\fR returns.
188 .sp
189 .LP
190 In the array of possible completions that the \fBcpl_complete_word()\fR
191 function returns, the suffix recorded by \fBcpl_add_completion()\fR is listed
192 along with the concatentation of this suffix with the word that lies between
193 \fIword_start\fR and \fIword_end\fR in the input line.
194 .sp
195 .LP
196 The \fItype_suffix\fR argument specifies an optional string to be appended to
197 the completion if it is displayed as part of a list of completions by
198 \fIcpl_list_completions\fR. The intention is that this indicate to the user the
199 type of each completion. For example, the file completion function places a
200 directory separator after completions that are directories, to indicate their
201 nature to the user. Similary, if the completion were a function, you could
202 indicate this to the user by setting \fItype_suffix\fR to "()". Note that the
203 \fItype_suffix\fR string is not copied, so if the argument is not a literal
204 string between speech marks, be sure that the string remains valid for at least
205 as long as the results of \fBcpl_complete_word()\fR are needed.
206 .sp
207 .LP
208 The \fIcont_suffix\fR argument is a continuation suffix to append to the
209 completed word in the input line if this is the only completion. This is
210 something that is not part of the completion itself, but that gives the user an
211 indication about how they might continue to extend the token. For example, the
212 file-completion callback function adds a directory separator if the completed
213 word is a directory. If the completed word were a function name, you could
214 similarly aid the user by arranging for an open parenthesis to be appended.
215 .sp
216 .LP
217 The \fBcpl_complete_word()\fR is normally called behind the scenes by
218 \fBgl_get_line\fR(3TECLA), but can also be called separately if you separately
219 allocate a \fBWordCompletion\fR object. It performs word completion, as
220 described at the beginning of this section. Its first argument is a resource
221 object previously returned by \fBnew_WordCompletion()\fR. The \fIline\fR
222 argument is the input line string, containing the word to be completed. The
223 \fIword_end\fR argument contains the index of the character in the input line,
224 that just follows the last character of the word to be completed. When called
225 by \fBgl_get_line()\fR, this is the character over which the user pressed TAB.
226 The \fImatch_fn\fR argument is the function pointer of the callback function
227 which will lookup possible completions of the word, as described above, and the
228 \fIdata\fR argument provides a way for the application to pass arbitrary data
229 to the callback function.
230 .sp
231 .LP
232 If no errors occur, the \fBcpl_complete_word()\fR function returns a pointer to
233 a \fBCplMatches\fR container, as defined below. This container is allocated as
234 part of the \fIcpl\fR object that was passed to \fBcpl_complete_word()\fR, and
235 will thus change on each call which uses the same \fIcpl\fR argument.
236 .sp
237 .in +2
260 /* nmatch==1. */
261 CplMatch *matches; /* The array of possible */
262 /* completion strings, */
263 /* sorted into lexical */
264 /* order. */
265 int nmatch; /* The number of elements in */
266 /* the above matches[] */
267 /* array. */
268 } CplMatches;
269 .fi
270 .in -2
271
272 .sp
273 .LP
274 If an error occurs during completion, \fBcpl_complete_word()\fR returns
275 \fINULL\fR. A description of the error can be acquired by calling the
276 \fBcpl_last_error()\fR function.
277 .sp
278 .LP
279 The \fBcpl_last_error()\fR function returns a terse description of the error
280 which occurred on the last call to \fBcpl_com plete_word()\fR or
281 \fBcpl_add_completion()\fR.
282 .sp
283 .LP
284 As a convenience, the return value of the last call to
285 \fBcpl_complete_word()\fR can be recalled at a later time by calling
286 \fBcpl_recall_matches()\fR. If \fBcpl_complete_word()\fR returned \fINULL\fR,
287 so will \fBcpl_recall_matches()\fR.
288 .sp
289 .LP
290 When the \fBcpl_complete_word()\fR function returns multiple possible
291 completions, the \fBcpl_list_completions()\fR function can be called upon to
292 list them, suitably arranged across the available width of the terminal. It
293 arranges for the displayed columns of completions to all have the same width,
294 set by the longest completion. It also appends the \fItype_suffix\fR strings
295 that were recorded with each completion, thus indicating their types to the
296 user.
297 .SS "Builtin Filename completion Callback"
298 .sp
299 .LP
300 By default the \fBgl_get_line()\fR function, passes the
301 \fBCPL_MATCH_FN\fR(\fBcps_file_completions\fR) completion callback function to
302 \fBcpl_complete_word()\fR. This function can also be used separately, either by
303 sending it to \fBcpl_complete_word()\fR, or by calling it directly from your
304 own completion callback function.
305 .sp
306 .in +2
307 .nf
308 #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \e
309 void *data, const char *line, \e
310 int word_end)
311
312 typedef CPL_MATCH_FN(CplMatchFn);
313
314 CPL_MATCH_FN(cpl_file_completions);
315 .fi
316 .in -2
317
318 .sp
319 .LP
320 Certain aspects of the behavior of this callback can be changed via its
326 .LP
327 \fBCplFileConf\fR objects encapsulate the configuration parameters of
328 \fBcpl_file_completions()\fR. These parameters, which start out with default
329 values, can be changed by calling the accessor functions described below.
330 .sp
331 .LP
332 By default, the \fBcpl_file_completions()\fR callback function searches
333 backwards for the start of the filename being completed, looking for the first
334 unescaped space or the start of the input line. If you wish to specify a
335 different location, call \fBcfc_file_start()\fR with the index at which the
336 filename starts in the input line. Passing \fIstart_index\fR=-1 reenables the
337 default behavior.
338 .sp
339 .LP
340 By default, when \fBcpl_file_completions()\fR looks at a filename in the input
341 line, each lone backslash in the input line is interpreted as being a special
342 character which removes any special significance of the character which follows
343 it, such as a space which should be taken as part of the filename rather than
344 delimiting the start of the filename. These backslashes are thus ignored while
345 looking for completions, and subsequently added before spaces, tabs and literal
346 back slashes in the list of completions. To have unescaped back slashes treated
347 as normal characters, call \fBcfc_literal_escapes()\fR with a non-zero value in
348 its \fIliteral\fR argument.
349 .sp
350 .LP
351 By default, \fBcpl_file_completions()\fR reports all files whose names start
352 with the prefix that is being completed. If you only want a selected subset of
353 these files to be reported in the list of completions, you can arrange this by
354 providing a callback function which takes the full pathname of a file, and
355 returns 0 if the file should be ignored, or 1 if the file should be included in
356 the list of completions. To register such a function for use by
357 \fBcpl_file_completions()\fR, call \fBcfc_set_check_fn()\fR, and pass it a
358 pointer to the function, together with a pointer to any data that you would
359 like passed to this callback whenever it is called. Your callback can make its
360 decisions based on any property of the file, such as the filename itself,
361 whether the file is readable, writable or executable, or even based on what the
362 file contains.
363 .sp
364 .in +2
365 .nf
366 #define CPL_CHECK_FN(fn) int (fn)(void *data, \e
367 const char *pathname)
368
369 typedef CPL_CHECK_FN(CplCheckFn);
370
371 void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, \e
372 void *chk_data);
373 .fi
374 .in -2
375
376 .sp
377 .LP
378 The \fBcpl_check_exe()\fR function is a provided callback of the above type,
379 for use with \fBcpl_file_completions()\fR. It returns non-zero if the filename
380 that it is given represents a normal file that the user has execute permission
381 to. You could use this to have \fBcpl_file_completions()\fR only list
382 completions of executable files.
383 .sp
384 .LP
385 When you have finished with a \fBCplFileConf\fR variable, you can pass it to
386 the \fBdel_CplFileConf()\fR destructor function to reclaim its memory.
387 .SS "Thread Safety"
388 .sp
389 .LP
390 It is safe to use the facilities of this module in multiple threads, provided
391 that each thread uses a separately allocated \fBWordCompletion\fR object. In
392 other words, if two threads want to do word completion, they should each call
393 \fBnew_WordCompletion()\fR to allocate their own completion objects.
394 .SH ATTRIBUTES
395 .sp
396 .LP
397 See \fBattributes\fR(5) for descriptions of the following attributes:
398 .sp
399
400 .sp
401 .TS
402 box;
403 c | c
404 l | l .
405 ATTRIBUTE TYPE ATTRIBUTE VALUE
406 _
407 Interface Stability Evolving
408 _
409 MT-Level MT-Safe
410 .TE
411
412 .SH SEE ALSO
413 .sp
414 .LP
415 \fBef_expand_file\fR(3TECLA), \fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB),
416 \fBpca_lookup_file\fR(3TECLA), \fBattributes\fR(5)
|
7 .\" to whom the Software is furnished to do so, provided that the above
8 .\" copyright notice(s) and this permission notice appear in all copies of
9 .\" the Software and that both the above copyright notice(s) and this
10 .\" permission notice appear in supporting documentation.
11 .\"
12 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
13 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
14 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
15 .\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
16 .\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
17 .\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
18 .\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
19 .\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
20 .\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21 .\"
22 .\" Except as contained in this notice, the name of a copyright holder
23 .\" shall not be used in advertising or otherwise to promote the sale, use
24 .\" or other dealings in this Software without prior written authorization
25 .\" of the copyright holder.
26 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
27 .TH CPL_COMPLETE_WORD 3TECLA "January 18, 2020"
28 .SH NAME
29 cpl_complete_word, cfc_file_start, cfc_literal_escapes, cfc_set_check_fn,
30 cpl_add_completion, cpl_file_completions, cpl_last_error, cpl_list_completions,
31 cpl_recall_matches, cpl_record_error, del_CplFileConf, cpl_check_exe,
32 del_WordCompletion, new_CplFileConf, new_WordCompletion \- look up possible
33 completions for a word
34 .SH SYNOPSIS
35 .nf
36 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ltecla\fR [ \fIlibrary\fR\&.\|.\|. ]
37 #include <stdio.h>
38 #include <libtecla.h>
39
40 \fBWordCompletion *\fR\fBnew_WordCompletion\fR(\fBvoid\fR);
41 .fi
42
43 .LP
44 .nf
45 \fBWordCompletion *\fR\fBdel_WordCompletion\fR(\fBWordCompletion *\fR\fIcpl\fR);
46 .fi
47
48 .LP
49 .nf
50 \fBCPL_MATCH_FN\fR(\fBcpl_file_completions\fR);
51 .fi
52
53 .LP
54 .nf
98 .fi
99
100 .LP
101 .nf
102 \fBint\fR \fBcpl_add_completion\fR(\fBWordCompletion *\fR\fIcpl\fR, \fBconst char *\fR\fIline\fR,
103 \fBint\fR \fIword_start\fR, \fBint\fR \fIword_end\fR, \fBconst char *\fR\fIsuffix\fR,
104 \fBconst char *\fR\fItype_suffix\fR, \fBconst char *\fR\fIcont_suffix\fR);
105 .fi
106
107 .LP
108 .nf
109 \fBvoid\fR \fBcpl_record_error\fR(\fBWordCompletion *\fR\fIcpl\fR, \fBconst char *\fR\fIerrmsg\fR);
110 .fi
111
112 .LP
113 .nf
114 \fBconst char *\fR\fBcpl_last_error\fR(\fBWordCompletion *\fR\fIcpl\fR);
115 .fi
116
117 .SH DESCRIPTION
118 The \fBcpl_complete_word()\fR function is part of the \fBlibtecla\fR(3LIB)
119 library. It is usually called behind the scenes by \fBgl_get_line\fR(3TECLA),
120 but can also be called separately.
121 .sp
122 .LP
123 Given an input line containing an incomplete word to be completed, it calls a
124 user-provided callback function (or the provided file-completion callback
125 function) to look up all possible completion suffixes for that word. The
126 callback function is expected to look backward in the line, starting from the
127 specified cursor position, to find the start of the word to be completed, then
128 to look up all possible completions of that word and record them, one at a
129 time, by calling \fBcpl_add_completion()\fR.
130 .sp
131 .LP
132 The \fBnew_WordCompletion()\fR function creates the resources used by the
133 \fBcpl_complete_word()\fR function. In particular, it maintains the memory that
134 is used to return the results of calling \fBcpl_complete_word()\fR.
135 .sp
136 .LP
137 The \fBdel_WordCompletion()\fR function deletes the resources that were
161 .LP
162 The callback function should return 0 if no errors occur. On failure it should
163 return 1 and register a terse description of the error by calling
164 \fBcpl_record_error()\fR.
165 .sp
166 .LP
167 The last error message recorded by calling \fBcpl_record_error()\fR can
168 subsequently be queried by calling \fBcpl_last_error()\fR.
169 .sp
170 .LP
171 The \fBcpl_add_completion()\fR function is called zero or more times by the
172 completion callback function to record each possible completion in the
173 specified \fBWordCompletion\fR object. These completions are subsequently
174 returned by \fBcpl_complete_word()\fR. The \fIcpl\fR, \fIline\fR, and
175 \fIword_end\fR arguments should be those that were passed to the callback
176 function. The \fIword_start\fR argument should be the index within the input
177 line string of the start of the word that is being completed. This should equal
178 \fIword_end\fR if a zero-length string is being completed. The \fIsuffix\fR
179 argument is the string that would have to be appended to the incomplete word to
180 complete it. If this needs any quoting (for example, the addition of
181 backslashes before special characters) to be valid within the displayed input
182 line, this should be included. A copy of the suffix string is allocated
183 internally, so there is no need to maintain your copy of the string after
184 \fBcpl_add_completion()\fR returns.
185 .sp
186 .LP
187 In the array of possible completions that the \fBcpl_complete_word()\fR
188 function returns, the suffix recorded by \fBcpl_add_completion()\fR is listed
189 along with the concatenation of this suffix with the word that lies between
190 \fIword_start\fR and \fIword_end\fR in the input line.
191 .sp
192 .LP
193 The \fItype_suffix\fR argument specifies an optional string to be appended to
194 the completion if it is displayed as part of a list of completions by
195 \fIcpl_list_completions\fR. The intention is that this indicates to the user the
196 type of each completion. For example, the file completion function places a
197 directory separator after completions that are directories, to indicate their
198 nature to the user. Similarly, if the completion were a function, you could
199 indicate this to the user by setting \fItype_suffix\fR to "()". Note that the
200 \fItype_suffix\fR string is not copied, so if the argument is not a literal
201 string between speech marks, be sure that the string remains valid for at least
202 as long as the results of \fBcpl_complete_word()\fR are needed.
203 .sp
204 .LP
205 The \fIcont_suffix\fR argument is a continuation suffix to append to the
206 completed word in the input line if this is the only completion. This is
207 something that is not part of the completion itself, but that gives the user an
208 indication about how they might continue to extend the token. For example, the
209 file-completion callback function adds a directory separator if the completed
210 word is a directory. If the completed word were a function name, you could
211 similarly aid the user by arranging for an open parenthesis to be appended.
212 .sp
213 .LP
214 The \fBcpl_complete_word()\fR function is normally called behind the scenes by
215 \fBgl_get_line\fR(3TECLA), but can also be called separately if you separately
216 allocate a \fBWordCompletion\fR object. It performs word completion, as
217 described at the beginning of this section. Its first argument is a resource
218 object previously returned by \fBnew_WordCompletion()\fR. The \fIline\fR
219 argument is the input line string, containing the word to be completed. The
220 \fIword_end\fR argument contains the index of the character in the input line,
221 that just follows the last character of the word to be completed. When called
222 by \fBgl_get_line()\fR, this is the character over which the user pressed TAB.
223 The \fImatch_fn\fR argument is the function pointer of the callback function
224 which will lookup possible completions of the word, as described above, and the
225 \fIdata\fR argument provides a way for the application to pass arbitrary data
226 to the callback function.
227 .sp
228 .LP
229 If no errors occur, the \fBcpl_complete_word()\fR function returns a pointer to
230 a \fBCplMatches\fR container, as defined below. This container is allocated as
231 part of the \fIcpl\fR object that was passed to \fBcpl_complete_word()\fR, and
232 will thus change on each call which uses the same \fIcpl\fR argument.
233 .sp
234 .in +2
257 /* nmatch==1. */
258 CplMatch *matches; /* The array of possible */
259 /* completion strings, */
260 /* sorted into lexical */
261 /* order. */
262 int nmatch; /* The number of elements in */
263 /* the above matches[] */
264 /* array. */
265 } CplMatches;
266 .fi
267 .in -2
268
269 .sp
270 .LP
271 If an error occurs during completion, \fBcpl_complete_word()\fR returns
272 \fINULL\fR. A description of the error can be acquired by calling the
273 \fBcpl_last_error()\fR function.
274 .sp
275 .LP
276 The \fBcpl_last_error()\fR function returns a terse description of the error
277 which occurred on the last call to \fBcpl_complete_word()\fR or
278 \fBcpl_add_completion()\fR.
279 .sp
280 .LP
281 As a convenience, the return value of the last call to
282 \fBcpl_complete_word()\fR can be recalled at a later time by calling
283 \fBcpl_recall_matches()\fR. If \fBcpl_complete_word()\fR returned \fINULL\fR,
284 so will \fBcpl_recall_matches()\fR.
285 .sp
286 .LP
287 When the \fBcpl_complete_word()\fR function returns multiple possible
288 completions, the \fBcpl_list_completions()\fR function can be called upon to
289 list them, suitably arranged across the available width of the terminal. It
290 arranges for the displayed columns of completions to all have the same width,
291 set by the longest completion. It also appends the \fItype_suffix\fR strings
292 that were recorded with each completion, thus indicating their types to the
293 user.
294 .SS "Builtin Filename completion Callback"
295 By default the \fBgl_get_line()\fR function passes the
296 \fBCPL_MATCH_FN\fR(\fBcps_file_completions\fR) completion callback function to
297 \fBcpl_complete_word()\fR. This function can also be used separately, either by
298 sending it to \fBcpl_complete_word()\fR, or by calling it directly from your
299 own completion callback function.
300 .sp
301 .in +2
302 .nf
303 #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \e
304 void *data, const char *line, \e
305 int word_end)
306
307 typedef CPL_MATCH_FN(CplMatchFn);
308
309 CPL_MATCH_FN(cpl_file_completions);
310 .fi
311 .in -2
312
313 .sp
314 .LP
315 Certain aspects of the behavior of this callback can be changed via its
321 .LP
322 \fBCplFileConf\fR objects encapsulate the configuration parameters of
323 \fBcpl_file_completions()\fR. These parameters, which start out with default
324 values, can be changed by calling the accessor functions described below.
325 .sp
326 .LP
327 By default, the \fBcpl_file_completions()\fR callback function searches
328 backwards for the start of the filename being completed, looking for the first
329 unescaped space or the start of the input line. If you wish to specify a
330 different location, call \fBcfc_file_start()\fR with the index at which the
331 filename starts in the input line. Passing \fIstart_index\fR=-1 reenables the
332 default behavior.
333 .sp
334 .LP
335 By default, when \fBcpl_file_completions()\fR looks at a filename in the input
336 line, each lone backslash in the input line is interpreted as being a special
337 character which removes any special significance of the character which follows
338 it, such as a space which should be taken as part of the filename rather than
339 delimiting the start of the filename. These backslashes are thus ignored while
340 looking for completions, and subsequently added before spaces, tabs and literal
341 backslashes in the list of completions. To have unescaped backslashes treated
342 as normal characters, call \fBcfc_literal_escapes()\fR with a non-zero value in
343 its \fIliteral\fR argument.
344 .sp
345 .LP
346 By default, \fBcpl_file_completions()\fR reports all files whose names start
347 with the prefix that is being completed. If you only want a selected subset of
348 these files to be reported in the list of completions, you can arrange this by
349 providing a callback function which takes the full pathname of a file, and
350 returns 0 if the file should be ignored, or 1 if the file should be included in
351 the list of completions. To register such a function for use by
352 \fBcpl_file_completions()\fR, call \fBcfc_set_check_fn()\fR, and pass it a
353 pointer to the function, together with a pointer to any data that you would
354 like passed to this callback whenever it is called. Your callback can make its
355 decisions based on any property of the file, such as the filename itself,
356 whether the file is readable, writable or executable, or even based on what the
357 file contains.
358 .sp
359 .in +2
360 .nf
361 #define CPL_CHECK_FN(fn) int (fn)(void *data, \e
362 const char *pathname)
363
364 typedef CPL_CHECK_FN(CplCheckFn);
365
366 void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, \e
367 void *chk_data);
368 .fi
369 .in -2
370
371 .sp
372 .LP
373 The \fBcpl_check_exe()\fR function is a provided callback of the above type,
374 for use with \fBcpl_file_completions()\fR. It returns non-zero if the filename
375 that it is given represents a normal file that the user has permission to
376 execute. You could use this to have \fBcpl_file_completions()\fR only list
377 completions of executable files.
378 .sp
379 .LP
380 When you have finished with a \fBCplFileConf\fR variable, you can pass it to
381 the \fBdel_CplFileConf()\fR destructor function to reclaim its memory.
382 .SS "Thread Safety"
383 It is safe to use the facilities of this module in multiple threads, provided
384 that each thread uses a separately allocated \fBWordCompletion\fR object. In
385 other words, if two threads want to do word completion, they should each call
386 \fBnew_WordCompletion()\fR to allocate their own completion objects.
387 .SH ATTRIBUTES
388 See \fBattributes\fR(5) for descriptions of the following attributes:
389 .sp
390
391 .sp
392 .TS
393 box;
394 c | c
395 l | l .
396 ATTRIBUTE TYPE ATTRIBUTE VALUE
397 _
398 Interface Stability Evolving
399 _
400 MT-Level MT-Safe
401 .TE
402
403 .SH SEE ALSO
404 \fBef_expand_file\fR(3TECLA), \fBgl_get_line\fR(3TECLA), \fBlibtecla\fR(3LIB),
405 \fBpca_lookup_file\fR(3TECLA), \fBattributes\fR(5)
|