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