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