1cpl_complete_worIdn(t3eTrEaCcLtAi)ve Command-line Input LibrarycFpuln_cctoimopnlsete_word(3TECLA)
2
3
4

NAME

6       cpl_complete_word,         cfc_file_start,         cfc_literal_escapes,
7       cfc_set_check_fn,       cpl_add_completion,       cpl_file_completions,
8       cpl_last_error,        cpl_list_completions,        cpl_recall_matches,
9       cpl_record_error, del_CplFileConf,  cpl_check_exe,  del_WordCompletion,
10       new_CplFileConf,  new_WordCompletion - look up possible completions for
11       a word
12

SYNOPSIS

14       cc [ flag... ] file... -ltecla [ library... ]
15       #include <stdio.h>
16       #include <libtecla.h>
17
18       WordCompletion *new_WordCompletion(void);
19
20
21       WordCompletion *del_WordCompletion(WordCompletion *cpl);
22
23
24       CPL_MATCH_FN(cpl_file_completions);
25
26
27       CplFileConf *new_CplFileConf(void);
28
29
30       void cfc_file_start((CplFileConf *cfc, int start_index);
31
32
33       void cfc_literal_escapes(CplFileConf *cfc, int literal);
34
35
36       void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn,
37            void *chk_data);
38
39
40       CPL_CHECK_FN(cpl_check_exe);
41
42
43       CplFileConf *del_CplFileConf(CplFileConf *cfc);
44
45
46       CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line,
47            int word_end, void *data, CplMatchFn *match_fn);
48
49
50       CplMatches *cpl_recall_matches(WordCompletion *cpl);
51
52
53       int cpl_list_completions(CplMatches *result, FILE *fp, int term_width);
54
55
56       int cpl_add_completion(WordCompletion *cpl, const char *line,
57            int word_start, int word_end, const char *suffix,
58            const char *type_suffix, const char *cont_suffix);
59
60
61       void cpl_record_error(WordCompletion *cpl, const char *errmsg);
62
63
64       const char *cpl_last_error(WordCompletion *cpl);
65
66

DESCRIPTION

68       The cpl_complete_word() function is part of the libtecla(3LIB) library.
69       It  is usually called behind the scenes by gl_get_line(3TECLA), but can
70       also be called separately.
71
72
73       Given an input line containing an incomplete word to be  completed,  it
74       calls  a  user-provided callback function (or the provided file-comple‐
75       tion callback function) to look up all possible completion suffixes for
76       that  word.  The  callback function is expected to look backward in the
77       line, starting from the specified cursor position, to find the start of
78       the  word  to be completed, then to look up all possible completions of
79       that word and record them, one at a time,  by  calling  cpl_add_comple‐
80       tion().
81
82
83       The  new_WordCompletion()  function  creates  the resources used by the
84       cpl_complete_word() function. In particular, it  maintains  the  memory
85       that is used to return the results of calling cpl_complete_word().
86
87
88       The  del_WordCompletion()  function  deletes  the  resources  that were
89       returned by a previous call to new_WordCompletion(). It always  returns
90       NULL  (that  is, a deleted object). It takes no action if the cpl argu‐
91       ment is NULL.
92
93
94       The callback functions that look  up  possible  completions  should  be
95       defined  with  the  CPL_MATCH_FN()  macro,  which is defined in <libte‐
96       cla.h>. Functions of this type are called by  cpl_complete_word(),  and
97       all of the arguments of the callback are those that were passed to said
98       function. In particular, the line argument contains the input line con‐
99       taining  the  word  to  be  completed, and word_end is the index of the
100       character that follows the last character of the incomplete word within
101       this  string.  The callback is expected to look backwards from word_end
102       for the start of the incomplete word. What constitutes the start  of  a
103       word  clearly  depends  on  the  application, so it makes sense for the
104       callback to take on this responsibility. For example, the builtin file‐
105       name  completion  function  looks  backwards  until  it  encounters  an
106       unescaped space or the start of the line. Having found the start of the
107       word,  the callback should then lookup all possible completions of this
108       word, and record each completion with separate calls to cpl_add_comple‐
109       tion().  If the callback needs access to an application-specific symbol
110       table, it can pass it and any other data that it needs using  the  data
111       argument. This removes any need for global variables.
112
113
114       The callback function should return 0 if no errors occur. On failure it
115       should return 1 and register a terse description of the error by  call‐
116       ing cpl_record_error().
117
118
119       The  last error message recorded by calling cpl_record_error() can sub‐
120       sequently be queried by calling cpl_last_error().
121
122
123       The cpl_add_completion() function is called zero or more times  by  the
124       completion  callback function to record each possible completion in the
125       specified WordCompletion object.  These  completions  are  subsequently
126       returned  by cpl_complete_word(). The cpl, line, and word_end arguments
127       should be  those  that  were  passed  to  the  callback  function.  The
128       word_start argument should be the index within the input line string of
129       the start of the word  that  is  being  completed.  This  should  equal
130       word_end  if  a zero-length string is being completed. The suffix argu‐
131       ment is the string that would have to be  appended  to  the  incomplete
132       word  to complete it. If this needs any quoting (for example, the addi‐
133       tion of backslashes before special charaters) to be  valid  within  the
134       displayed  input  line,  this  should be included. A copy of the suffix
135       string is allocated internally, so there is no need  to  maintain  your
136       copy of the string after cpl_add_completion() returns.
137
138
139       In the array of possible completions that the cpl_complete_word() func‐
140       tion returns, the suffix recorded  by  cpl_add_completion()  is  listed
141       along  with  the  concatentation of this suffix with the word that lies
142       between word_start and word_end in the input line.
143
144
145       The type_suffix argument specifies an optional string to be appended to
146       the  completion  if it is displayed as part of a list of completions by
147       cpl_list_completions. The intention is that this indicate to  the  user
148       the  type of each completion. For example, the file completion function
149       places a directory separator after completions that are directories, to
150       indicate  their  nature to the user. Similary, if the completion were a
151       function, you could indicate this to the user by setting type_suffix to
152       "()".  Note  that the type_suffix string is not copied, so if the argu‐
153       ment is not a literal string between speech marks,  be  sure  that  the
154       string  remains  valid  for at least as long as the results of cpl_com‐
155       plete_word() are needed.
156
157
158       The cont_suffix argument is a continuation suffix to append to the com‐
159       pleted  word  in the input line if this is the only completion. This is
160       something that is not part of the completion itself, but that gives the
161       user  an  indication about how they might continue to extend the token.
162       For example, the file-completion callback  function  adds  a  directory
163       separator  if  the completed word is a directory. If the completed word
164       were a function name, you could similarly aid the user by arranging for
165       an open parenthesis to be appended.
166
167
168       The  cpl_complete_word()  is  normally  called  behind  the  scenes  by
169       gl_get_line(3TECLA), but can also be called  separately  if  you  sepa‐
170       rately  allocate  a WordCompletion object. It performs word completion,
171       as described at the beginning of this section. Its first argument is  a
172       resource  object  previously returned by new_WordCompletion(). The line
173       argument is the input line string, containing the word to be completed.
174       The  word_end argument contains the index of the character in the input
175       line, that just follows the last character of the word to be completed.
176       When called by gl_get_line(), this is the character over which the user
177       pressed TAB. The match_fn argument is the function pointer of the call‐
178       back  function  which  will lookup possible completions of the word, as
179       described above, and the data argument provides a way for the  applica‐
180       tion to pass arbitrary data to the callback function.
181
182
183       If  no errors occur, the cpl_complete_word() function returns a pointer
184       to a CplMatches container, as defined below. This  container  is  allo‐
185       cated as part of the cpl object that was passed to cpl_complete_word(),
186       and will thus change on each call which uses the same cpl argument.
187
188         typedef struct {
189             char *completion;        /* A matching completion */
190                                      /* string */
191             char *suffix;            /* The part of the */
192                                      /* completion string which */
193                                      /* would have to be */
194                                      /* appended to complete the */
195                                      /* original word. */
196             const char *type_suffix; /* A suffix to be added when */
197                                      /* listing completions, to */
198                                      /* indicate the type of the */
199                                      /* completion. */
200         } CplMatch;
201
202         typedef struct {
203             char *suffix;            /* The common initial part */
204                                      /* of all of the completion */
205                                      /* suffixes. */
206             const char *cont_suffix; /* Optional continuation */
207                                      /* string to be appended to */
208                                      /* the sole completion when */
209                                      /* nmatch==1. */
210             CplMatch *matches;       /* The array of possible */
211                                      /* completion strings, */
212                                      /* sorted into lexical */
213                                      /* order. */
214             int nmatch;              /* The number of elements in */
215                                      /* the above matches[] */
216                                      /* array. */
217         } CplMatches;
218
219
220
221       If an error occurs during completion, cpl_complete_word() returns NULL.
222       A   description   of   the   error  can  be  acquired  by  calling  the
223       cpl_last_error() function.
224
225
226       The cpl_last_error() function returns a terse description of the  error
227       which occurred on the last call to cpl_com plete_word() or cpl_add_com‐
228       pletion().
229
230
231       As a convenience, the  return  value  of  the  last  call  to  cpl_com‐
232       plete_word()   can   be   recalled   at   a   later   time  by  calling
233       cpl_recall_matches(). If cpl_complete_word()  returned  NULL,  so  will
234       cpl_recall_matches().
235
236
237       When the cpl_complete_word() function returns multiple possible comple‐
238       tions, the cpl_list_completions() function can be called upon  to  list
239       them,  suitably arranged across the available width of the terminal. It
240       arranges for the displayed columns of completions to all have the  same
241       width,  set  by the longest completion. It also appends the type_suffix
242       strings that were recorded with each completion, thus indicating  their
243       types to the user.
244
245   Builtin Filename completion Callback
246       By     default     the     gl_get_line()     function,    passes    the
247       CPL_MATCH_FN(cps_file_completions)  completion  callback  function   to
248       cpl_complete_word().  This function can also be used separately, either
249       by sending it to cpl_complete_word(), or by calling  it  directly  from
250       your own completion callback function.
251
252         #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
253                                       void *data, const char *line, \
254                                       int word_end)
255
256         typedef CPL_MATCH_FN(CplMatchFn);
257
258         CPL_MATCH_FN(cpl_file_completions);
259
260
261
262       Certain aspects of the behavior of this callback can be changed via its
263       data argument. If you are happy with its default behavior you can  pass
264       NULL  in  this argument. Otherwise it should be a pointer to a CplFile‐
265       Conf object, previously allocated by calling new_CplFileConf().
266
267
268       CplFileConf  objects  encapsulate  the  configuration   parameters   of
269       cpl_file_completions().  These parameters, which start out with default
270       values, can be changed by  calling  the  accessor  functions  described
271       below.
272
273
274       By default, the cpl_file_completions() callback function searches back‐
275       wards for the start of the filename being completed,  looking  for  the
276       first  unescaped  space  or the start of the input line. If you wish to
277       specify a different location, call cfc_file_start() with the  index  at
278       which  the  filename  starts  in the input line. Passing start_index=-1
279       reenables the default behavior.
280
281
282       By default, when cpl_file_completions() looks  at  a  filename  in  the
283       input  line,  each  lone  backslash in the input line is interpreted as
284       being a special character which removes any special significance of the
285       character  which  follows  it, such as a space which should be taken as
286       part of the filename rather than delimiting the start of the  filename.
287       These  backslashes  are thus ignored while looking for completions, and
288       subsequently added before spaces, tabs and literal back slashes in  the
289       list  of  completions. To have unescaped back slashes treated as normal
290       characters, call cfc_literal_escapes() with a  non-zero  value  in  its
291       literal argument.
292
293
294       By  default, cpl_file_completions() reports all files whose names start
295       with the prefix that is being completed. If you only  want  a  selected
296       subset  of  these  files to be reported in the list of completions, you
297       can arrange this by providing a callback function which takes the  full
298       pathname  of  a file, and returns 0 if the file should be ignored, or 1
299       if the file should be included in the list of completions. To  register
300       such    a    function   for   use   by   cpl_file_completions(),   call
301       cfc_set_check_fn(), and pass it a pointer  to  the  function,  together
302       with  a pointer to any data that you would like passed to this callback
303       whenever it is called. Your callback can make its  decisions  based  on
304       any property of the file, such as the filename itself, whether the file
305       is readable, writable or executable, or even based  on  what  the  file
306       contains.
307
308         #define CPL_CHECK_FN(fn) int (fn)(void *data, \
309                                                const char *pathname)
310
311         typedef CPL_CHECK_FN(CplCheckFn);
312
313         void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, \
314                                                      void *chk_data);
315
316
317
318       The  cpl_check_exe() function is a provided callback of the above type,
319       for use with cpl_file_completions(). It returns non-zero if  the  file‐
320       name  that  it is given represents a normal file that the user has exe‐
321       cute permission to. You could use this to  have  cpl_file_completions()
322       only list completions of executable files.
323
324
325       When  you have finished with a CplFileConf variable, you can pass it to
326       the del_CplFileConf() destructor function to reclaim its memory.
327
328   Thread Safety
329       It is safe to use the facilities of this module  in  multiple  threads,
330       provided  that  each  thread uses a separately allocated WordCompletion
331       object. In other words, if two threads want to do word completion, they
332       should  each call new_WordCompletion() to allocate their own completion
333       objects.
334

ATTRIBUTES

336       See attributes(5) for descriptions of the following attributes:
337
338
339
340
341       ┌─────────────────────────────┬─────────────────────────────┐
342       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
343       ├─────────────────────────────┼─────────────────────────────┤
344       │Interface Stability          │Evolving                     │
345       ├─────────────────────────────┼─────────────────────────────┤
346       │MT-Level                     │MT-Safe                      │
347       └─────────────────────────────┴─────────────────────────────┘
348

SEE ALSO

350       ef_expand_file(3TECLA),      gl_get_line(3TECLA),       libtecla(3LIB),
351       pca_lookup_file(3TECLA), attributes(5)
352
353
354
355SunOS 5.11                        1 Jun 2004         cpl_complete_word(3TECLA)
Impressum