xref: /titanic_41/usr/src/lib/libtecla/common/cplmatch.c (revision 7c478bd95313f5f23a4c958a745db2134aa03244)
1 /*
2  * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
3  *
4  * All rights reserved.
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a
7  * copy of this software and associated documentation files (the
8  * "Software"), to deal in the Software without restriction, including
9  * without limitation the rights to use, copy, modify, merge, publish,
10  * distribute, and/or sell copies of the Software, and to permit persons
11  * to whom the Software is furnished to do so, provided that the above
12  * copyright notice(s) and this permission notice appear in all copies of
13  * the Software and that both the above copyright notice(s) and this
14  * permission notice appear in supporting documentation.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
17  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
19  * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
20  * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
21  * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
22  * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
23  * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
24  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25  *
26  * Except as contained in this notice, the name of a copyright holder
27  * shall not be used in advertising or otherwise to promote the sale, use
28  * or other dealings in this Software without prior written authorization
29  * of the copyright holder.
30  */
31 
32 /*
33  * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
34  * Use is subject to license terms.
35  */
36 
37 #pragma ident	"%Z%%M%	%I%	%E% SMI"
38 
39 /*
40  * Standard includes.
41  */
42 #include <stdlib.h>
43 #include <stdio.h>
44 #include <string.h>
45 #include <errno.h>
46 
47 /*
48  * Local includes.
49  */
50 #include "libtecla.h"
51 #include "ioutil.h"
52 #include "stringrp.h"
53 #include "pathutil.h"
54 #include "cplfile.h"
55 #include "cplmatch.h"
56 #include "errmsg.h"
57 
58 /*
59  * Specify the number of strings to allocate when the string free-list
60  * is exhausted. This also sets the number of elements to expand the
61  * matches[] array by whenever it is found to be too small.
62  */
63 #define STR_BLK_FACT 100
64 
65 /*
66  * Set the default number of spaces place between columns when listing
67  * a set of completions.
68  */
69 #define CPL_COL_SEP 2
70 
71 /*
72  * Completion matches are recorded in containers of the following
73  * type.
74  */
75 struct WordCompletion {
76   ErrMsg *err;            /* The error reporting buffer */
77   StringGroup *sg;        /* Memory for a group of strings */
78   int matches_dim;        /* The allocated size of result.matches[] */
79   CplMatches result;      /* Completions to be returned to the caller */
80 #ifndef WITHOUT_FILE_SYSTEM
81   CompleteFile *cf;       /* The resources used for filename completion */
82 #endif
83 };
84 
85 static void cpl_sort_matches(WordCompletion *cpl);
86 static void cpl_zap_duplicates(WordCompletion *cpl);
87 static void cpl_clear_completions(WordCompletion *cpl);
88 static int cpl_cmp_matches(const void *v1, const void *v2);
89 static int cpl_cmp_suffixes(const void *v1, const void *v2);
90 
91 /*
92  * The new_CplFileConf() constructor sets the integer first member of
93  * the returned object to the following magic number. On seeing this,
94  * cpl_file_completions() knows when it is passed a valid CplFileConf
95  * object.
96  */
97 #define CFC_ID_CODE 4568
98 
99 #ifndef WITHOUT_FILE_SYSTEM
100 /*
101  * A pointer to a structure of the following type can be passed to
102  * the builtin file-completion callback function to modify its behavior.
103  */
104 struct CplFileConf {
105   int id;             /* new_CplFileConf() sets this to CFC_ID_CODE */
106   int escaped;        /* If none-zero, backslashes in the input line are */
107                       /*  interpreted as escaping special characters and */
108                       /*  spaces, and any special characters and spaces in */
109                       /*  the listed completions will also be escaped with */
110                       /*  added backslashes. This is the default behaviour. */
111                       /* If zero, backslashes are interpreted as being */
112                       /*  literal parts of the filename, and none are added */
113                       /*  to the completion suffixes. */
114   int file_start;     /* The index in the input line of the first character */
115                       /*  of the filename. If you specify -1 here, */
116                       /*  cpl_file_completions() identifies the */
117                       /*  the start of the filename by looking backwards for */
118                       /*  an unescaped space, or the beginning of the line. */
119   CplCheckFn *chk_fn; /* If not zero, this argument specifies a */
120                       /*  function to call to ask whether a given */
121                       /*  file should be included in the list */
122                       /*  of completions. */
123   void *chk_data;     /* Anonymous data to be passed to check_fn(). */
124 };
125 
126 static void cpl_init_FileConf(CplFileConf *cfc);
127 
128 /*
129  * When file-system access is being excluded, define a dummy structure
130  * to satisfy the typedef in libtecla.h.
131  */
132 #else
133 struct CplFileConf {int dummy;};
134 #endif
135 
136 /*
137  * Encapsulate the formatting information needed to layout a
138  * multi-column listing of completions.
139  */
140 typedef struct {
141   int term_width;     /* The width of the terminal (characters) */
142   int column_width;   /* The number of characters within in each column. */
143   int ncol;           /* The number of columns needed */
144   int nline;          /* The number of lines needed */
145 } CplListFormat;
146 
147 /*
148  * Given the current terminal width, and a list of completions, determine
149  * how to best use the terminal width to display a multi-column listing
150  * of completions.
151  */
152 static void cpl_plan_listing(CplMatches *result, int term_width,
153 			     CplListFormat *fmt);
154 
155 /*
156  * Display a given line of a multi-column list of completions.
157  */
158 static int cpl_format_line(CplMatches *result, CplListFormat *fmt, int lnum,
159 			   GlWriteFn *write_fn, void *data);
160 
161 /*.......................................................................
162  * Create a new string-completion object.
163  *
164  * Output:
165  *  return    WordCompletion *  The new object, or NULL on error.
166  */
new_WordCompletion(void)167 WordCompletion *new_WordCompletion(void)
168 {
169   WordCompletion *cpl;  /* The object to be returned */
170 /*
171  * Allocate the container.
172  */
173   cpl = (WordCompletion *) malloc(sizeof(WordCompletion));
174   if(!cpl) {
175     errno = ENOMEM;
176     return NULL;
177   };
178 /*
179  * Before attempting any operation that might fail, initialize the
180  * container at least up to the point at which it can safely be passed
181  * to del_WordCompletion().
182  */
183   cpl->err = NULL;
184   cpl->sg = NULL;
185   cpl->matches_dim = 0;
186   cpl->result.suffix = NULL;
187   cpl->result.cont_suffix = NULL;
188   cpl->result.matches = NULL;
189   cpl->result.nmatch = 0;
190 #ifndef WITHOUT_FILE_SYSTEM
191   cpl->cf = NULL;
192 #endif
193 /*
194  * Allocate a place to record error messages.
195  */
196   cpl->err = _new_ErrMsg();
197   if(!cpl->err)
198     return del_WordCompletion(cpl);
199 /*
200  * Allocate an object that allows a group of strings to be allocated
201  * efficiently by placing many of them in contiguous string segments.
202  */
203 #ifdef WITHOUT_FILE_SYSTEM
204   cpl->sg = _new_StringGroup(MAX_PATHLEN_FALLBACK);
205 #else
206   cpl->sg = _new_StringGroup(_pu_pathname_dim());
207 #endif
208   if(!cpl->sg)
209     return del_WordCompletion(cpl);
210 /*
211  * Allocate an array for matching completions. This will be extended later
212  * if needed.
213  */
214   cpl->matches_dim = STR_BLK_FACT;
215   cpl->result.matches = (CplMatch *) malloc(sizeof(cpl->result.matches[0]) *
216 					    cpl->matches_dim);
217   if(!cpl->result.matches) {
218     errno = ENOMEM;
219     return del_WordCompletion(cpl);
220   };
221 /*
222  * Allocate a filename-completion resource object.
223  */
224 #ifndef WITHOUT_FILE_SYSTEM
225   cpl->cf = _new_CompleteFile();
226   if(!cpl->cf)
227     return del_WordCompletion(cpl);
228 #endif
229   return cpl;
230 }
231 
232 /*.......................................................................
233  * Delete a string-completion object.
234  *
235  * Input:
236  *  cpl    WordCompletion *  The object to be deleted.
237  * Output:
238  *  return WordCompletion *  The deleted object (always NULL).
239  */
del_WordCompletion(WordCompletion * cpl)240 WordCompletion *del_WordCompletion(WordCompletion *cpl)
241 {
242   if(cpl) {
243     cpl->err = _del_ErrMsg(cpl->err);
244     cpl->sg = _del_StringGroup(cpl->sg);
245     if(cpl->result.matches) {
246       free(cpl->result.matches);
247       cpl->result.matches = NULL;
248 #ifndef WITHOUT_FILE_SYSTEM
249       cpl->cf = _del_CompleteFile(cpl->cf);
250 #endif
251     };
252     free(cpl);
253   };
254   return NULL;
255 }
256 
257 /*.......................................................................
258  * This function is designed to be called by CplMatchFn callback
259  * functions. It adds one possible completion of the token that is being
260  * completed to an array of completions. If the completion needs any
261  * special quoting to be valid when displayed in the input line, this
262  * quoting must be included in the string.
263  *
264  * Input:
265  *  cpl     WordCompletion *  The argument of the same name that was passed
266  *                            to the calling CplMatchFn callback function.
267  *  line        const char *  The input line, as received by the callback
268  *                            function.
269  *  word_start         int    The index within line[] of the start of the
270  *                            word that is being completed.
271  *  word_end           int    The index within line[] of the character which
272  *                            follows the incomplete word, as received by the
273  *                            calling callback function.
274  *  suffix      const char *  The appropriately quoted string that could
275  *                            be appended to the incomplete token to complete
276  *                            it. A copy of this string will be allocated
277  *                            internally.
278  *  type_suffix const char *  When listing multiple completions, gl_get_line()
279  *                            appends this string to the completion to indicate
280  *                            its type to the user. If not pertinent pass "".
281  *                            Otherwise pass a literal or static string.
282  *  cont_suffix const char *  If this turns out to be the only completion,
283  *                            gl_get_line() will append this string as
284  *                            a continuation. For example, the builtin
285  *                            file-completion callback registers a directory
286  *                            separator here for directory matches, and a
287  *                            space otherwise. If the match were a function
288  *                            name you might want to append an open
289  *                            parenthesis, etc.. If not relevant pass "".
290  *                            Otherwise pass a literal or static string.
291  * Output:
292  *  return             int    0 - OK.
293  *                            1 - Error.
294  */
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)295 int cpl_add_completion(WordCompletion *cpl, const char *line,
296 		       int word_start, int word_end, const char *suffix,
297 		       const char *type_suffix, const char *cont_suffix)
298 {
299   CplMatch *match; /* The container of the new match */
300   char *string;    /* A newly allocated copy of the completion string */
301   size_t len;
302 /*
303  * Check the arguments.
304  */
305   if(!cpl)
306     return 1;
307   if(!suffix)
308     return 0;
309   if(!type_suffix)
310     type_suffix = "";
311   if(!cont_suffix)
312     cont_suffix = "";
313 /*
314  * Do we need to extend the array of matches[]?
315  */
316   if(cpl->result.nmatch+1 > cpl->matches_dim) {
317     int needed = cpl->matches_dim + STR_BLK_FACT;
318     CplMatch *matches = (CplMatch *) realloc(cpl->result.matches,
319 			    sizeof(cpl->result.matches[0]) * needed);
320     if(!matches) {
321       _err_record_msg(cpl->err,
322 		      "Insufficient memory to extend array of matches.",
323 		      END_ERR_MSG);
324       return 1;
325     };
326     cpl->result.matches = matches;
327     cpl->matches_dim = needed;
328   };
329 /*
330  * Allocate memory to store the combined completion prefix and the
331  * new suffix.
332  */
333   len = strlen(suffix);
334   string = _sg_alloc_string(cpl->sg, word_end-word_start + len);
335   if(!string) {
336     _err_record_msg(cpl->err, "Insufficient memory to extend array of matches.",
337 		    END_ERR_MSG);
338     return 1;
339   };
340 /*
341  * Compose the string.
342  */
343   strncpy(string, line + word_start, word_end - word_start);
344   strlcpy(string + word_end - word_start, suffix, len + 1);
345 /*
346  * Record the new match.
347  */
348   match = cpl->result.matches + cpl->result.nmatch++;
349   match->completion = string;
350   match->suffix = string + word_end - word_start;
351   match->type_suffix = type_suffix;
352 /*
353  * Record the continuation suffix.
354  */
355   cpl->result.cont_suffix = cont_suffix;
356   return 0;
357 }
358 
359 /*.......................................................................
360  * Sort the array of matches.
361  *
362  * Input:
363  *  cpl   WordCompletion *  The completion resource object.
364  */
cpl_sort_matches(WordCompletion * cpl)365 static void cpl_sort_matches(WordCompletion *cpl)
366 {
367   qsort(cpl->result.matches, cpl->result.nmatch,
368 	sizeof(cpl->result.matches[0]), cpl_cmp_matches);
369 }
370 
371 /*.......................................................................
372  * This is a qsort() comparison function used to sort matches.
373  *
374  * Input:
375  *  v1, v2   void *  Pointers to the two matches to be compared.
376  * Output:
377  *  return    int    -1 -> v1 < v2.
378  *                    0 -> v1 == v2
379  *                    1 -> v1 > v2
380  */
cpl_cmp_matches(const void * v1,const void * v2)381 static int cpl_cmp_matches(const void *v1, const void *v2)
382 {
383   const CplMatch *m1 = (const CplMatch *) v1;
384   const CplMatch *m2 = (const CplMatch *) v2;
385   return strcmp(m1->completion, m2->completion);
386 }
387 
388 /*.......................................................................
389  * Sort the array of matches in order of their suffixes.
390  *
391  * Input:
392  *  cpl   WordCompletion *  The completion resource object.
393  */
cpl_sort_suffixes(WordCompletion * cpl)394 static void cpl_sort_suffixes(WordCompletion *cpl)
395 {
396   qsort(cpl->result.matches, cpl->result.nmatch,
397 	sizeof(cpl->result.matches[0]), cpl_cmp_suffixes);
398 }
399 
400 /*.......................................................................
401  * This is a qsort() comparison function used to sort matches in order of
402  * their suffixes.
403  *
404  * Input:
405  *  v1, v2   void *  Pointers to the two matches to be compared.
406  * Output:
407  *  return    int    -1 -> v1 < v2.
408  *                    0 -> v1 == v2
409  *                    1 -> v1 > v2
410  */
cpl_cmp_suffixes(const void * v1,const void * v2)411 static int cpl_cmp_suffixes(const void *v1, const void *v2)
412 {
413   const CplMatch *m1 = (const CplMatch *) v1;
414   const CplMatch *m2 = (const CplMatch *) v2;
415   return strcmp(m1->suffix, m2->suffix);
416 }
417 
418 /*.......................................................................
419  * Find the common prefix of all of the matching completion matches,
420  * and record a pointer to it in cpl->result.suffix. Note that this has
421  * the side effect of sorting the matches into suffix order.
422  *
423  * Input:
424  *  cpl   WordCompletion *  The completion resource object.
425  * Output:
426  *  return           int    0 - OK.
427  *                          1 - Error.
428  */
cpl_common_suffix(WordCompletion * cpl)429 static int cpl_common_suffix(WordCompletion *cpl)
430 {
431   CplMatches *result;       /* The result container */
432   const char *first, *last; /* The first and last matching suffixes */
433   int length;               /* The length of the common suffix */
434 /*
435  * Get the container of the array of matching files.
436  */
437   result = &cpl->result;
438 /*
439  * No matching completions?
440  */
441   if(result->nmatch < 1)
442     return 0;
443 /*
444  * Sort th matches into suffix order.
445  */
446   cpl_sort_suffixes(cpl);
447 /*
448  * Given that the array of matches is sorted, the first and last
449  * suffixes are those that differ most in their prefixes, so the common
450  * prefix of these strings is the longest common prefix of all of the
451  * suffixes.
452  */
453   first = result->matches[0].suffix;
454   last = result->matches[result->nmatch - 1].suffix;
455 /*
456  * Find the point at which the first and last matching strings
457  * first difffer.
458  */
459   while(*first && *first == *last) {
460     first++;
461     last++;
462   };
463 /*
464  * How long is the common suffix?
465  */
466   length = first - result->matches[0].suffix;
467 /*
468  * Allocate memory to record the common suffix.
469  */
470   result->suffix = _sg_alloc_string(cpl->sg, length);
471   if(!result->suffix) {
472     _err_record_msg(cpl->err,
473 		    "Insufficient memory to record common completion suffix.",
474 		    END_ERR_MSG);
475     return 1;
476   };
477 /*
478  * Record the common suffix.
479  */
480   strncpy(result->suffix, result->matches[0].suffix, length);
481   result->suffix[length] = '\0';
482   return 0;
483 }
484 
485 /*.......................................................................
486  * Discard the contents of the array of possible completion matches.
487  *
488  * Input:
489  *  cpl   WordCompletion *  The word-completion resource object.
490  */
cpl_clear_completions(WordCompletion * cpl)491 static void cpl_clear_completions(WordCompletion *cpl)
492 {
493 /*
494  * Discard all of the strings.
495  */
496   _clr_StringGroup(cpl->sg);
497 /*
498  * Record the fact that the array is now empty.
499  */
500   cpl->result.nmatch = 0;
501   cpl->result.suffix = NULL;
502   cpl->result.cont_suffix = "";
503 /*
504  * Also clear the error message.
505  */
506   _err_clear_msg(cpl->err);
507   return;
508 }
509 
510 /*.......................................................................
511  * Given an input line and the point at which it completion is to be
512  * attempted, return an array of possible completions.
513  *
514  * Input:
515  *  cpl    WordCompletion *  The completion resource object.
516  *  line             char *  The current input line.
517  *  word_end          int    The index of the character in line[] which
518  *                           follows the end of the token that is being
519  *                           completed.
520  *  data             void *  Anonymous 'data' to be passed to match_fn().
521  *  match_fn   CplMatchFn *  The function that will identify the prefix
522  *                           to be completed from the input line, and
523  *                           record completion matches.
524  * Output:
525  *  return     CplMatches *  The container of the array of possible
526  *                           completions. The returned pointer refers
527  *                           to a container owned by the parent WordCompletion
528  *                           object, and its contents thus potentially
529  *                           change on every call to cpl_matches().
530  *                           On error, NULL is returned, and a description
531  *                           of the error can be acquired by calling
532  *                           cpl_last_error(cpl).
533  */
cpl_complete_word(WordCompletion * cpl,const char * line,int word_end,void * data,CplMatchFn * match_fn)534 CplMatches *cpl_complete_word(WordCompletion *cpl, const char *line,
535 			      int word_end, void *data,
536 			      CplMatchFn *match_fn)
537 {
538   int line_len;   /* The total length of the input line */
539 /*
540  * How long is the input line?
541  */
542   line_len = strlen(line);
543 /*
544  * Check the arguments.
545  */
546   if(!cpl || !line || !match_fn || word_end < 0 || word_end > line_len) {
547     if(cpl) {
548       _err_record_msg(cpl->err, "cpl_complete_word: Invalid arguments.",
549 		      END_ERR_MSG);
550     };
551     return NULL;
552   };
553 /*
554  * Clear the return container.
555  */
556   cpl_clear_completions(cpl);
557 /*
558  * Have the matching function record possible completion matches in
559  * cpl->result.matches.
560  */
561   if(match_fn(cpl, data, line, word_end)) {
562     if(_err_get_msg(cpl->err)[0] == '\0')
563       _err_record_msg(cpl->err, "Error completing word.", END_ERR_MSG);
564     return NULL;
565   };
566 /*
567  * Record a copy of the common initial part of all of the prefixes
568  * in cpl->result.common.
569  */
570   if(cpl_common_suffix(cpl))
571     return NULL;
572 /*
573  * Sort the matches into lexicographic order.
574  */
575   cpl_sort_matches(cpl);
576 /*
577  * Discard any duplicate matches.
578  */
579   cpl_zap_duplicates(cpl);
580 /*
581  * If there is more than one match, discard the continuation suffix.
582  */
583   if(cpl->result.nmatch > 1)
584     cpl->result.cont_suffix = "";
585 /*
586  * Return the array of matches.
587  */
588   return &cpl->result;
589 }
590 
591 /*.......................................................................
592  * Recall the return value of the last call to cpl_complete_word().
593  *
594  * Input:
595  *  cpl    WordCompletion *  The completion resource object.
596  * Output:
597  *  return     CplMatches *  The container of the array of possible
598  *                           completions, as returned by the last call to
599  *                           cpl_complete_word(). The returned pointer refers
600  *                           to a container owned by the parent WordCompletion
601  *                           object, and its contents thus potentially
602  *                           change on every call to cpl_complete_word().
603  *                           On error, either in the execution of this
604  *                           function, or in the last call to
605  *                           cpl_complete_word(), NULL is returned, and a
606  *                           description of the error can be acquired by
607  *                           calling cpl_last_error(cpl).
608  */
cpl_recall_matches(WordCompletion * cpl)609 CplMatches *cpl_recall_matches(WordCompletion *cpl)
610 {
611   return (!cpl || *_err_get_msg(cpl->err)!='\0') ? NULL : &cpl->result;
612 }
613 
614 /*.......................................................................
615  * Print out an array of matching completions.
616  *
617  * Input:
618  *  result  CplMatches *   The container of the sorted array of
619  *                         completions.
620  *  fp            FILE *   The output stream to write to.
621  *  term_width     int     The width of the terminal.
622  * Output:
623  *  return         int     0 - OK.
624  *                         1 - Error.
625  */
cpl_list_completions(CplMatches * result,FILE * fp,int term_width)626 int cpl_list_completions(CplMatches *result, FILE *fp, int term_width)
627 {
628   return _cpl_output_completions(result, _io_write_stdio, fp, term_width);
629 }
630 
631 /*.......................................................................
632  * Print an array of matching completions via a callback function.
633  *
634  * Input:
635  *  result   CplMatches *  The container of the sorted array of
636  *                         completions.
637  *  write_fn  GlWriteFn *  The function to call to write the completions,
638  *                         or 0 to discard the output.
639  *  data           void *  Anonymous data to pass to write_fn().
640  *  term_width      int    The width of the terminal.
641  * Output:
642  *  return          int     0 - OK.
643  *                          1 - Error.
644  */
_cpl_output_completions(CplMatches * result,GlWriteFn * write_fn,void * data,int term_width)645 int _cpl_output_completions(CplMatches *result, GlWriteFn *write_fn, void *data,
646 			    int term_width)
647 {
648   CplListFormat fmt; /* List formatting information */
649   int lnum;          /* The sequential number of the line to print next */
650 /*
651  * Not enough space to list anything?
652  */
653   if(term_width < 1)
654     return 0;
655 /*
656  * Do we have a callback to write via, and any completions to be listed?
657  */
658   if(write_fn && result && result->nmatch>0) {
659 /*
660  * Work out how to arrange the listing into fixed sized columns.
661  */
662     cpl_plan_listing(result, term_width, &fmt);
663 /*
664  * Print the listing via the specified callback.
665  */
666     for(lnum=0; lnum < fmt.nline; lnum++) {
667       if(cpl_format_line(result, &fmt, lnum, write_fn, data))
668 	return 1;
669     };
670   };
671   return 0;
672 }
673 
674 /*.......................................................................
675  * Return a description of the string-completion error that occurred.
676  *
677  * Input:
678  *  cpl   WordCompletion *  The string-completion resource object.
679  * Output:
680  *  return    const char *  The description of the last error.
681  */
cpl_last_error(WordCompletion * cpl)682 const char *cpl_last_error(WordCompletion *cpl)
683 {
684   return cpl ? _err_get_msg(cpl->err) : "NULL WordCompletion argument";
685 }
686 
687 /*.......................................................................
688  * When an error occurs while performing a completion, you registerf a
689  * terse description of the error by calling cpl_record_error(). This
690  * message will then be returned on the next call to cpl_last_error().
691  *
692  * Input:
693  *  cpl   WordCompletion *  The string-completion resource object that was
694  *                          originally passed to the callback.
695  *  errmsg    const char *  The description of the error.
696  */
cpl_record_error(WordCompletion * cpl,const char * errmsg)697 void cpl_record_error(WordCompletion *cpl, const char *errmsg)
698 {
699   if(cpl && errmsg)
700     _err_record_msg(cpl->err, errmsg, END_ERR_MSG);
701 }
702 
703 /*.......................................................................
704  * This is the builtin completion callback function which performs file
705  * completion.
706  *
707  * Input:
708  *  cpl  WordCompletion *  An opaque pointer to the object that will
709  *                         contain the matches. This should be filled
710  *                         via zero or more calls to cpl_add_completion().
711  *  data           void *  Either NULL to request the default
712  *                         file-completion behavior, or a pointer to a
713  *                         CplFileConf structure, whose members specify
714  *                         a different behavior.
715  *  line           char *  The current input line.
716  *  word_end        int    The index of the character in line[] which
717  *                         follows the end of the token that is being
718  *                         completed.
719  * Output
720  *  return          int    0 - OK.
721  *                         1 - Error.
722  */
CPL_MATCH_FN(cpl_file_completions)723 CPL_MATCH_FN(cpl_file_completions)
724 {
725 #ifdef WITHOUT_FILE_SYSTEM
726   return 0;
727 #else
728   const char *start_path;  /* The pointer to the start of the pathname */
729                            /*  in line[]. */
730   CplFileConf *conf;       /* The new-style configuration object. */
731 /*
732  * The following configuration object will be used if the caller didn't
733  * provide one.
734  */
735   CplFileConf default_conf;
736 /*
737  * This function can be called externally, so check its arguments.
738  */
739   if(!cpl)
740     return 1;
741   if(!line || word_end < 0) {
742     _err_record_msg(cpl->err, "cpl_file_completions: Invalid arguments.",
743 		    END_ERR_MSG);
744     return 1;
745   };
746 /*
747  * The 'data' argument is either a CplFileConf pointer, identifiable
748  * by having an integer id code as its first member, or the deprecated
749  * CplFileArgs pointer, or can be NULL to request the default
750  * configuration.
751  */
752   if(data && *(int *)data == CFC_ID_CODE) {
753     conf = (CplFileConf *) data;
754   } else {
755 /*
756  * Select the defaults.
757  */
758     conf = &default_conf;
759     cpl_init_FileConf(&default_conf);
760 /*
761  * If we have been passed an instance of the deprecated CplFileArgs
762  * structure, copy its configuration parameters over the defaults.
763  */
764     if(data) {
765       CplFileArgs *args = (CplFileArgs *) data;
766       conf->escaped = args->escaped;
767       conf->file_start = args->file_start;
768     };
769   };
770 /*
771  * Get the start of the filename. If not specified by the caller
772  * identify it by searching backwards in the input line for an
773  * unescaped space or the start of the line.
774  */
775   if(conf->file_start < 0) {
776     start_path = _pu_start_of_path(line, word_end);
777     if(!start_path) {
778       _err_record_msg(cpl->err, "Unable to find the start of the filename.",
779 		      END_ERR_MSG);
780       return 1;
781     };
782   } else {
783     start_path = line + conf->file_start;
784   };
785 /*
786  * Perform the completion.
787  */
788   if(_cf_complete_file(cpl, cpl->cf, line, start_path - line, word_end,
789 		      conf->escaped, conf->chk_fn, conf->chk_data)) {
790     cpl_record_error(cpl, _cf_last_error(cpl->cf));
791     return 1;
792   };
793   return 0;
794 #endif
795 }
796 
797 /*.......................................................................
798  * Initialize a CplFileArgs structure with default configuration
799  * parameters. Note that the CplFileArgs configuration type is
800  * deprecated. The opaque CplFileConf object should be used in future
801  * applications.
802  *
803  * Input:
804  *  cfa  CplFileArgs *  The configuration object of the
805  *                      cpl_file_completions() callback.
806  */
cpl_init_FileArgs(CplFileArgs * cfa)807 void cpl_init_FileArgs(CplFileArgs *cfa)
808 {
809   if(cfa) {
810     cfa->escaped = 1;
811     cfa->file_start = -1;
812   };
813 }
814 
815 #ifndef WITHOUT_FILE_SYSTEM
816 /*.......................................................................
817  * Initialize a CplFileConf structure with default configuration
818  * parameters.
819  *
820  * Input:
821  *  cfc  CplFileConf *  The configuration object of the
822  *                      cpl_file_completions() callback.
823  */
cpl_init_FileConf(CplFileConf * cfc)824 static void cpl_init_FileConf(CplFileConf *cfc)
825 {
826   if(cfc) {
827     cfc->id = CFC_ID_CODE;
828     cfc->escaped = 1;
829     cfc->file_start = -1;
830     cfc->chk_fn = 0;
831     cfc->chk_data = NULL;
832   };
833 }
834 #endif
835 
836 /*.......................................................................
837  * Create a new CplFileConf object and initialize it with defaults.
838  *
839  * Output:
840  *  return  CplFileConf *  The new object, or NULL on error.
841  */
new_CplFileConf(void)842 CplFileConf *new_CplFileConf(void)
843 {
844 #ifdef WITHOUT_FILE_SYSTEM
845   errno = EINVAL;
846   return NULL;
847 #else
848   CplFileConf *cfc;  /* The object to be returned */
849 /*
850  * Allocate the container.
851  */
852   cfc = (CplFileConf *)malloc(sizeof(CplFileConf));
853   if(!cfc)
854     return NULL;
855 /*
856  * Before attempting any operation that might fail, initialize the
857  * container at least up to the point at which it can safely be passed
858  * to del_CplFileConf().
859  */
860   cpl_init_FileConf(cfc);
861   return cfc;
862 #endif
863 }
864 
865 /*.......................................................................
866  * Delete a CplFileConf object.
867  *
868  * Input:
869  *  cfc    CplFileConf *  The object to be deleted.
870  * Output:
871  *  return CplFileConf *  The deleted object (always NULL).
872  */
del_CplFileConf(CplFileConf * cfc)873 CplFileConf *del_CplFileConf(CplFileConf *cfc)
874 {
875 #ifndef WITHOUT_FILE_SYSTEM
876   if(cfc) {
877 /*
878  * Delete the container.
879  */
880     free(cfc);
881   };
882 #endif
883   return NULL;
884 }
885 
886 /*.......................................................................
887  * If backslashes in the filename should be treated as literal
888  * characters, call the following function with literal=1. Otherwise
889  * the default is to treat them as escape characters, used for escaping
890  * spaces etc..
891  *
892  * Input:
893  *  cfc    CplFileConf *  The cpl_file_completions() configuration object
894  *                        to be configured.
895  *  literal        int    Pass non-zero here to enable literal interpretation
896  *                        of backslashes. Pass 0 to turn off literal
897  *                        interpretation.
898  */
cfc_literal_escapes(CplFileConf * cfc,int literal)899 void cfc_literal_escapes(CplFileConf *cfc, int literal)
900 {
901 #ifndef WITHOUT_FILE_SYSTEM
902   if(cfc)
903     cfc->escaped = !literal;
904 #endif
905 }
906 
907 /*.......................................................................
908  * Call this function if you know where the index at which the
909  * filename prefix starts in the input line. Otherwise by default,
910  * or if you specify start_index to be -1, the filename is taken
911  * to start after the first unescaped space preceding the cursor,
912  * or the start of the line, which ever comes first.
913  *
914  * Input:
915  *  cfc    CplFileConf *  The cpl_file_completions() configuration object
916  *                        to be configured.
917  *  start_index    int    The index of the start of the filename in
918  *                        the input line, or -1 to select the default.
919  */
cfc_file_start(CplFileConf * cfc,int start_index)920 void cfc_file_start(CplFileConf *cfc, int start_index)
921 {
922 #ifndef WITHOUT_FILE_SYSTEM
923   if(cfc)
924     cfc->file_start = start_index;
925 #endif
926 }
927 
928 /*.......................................................................
929  * If you only want certain types of files to be included in the
930  * list of completions, you use the following function to specify a
931  * callback function which will be called to ask whether a given file
932  * should be included.
933  *
934  * Input:
935  *  cfc    CplFileConf *  The cpl_file_completions() configuration object
936  *                        to be configured.
937  *  chk_fn  CplCheckFn *  Zero to disable filtering, or a pointer to a
938  *                        function that returns 1 if a given file should
939  *                        be included in the list of completions.
940  *  chk_data      void *  Anonymous data to be passed to chk_fn()
941  *                        every time that it is called.
942  */
cfc_set_check_fn(CplFileConf * cfc,CplCheckFn * chk_fn,void * chk_data)943 void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn, void *chk_data)
944 {
945 #ifndef WITHOUT_FILE_SYSTEM
946   if(cfc) {
947     cfc->chk_fn = chk_fn;
948     cfc->chk_data = chk_data;
949   };
950 #endif
951 }
952 
953 /*.......................................................................
954  * The following CplCheckFn callback returns non-zero if the specified
955  * filename is that of an executable.
956  */
CPL_CHECK_FN(cpl_check_exe)957 CPL_CHECK_FN(cpl_check_exe)
958 {
959 #ifdef WITHOUT_FILE_SYSTEM
960   return 0;
961 #else
962   return _pu_path_is_exe(pathname);
963 #endif
964 }
965 
966 /*.......................................................................
967  * Remove duplicates from a sorted array of matches.
968  *
969  * Input:
970  *  cpl   WordCompletion *  The completion resource object.
971  */
cpl_zap_duplicates(WordCompletion * cpl)972 static void cpl_zap_duplicates(WordCompletion *cpl)
973 {
974   CplMatch *matches;       /* The array of matches */
975   int nmatch;              /* The number of elements in matches[] */
976   const char *completion;  /* The completion string of the last unique match */
977   const char *type_suffix; /* The type of the last unique match */
978   int src;                 /* The index of the match being considered */
979   int dst;                 /* The index at which to record the next */
980                            /*  unique match. */
981 /*
982  * Get the array of matches and the number of matches that it
983  * contains.
984  */
985   matches = cpl->result.matches;
986   nmatch = cpl->result.nmatch;
987 /*
988  * No matches?
989  */
990   if(nmatch < 1)
991     return;
992 /*
993  * Initialize the comparison strings with the first match.
994  */
995   completion = matches[0].completion;
996   type_suffix = matches[0].type_suffix;
997 /*
998  * Go through the array of matches, copying each new unrecorded
999  * match at the head of the array, while discarding duplicates.
1000  */
1001   for(src=dst=1; src<nmatch; src++) {
1002     CplMatch *match = matches + src;
1003     if(strcmp(completion, match->completion) != 0 ||
1004        strcmp(type_suffix, match->type_suffix) != 0) {
1005       if(src != dst)
1006 	matches[dst] = *match;
1007       dst++;
1008       completion = match->completion;
1009       type_suffix = match->type_suffix;
1010     };
1011   };
1012 /*
1013  * Record the number of unique matches that remain.
1014  */
1015   cpl->result.nmatch = dst;
1016   return;
1017 }
1018 
1019 /*.......................................................................
1020  * Work out how to arrange a given array of completions into a listing
1021  * of one or more fixed size columns.
1022  *
1023  * Input:
1024  *  result   CplMatches *   The set of completions to be listed.
1025  *  term_width      int     The width of the terminal. A lower limit of
1026  *                          zero is quietly enforced.
1027  * Input/Output:
1028  *  fmt   CplListFormat *   The formatting information will be assigned
1029  *                          to the members of *fmt.
1030  */
cpl_plan_listing(CplMatches * result,int term_width,CplListFormat * fmt)1031 static void cpl_plan_listing(CplMatches *result, int term_width,
1032 			     CplListFormat *fmt)
1033 {
1034   int maxlen;    /* The length of the longest matching string */
1035   int i;
1036 /*
1037  * Ensure that term_width >= 0.
1038  */
1039   if(term_width < 0)
1040     term_width = 0;
1041 /*
1042  * Start by assuming the worst case, that either nothing will fit
1043  * on the screen, or that there are no matches to be listed.
1044  */
1045   fmt->term_width = term_width;
1046   fmt->column_width = 0;
1047   fmt->nline = fmt->ncol = 0;
1048 /*
1049  * Work out the maximum length of the matching strings.
1050  */
1051   maxlen = 0;
1052   for(i=0; i<result->nmatch; i++) {
1053     CplMatch *match = result->matches + i;
1054     int len = strlen(match->completion) + strlen(match->type_suffix);
1055     if(len > maxlen)
1056       maxlen = len;
1057   };
1058 /*
1059  * Nothing to list?
1060  */
1061   if(maxlen == 0)
1062     return;
1063 /*
1064  * Split the available terminal width into columns of
1065  * maxlen + CPL_COL_SEP characters.
1066  */
1067   fmt->column_width = maxlen;
1068   fmt->ncol = fmt->term_width / (fmt->column_width + CPL_COL_SEP);
1069 /*
1070  * If the column width is greater than the terminal width, zero columns
1071  * will have been selected. Set a lower limit of one column. Leave it
1072  * up to the caller how to deal with completions who's widths exceed
1073  * the available terminal width.
1074  */
1075   if(fmt->ncol < 1)
1076     fmt->ncol = 1;
1077 /*
1078  * How many lines of output will be needed?
1079  */
1080   fmt->nline = (result->nmatch + fmt->ncol - 1) / fmt->ncol;
1081   return;
1082 }
1083 
1084 /*.......................................................................
1085  * Render one line of a multi-column listing of completions, using a
1086  * callback function to pass the output to an arbitrary destination.
1087  *
1088  * Input:
1089  *  result      CplMatches *  The container of the sorted array of
1090  *                            completions.
1091  *  fmt      CplListFormat *  Formatting information.
1092  *  lnum               int    The index of the line to print, starting
1093  *                            from 0, and incrementing until the return
1094  *                            value indicates that there is nothing more
1095  *                            to be printed.
1096  *  write_fn     GlWriteFn *  The function to call to write the line, or
1097  *                            0 to discard the output.
1098  *  data              void *  Anonymous data to pass to write_fn().
1099  * Output:
1100  *  return             int    0 - Line printed ok.
1101  *                            1 - Nothing to print.
1102  */
cpl_format_line(CplMatches * result,CplListFormat * fmt,int lnum,GlWriteFn * write_fn,void * data)1103 static int cpl_format_line(CplMatches *result, CplListFormat *fmt, int lnum,
1104 			   GlWriteFn *write_fn, void *data)
1105 {
1106   int col;             /* The index of the list column being output */
1107 /*
1108  * If the line index is out of bounds, there is nothing to be written.
1109  */
1110   if(lnum < 0 || lnum >= fmt->nline)
1111     return 1;
1112 /*
1113  * If no output function has been provided, return as though the
1114  * line had been printed.
1115  */
1116   if(!write_fn)
1117     return 0;
1118 /*
1119  * Print the matches in 'ncol' columns, sorted in line order within each
1120  * column.
1121  */
1122   for(col=0; col < fmt->ncol; col++) {
1123     int m = col*fmt->nline + lnum;
1124 /*
1125  * Is there another match to be written? Note that in general
1126  * the last line of a listing will have fewer filled columns
1127  * than the initial lines.
1128  */
1129     if(m < result->nmatch) {
1130       CplMatch *match = result->matches + m;
1131 /*
1132  * How long are the completion and type-suffix strings?
1133  */
1134       int clen = strlen(match->completion);
1135       int tlen = strlen(match->type_suffix);
1136 /*
1137  * Write the completion string.
1138  */
1139       if(write_fn(data, match->completion, clen) != clen)
1140 	return 1;
1141 /*
1142  * Write the type suffix, if any.
1143  */
1144       if(tlen > 0 && write_fn(data, match->type_suffix, tlen) != tlen)
1145 	return 1;
1146 /*
1147  * If another column follows the current one, pad to its start with spaces.
1148  */
1149       if(col+1 < fmt->ncol) {
1150 /*
1151  * The following constant string of spaces is used to pad the output.
1152  */
1153 	static const char spaces[] = "                    ";
1154 	static const int nspace = sizeof(spaces) - 1;
1155 /*
1156  * Pad to the next column, using as few sub-strings of the spaces[]
1157  * array as possible.
1158  */
1159 	int npad = fmt->column_width + CPL_COL_SEP - clen - tlen;
1160 	while(npad>0) {
1161 	  int n = npad > nspace ? nspace : npad;
1162 	  if(write_fn(data, spaces + nspace - n, n) != n)
1163 	    return 1;
1164 	  npad -= n;
1165 	};
1166       };
1167     };
1168   };
1169 /*
1170  * Start a new line.
1171  */
1172   {
1173     char s[] = "\r\n";
1174     int n = strlen(s);
1175     if(write_fn(data, s, n) != n)
1176       return 1;
1177   };
1178   return 0;
1179 }
1180