1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
|
Content-type: text/html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of cpl_complete_word</TITLE>
</HEAD><BODY>
<H1>cpl_complete_word</H1>
Section: C Library Functions (3)<BR><A HREF="#index">Index</A>
<A HREF="index.html">Return to Main Contents</A><HR>
<A NAME="lbAB"> </A>
<H2>NAME</H2>
cpl_complete_word, cfc_file_start, cfc_literal_escapes, cfc_set_check_fn, cpl_add_completion, cpl_file_completions, cpl_last_error, cpl_list_completions, cpl_recall_matches, cpl_record_error, del_CplFileConf, del_WordCompletion, new_CplFileConf, new_WordCompletion - lookup possible completions for a word
<A NAME="lbAC"> </A>
<H2>SYNOPSIS</H2>
<PRE>
#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>>
#include <<A HREF="file:///usr/include/libtecla.h">libtecla.h</A>>
WordCompletion *new_WordCompletion(void);
WordCompletion *del_WordCompletion(WordCompletion *cpl);
#define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
void *data, \
const char *line, \
int word_end)
typedef CPL_MATCH_FN(CplMatchFn);
CPL_MATCH_FN(cpl_file_completions);
CplMatches *cpl_complete_word(WordCompletion *cpl,
const char *line,
int word_end, void *data,
CplMatchFn *match_fn);
CplMatches *cpl_recall_matches(WordCompletion *cpl);
int cpl_list_completions(CplMatches *result, FILE *fp,
int term_width);
int cpl_add_completion(WordCompletion *cpl,
const char *line, int word_start,
int word_end, const char *suffix,
const char *type_suffix,
const char *cont_suffix);
void cpl_record_error(WordCompletion *cpl,
const char *errmsg);
const char *cpl_last_error(WordCompletion *cpl);
#define CPL_CHECK_FN(fn) int (fn)(void *data, \
const char *pathname)
typedef CPL_CHECK_FN(CplCheckFn);
CPL_CHECK_FN(cpl_check_exe);
CplFileConf *new_CplFileConf(void);
CplFileConf *del_CplFileConf(CplFileConf *cfc);
void cfc_literal_escapes(CplFileConf *cfc, int literal);
void cfc_file_start(CplFileConf *cfc, int start_index);
void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn,
void *chk_data);
</PRE>
<P>
<A NAME="lbAD"> </A>
<H2>DESCRIPTION</H2>
<P>
The <B>cpl_complete_word()</B> function is part of the tecla library
(see the <A HREF="libtecla.html">libtecla</A>(3) man page). It is usually called behind the scenes
by <B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B>, but can also be called separately.
<P>
Given an input line containing an incomplete word to be completed, it
calls a user-provided callback function (or the provided
file-completion callback function) to look up all possible completion
suffixes for that word. The callback function is expected to look
backward in the line, starting from the specified cursor position, to
find the start of the word to be completed, then to look up all
possible completions of that word and record them, one at a time by
calling <B>cpl_add_completion()</B>.
<P>
<P>
Descriptions of the functions of this module are as follows:
<P>
<PRE>
WordCompletion *new_WordCompletion(void)
</PRE>
<P>
This function creates the resources used by the <B>cpl_complete_word()</B>
function. In particular, it maintains the memory that is used to
return the results of calling <B>cpl_complete_word()</B>.
<P>
<PRE>
WordCompletion *del_WordCompletion(WordCompletion *cpl)
</PRE>
<P>
This function deletes the resources that were returned by a previous
call to <B>new_WordCompletion()</B>. It always returns <B>NULL</B> (ie. a
deleted object). It does nothing if the <B>cpl</B> argument is
<B>NULL</B>.
<P>
The callback functions which lookup possible completions should be
defined with the following macro (which is defined in libtecla.h).
<P>
<PRE>
#define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
void *data, \
const char *line, \
int word_end)
</PRE>
<P>
Functions of this type are called by <B>cpl_complete_word()</B>, and
all of the arguments of the callback are those that were passed to
said function. In particular, the <B>line</B> argument contains the
input line containing the word to be completed, and <B>word_end</B> is
the index of the character that follows the last character of the
incomplete word within this string. The callback is expected to look
backwards from <B>word_end</B> for the start of the incomplete
word. What constitutes the start of a word clearly depends on the
application, so it makes sense for the callback to take on this
responsibility. For example, the builtin filename completion function
looks backwards until it hits an unescaped space, or the start of the
line. Having found the start of the word, the callback should then
lookup all possible completions of this word, and record each
completion via separate calls to <B>cpl_add_completion()</B>. If the
callback needs access to an application-specific symbol table, it can
pass it and any other data that it needs, via the <B>data</B>
argument. This removes any need for globals.
<P>
The callback function should return 0 if no errors occur. On failure
it should return 1, and register a terse description of the error by
calling <B>cpl_record_error()</B>.
<P>
<PRE>
void cpl_record_error(WordCompletion *cpl,
const char *errmsg);
</PRE>
<P>
The last error message recorded by calling <B>cpl_record_error()</B>,
can subsequently be queried by calling <B>cpl_last_error()</B>, as
described later.
<P>
<PRE>
int cpl_add_completion(WordCompletion *cpl,
const char *line, int word_start,
int word_end, const char *suffix,
const char *type_suffix,
const char *cont_suffix);
</PRE>
<P>
The <B>cpl_add_completion()</B> function is called zero or more times
by the completion callback function to record each possible completion
in the specified <B>WordCompletion</B> object. These completions are
subsequently returned by <B>cpl_complete_word()</B>, as described
later. The <B>cpl</B>, <B>line</B>, and <B>word_end</B> arguments should
be those that were passed to the callback function. The
<B>word_start</B> argument should be the index within the input line
string of the start of the word that is being completed. This should
equal <B>word_end</B> if a zero-length string is being completed. The
<B>suffix</B> argument is the string that would have to be appended to
the incomplete word to complete it. If this needs any quoting
(eg. the addition of backslashes before special charaters) to be valid
within the displayed input line, this should be included. A copy of
the suffix string is allocated internally, so there is no need to
maintain your copy of the string after <B>cpl_add_completion()</B>
returns.
<P>
Note that in the array of possible completions which the
<B>cpl_complete_word()</B> function returns, the suffix recorded by
<B>cpl_add_completion()</B> is listed along with the concatentation of
this suffix with the word that lies between <B>word_start</B> and
<B>word_end</B> in the input line.
<P>
The <B>type_suffix</B> argument specifies an optional string to be
appended to the completion if it is displayed as part of a list of
completions by <B>cpl_list_completions()</B>. The intention is that
this indicate to the user the type of each completion. For example,
the file completion function places a directory separator after
completions that are directories, to indicate their nature to the
user. Similary, if the completion were a function, you could indicate
this to the user by setting <B>type_suffix</B> to "()". Note that the
<B>type_suffix</B> string isn't copied, so if the argument isn't a
literal string between speech marks, be sure that the string remains
valid for at least as long as the results of <B>cpl_complete_word()</B>
are needed.
<P>
The <B>cont_suffix</B> is a continuation suffix to append to the
completed word in the input line if this is the only completion. This
is something that isn't part of the completion itself, but that gives
the user an indication about how they might continue to extend the
token. For example, the file-completion callback function adds a
directory separator if the completed word is a directory. If the
completed word were a function name, you could similarly aid the user
by arranging for an open parenthesis to be appended.
<P>
<PRE>
CplMatches *cpl_complete_word(WordCompletion *cpl,
const char *line,
int word_end, void *data,
CplMatchFn *match_fn);
</PRE>
<P>
The <B>cpl_complete_word()</B> is normally called behind the scenes by
<B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B>, but can also be called separately if you
separately allocate a <B>WordCompletion</B> object. It performs word
completion, as described at the beginning of this section. Its first
argument is a resource object previously returned by
<B>new_WordCompletion()</B>. The <B>line</B> argument is the input line
string, containing the word to be completed. The <B>word_end</B>
argument contains the index of the character in the input line, that
just follows the last character of the word to be completed. When
called by <B>gl_get_line()</B>, this is the character over which the
user pressed <B>TAB</B>. The <B>match_fn argument is the function
pointer of the callback function which will lookup possible
completions of the word, as described above, and the data</B>
argument provides a way for the application to pass arbitrary data to
the callback function.
<P>
If no errors occur, the <B>cpl_complete_word()</B> function returns a
pointer to a <B>CplMatches</B> container, as defined below. This
container is allocated as part of the <B>cpl</B> object that was passed
to <B>cpl_complete_word()</B>, and will thus change on each call which
uses the same <B>cpl</B> argument.
<P>
<PRE>
typedef struct {
char *completion; /* A matching completion */
/* string */
char *suffix; /* The part of the */
/* completion string which */
/* would have to be */
/* appended to complete the */
/* original word. */
const char *type_suffix; /* A suffix to be added when */
/* listing completions, to */
/* indicate the type of the */
/* completion. */
} CplMatch;
typedef struct {
char *suffix; /* The common initial part */
/* of all of the completion */
/* suffixes. */
const char *cont_suffix; /* Optional continuation */
/* string to be appended to */
/* the sole completion when */
/* nmatch==1. */
CplMatch *matches; /* The array of possible */
/* completion strings, */
/* sorted into lexical */
/* order. */
int nmatch; /* The number of elements in */
/* the above matches[] */
/* array. */
} CplMatches;
</PRE>
<P>
If an error occurs during completion, <B>cpl_complete_word()</B>
returns NULL. A description of the error can be acquired by calling
the <B>cpl_last_error() function.
<P>
</B><PRE>
const char *cpl_last_error(WordCompletion *cpl);
</PRE>
<P>
The <B>cpl_last_error() function returns a terse description of the
error which occurred on the last call to cpl_complete_word()</B> or
<B>cpl_add_completion()</B>.
<P>
<PRE>
CplMatches *cpl_recall_matches(WordCompletion *cpl);
</PRE>
<P>
As a convenience, the return value of the last call to
<B>cpl_complete_word()</B> can be recalled at a later time by calling
<B>cpl_recall_matches()</B>. If <B>cpl_complete_word()</B> returned
<B>NULL</B>, so will <B>cpl_recall_matches()</B>.
<P>
<PRE>
int cpl_list_completions(CplMatches *result, FILE *fp,
int terminal_width);
</PRE>
<P>
When the <B>cpl_complete_word()</B> function returns multiple possible
completions, the <B>cpl_list_completions()</B> function can be called
upon to list them, suitably arranged across the available width of the
terminal. It arranges for the displayed columns of completions to all
have the same width, set by the longest completion. It also appends
the <B>type_suffix</B> strings that were recorded with each completion,
thus indicating their types to the user.
<P>
<A NAME="lbAE"> </A>
<H2>THE BUILT-IN FILENAME-COMPLETION CALLBACK</H2>
<P>
By default the <B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B> function, passes the following
completion callback function to <B>cpl_complete_word()</B>. This
function can also be used separately, either by sending it to
<B>cpl_complete_word()</B>, or by calling it directly from your
own completion callback function.
<P>
<PRE>
CPL_MATCH_FN(cpl_file_completions);
</PRE>
<P>
Certain aspects of the behavior of this callback can be changed via
its <B>data</B> argument. If you are happy with its default behavior
you can pass <B>NULL</B> in this argument. Otherwise it should be a
pointer to a <B>CplFileConf</B> object, previously allocated by calling
<B>new_CplFileConf()</B>.
<P>
<PRE>
CplFileConf *new_CplFileConf(void);
</PRE>
<P>
<B>CplFileConf</B> objects encapsulate the configuration parameters of
<B>cpl_file_completions()</B>. These parameters, which start out with
default values, can be changed by calling the accessor functions
described below.
<P>
By default, the <B>cpl_file_completions() callback function
searches backwards for the start of the filename being completed,
looking for the first un-escaped space or the start of the input
line. If you wish to specify a different location, call
cfc_file_start()</B> with the index at which the filename starts in
the input line. Passing start_index=-1 re-enables the default
behavior.
<P>
<PRE>
void cfc_file_start(CplFileConf *cfc, int start_index);
</PRE>
<P>
By default, when <B>cpl_file_completions()</B> looks at a filename in
the input line, each lone backslash in the input line is interpreted
as being a special character which removes any special significance of
the character which follows it, such as a space which should be taken
as part of the filename rather than delimiting the start of the
filename. These backslashes are thus ignored while looking for
completions, and subsequently added before spaces, tabs and literal
backslashes in the list of completions. To have unescaped backslashes
treated as normal characters, call <B>cfc_literal_escapes()</B> with a
non-zero value in its <B>literal</B> argument.
<P>
<PRE>
void cfc_literal_escapes(CplFileConf *cfc, int literal);
</PRE>
<P>
By default, <B>cpl_file_completions()</B> reports all files who's names
start with the prefix that is being completed. If you only want a
selected subset of these files to be reported in the list of
completions, you can arrange this by providing a callback function
which takes the full pathname of a file, and returns <B>0</B> if the
file should be ignored, or <B>1</B> if the file should be included in
the list of completions. To register such a function for use by
<B>cpl_file_completions()</B>, call <B>cfc_set_check_fn()</B>, and pass
it a pointer to the function, together with a pointer to any data that
you would like passed to this callback whenever it is called. Your
callback can make its decisions based on any property of the file,
such as the filename itself, whether the file is readable, writable or
executable, or even based on what the file contains.
<P>
<PRE>
#define CPL_CHECK_FN(fn) int (fn)(void *data, \
const char *pathname)
typedef CPL_CHECK_FN(CplCheckFn);
void cfc_set_check_fn(CplFileConf *cfc,
CplCheckFn *chk_fn, void *chk_data);
</PRE>
<P>
The <B>cpl_check_exe()</B> function is a provided callback of the above
type, for use with <B>cpl_file_completions()</B>. It returns non-zero
if the filename that it is given represents a normal file that the
user has execute permission to. You could use this to have
<B>cpl_file_completions()</B> only list completions of executable
files.
<P>
When you have finished with a <B>CplFileConf</B> variable, you can pass
it to the <B>del_CplFileConf()</B> destructor function to reclaim its
memory.
<P>
<PRE>
CplFileConf *del_CplFileConf(CplFileConf *cfc);
</PRE>
<P>
<P>
<A NAME="lbAF"> </A>
<H2>THREAD SAFETY</H2>
<P>
In multi-threaded programs, you should use the <B>libtecla_r.a</B>
version of the library. This uses POSIX reentrant functions where
available (hence the <B>_r</B> suffix), and disables features that rely
on non-reentrant system functions. In the case of this module, the
only disabled feature is username completion in <B>~username/</B>
expressions, in <B>cpl_file_completions()</B>.
<P>
Using the <B>libtecla_r.a</B> version of the library, it is safe to use
the facilities of this module in multiple threads, provided that each
thread uses a separately allocated <B>WordCompletion</B> object. In
other words, if two threads want to do word completion, they should
each call <B>new_WordCompletion()</B> to allocate their own completion
objects.
<P>
<A NAME="lbAG"> </A>
<H2>FILES</H2>
<PRE>
libtecla.a - The tecla library
libtecla.h - The tecla header file.
</PRE>
<P>
<A NAME="lbAH"> </A>
<H2>SEE ALSO</H2>
<P>
<PRE>
<A HREF="libtecla.html">libtecla</A>(3), <A HREF="gl_get_line.html">gl_get_line</A>(3), <A HREF="ef_expand_file.html">ef_expand_file</A>(3),
<A HREF="pca_lookup_file.html">pca_lookup_file</A>(3)
</PRE>
<P>
<A NAME="lbAI"> </A>
<H2>AUTHOR</H2>
Martin Shepherd (<A HREF="mailto:mcs@astro.caltech.edu">mcs@astro.caltech.edu</A>)
<P>
<HR>
<A NAME="index"> </A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">THE BUILT-IN FILENAME-COMPLETION CALLBACK</A><DD>
<DT><A HREF="#lbAF">THREAD SAFETY</A><DD>
<DT><A HREF="#lbAG">FILES</A><DD>
<DT><A HREF="#lbAH">SEE ALSO</A><DD>
<DT><A HREF="#lbAI">AUTHOR</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 22:21:57 GMT, November 09, 2014
</BODY>
</HTML>
|
