1 '\" te
2 .\" Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd. All Rights Reserved.
3 .\" Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the
4 .\" "Software"), to deal in the Software without restriction, including
5 .\" without limitation the rights to use, copy, modify, merge, publish,
6 .\" distribute, and/or sell copies of the Software, and to permit persons
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
55 \fBCplFileConf *\fR\fBnew_CplFileConf\fR(\fBvoid\fR);
56 .fi
57
58 .LP
59 .nf
60 \fBvoid\fR \fBcfc_file_start\fR(\fB(CplFileConf *\fR\fIcfc\fR, \fBint\fR \fIstart_index\fR);
61 .fi
62
63 .LP
64 .nf
65 \fBvoid\fR \fBcfc_literal_escapes\fR(\fBCplFileConf *\fR\fIcfc\fR, \fBint\fR \fIliteral\fR);
66 .fi
67
68 .LP
69 .nf
70 \fBvoid\fR \fBcfc_set_check_fn\fR(\fBCplFileConf *\fR\fIcfc\fR, \fBCplCheckFn *\fR\fIchk_fn\fR,
71 \fBvoid *\fR\fIchk_data\fR);
72 .fi
73
74 .LP
75 .nf
76 \fBCPL_CHECK_FN\fR(\fBcpl_check_exe\fR);
77 .fi
78
79 .LP
80 .nf
81 \fBCplFileConf *\fR\fBdel_CplFileConf\fR(\fBCplFileConf *\fR\fIcfc\fR);
82 .fi
83
84 .LP
85 .nf
86 \fBCplMatches *\fR\fBcpl_complete_word\fR(\fBWordCompletion *\fR\fIcpl\fR, \fBconst char *\fR\fIline\fR,
87 \fBint\fR \fIword_end\fR, \fBvoid *\fR\fIdata\fR, \fBCplMatchFn *\fR\fImatch_fn\fR);
88 .fi
89
90 .LP
91 .nf
92 \fBCplMatches *\fR\fBcpl_recall_matches\fR(\fBWordCompletion *\fR\fIcpl\fR);
93 .fi
94
95 .LP
96 .nf
97 \fBint\fR \fBcpl_list_completions\fR(\fBCplMatches *\fR\fIresult\fR, \fBFILE *\fR\fIfp\fR, \fBint\fR \fIterm_width\fR);
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
138 returned by a previous call to \fBnew_WordCompletion()\fR. It always returns
139 \fINULL\fR (that is, a deleted object). It takes no action if the \fIcpl\fR
140 argument is \fINULL\fR.
141 .sp
142 .LP
143 The callback functions that look up possible completions should be defined with
144 the \fBCPL_MATCH_FN()\fR macro, which is defined in <\fBlibtecla.h\fR>.
145 Functions of this type are called by \fBcpl_complete_word()\fR, and all of the
146 arguments of the callback are those that were passed to said function. In
147 particular, the \fIline\fR argument contains the input line containing the word
148 to be completed, and \fIword_end\fR is the index of the character that follows
149 the last character of the incomplete word within this string. The callback is
150 expected to look backwards from \fIword_end\fR for the start of the incomplete
151 word. What constitutes the start of a word clearly depends on the application,
152 so it makes sense for the callback to take on this responsibility. For example,
153 the builtin filename completion function looks backwards until it encounters an
154 unescaped space or the start of the line. Having found the start of the word,
155 the callback should then lookup all possible completions of this word, and
156 record each completion with separate calls to \fBcpl_add_completion()\fR. If
157 the callback needs access to an application-specific symbol table, it can pass
158 it and any other data that it needs using the \fIdata\fR argument. This removes
159 any need for global variables.
160 .sp
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
235 .nf
236 typedef struct {
237 char *completion; /* A matching completion */
238 /* string */
239 char *suffix; /* The part of the */
240 /* completion string which */
241 /* would have to be */
242 /* appended to complete the */
243 /* original word. */
244 const char *type_suffix; /* A suffix to be added when */
245 /* listing completions, to */
246 /* indicate the type of the */
247 /* completion. */
248 } CplMatch;
249
250 typedef struct {
251 char *suffix; /* The common initial part */
252 /* of all of the completion */
253 /* suffixes. */
254 const char *cont_suffix; /* Optional continuation */
255 /* string to be appended to */
256 /* the sole completion when */
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
316 \fIdata\fR argument. If you are happy with its default behavior you can pass
317 \fINULL\fR in this argument. Otherwise it should be a pointer to a
318 \fBCplFileConf\fR object, previously allocated by calling
319 \fBnew_CplFileConf()\fR.
320 .sp
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)