Provided by: libtecla1-dev_1.6.1-5_i386 bug

NAME

       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

SYNOPSIS

       #include <stdio.h>
       #include <libtecla.h>

       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);

DESCRIPTION

       The  cpl_complete_word() function is part of the tecla library (see the
       libtecla(3) man page). It  is  usually  called  behind  the  scenes  by
       gl_get_line(3), but can also be called separately.

       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 cpl_add_completion().

       Descriptions of the functions of this module are as follows:

         WordCompletion *new_WordCompletion(void)

       This function creates the resources  used  by  the  cpl_complete_word()
       function. In particular, it maintains the memory that is used to return
       the results of calling cpl_complete_word().

         WordCompletion *del_WordCompletion(WordCompletion *cpl)

       This function deletes the resources that were returned  by  a  previous
       call  to  new_WordCompletion().  It  always returns NULL (ie. a deleted
       object). It does nothing if the cpl argument is NULL.

       The callback functions which  lookup  possible  completions  should  be
       defined with the following macro (which is defined in libtecla.h).

         #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
                                           void *data, \
                                           const char *line, \
                                           int word_end)

       Functions  of  this  type are called by cpl_complete_word(), and all of
       the arguments of the callback  are  those  that  were  passed  to  said
       function.  In  particular,  the  line  argument contains the input line
       containing the word to be completed, and word_end 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  word_end
       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 cpl_add_completion().
       If the callback needs access to an application-specific  symbol  table,
       it can pass it and any other data that it needs, via the data argument.
       This removes any need for globals.

       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 cpl_record_error().

         void cpl_record_error(WordCompletion *cpl,
                               const char *errmsg);

       The last error message  recorded  by  calling  cpl_record_error(),  can
       subsequently  be  queried  by  calling  cpl_last_error(),  as described
       later.

         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);

       The cpl_add_completion() function is called zero or more times  by  the
       completion  callback function to record each possible completion in the
       specified WordCompletion object.  These  completions  are  subsequently
       returned by cpl_complete_word(), as described later. The cpl, line, and
       word_end arguments should be those that were  passed  to  the  callback
       function.  The word_start argument should be the index within the input
       line string of the start of the word  that  is  being  completed.  This
       should  equal  word_end if a zero-length string is being completed. The
       suffix 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 cpl_add_completion() returns.

       Note   that   in   the   array   of   possible  completions  which  the
       cpl_complete_word()  function   returns,   the   suffix   recorded   by
       cpl_add_completion()  is  listed  along with the concatentation of this
       suffix with the word that lies between word_start and word_end  in  the
       input line.

       The type_suffix argument specifies an optional string to be appended to
       the completion if it is displayed as part of a list of  completions  by
       cpl_list_completions(). 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 type_suffix to
       "()". Note that the type_suffix 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
       cpl_complete_word() are needed.

       The  cont_suffix  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.

         CplMatches *cpl_complete_word(WordCompletion *cpl,
                                       const char *line,
                                       int word_end, void *data,
                                       CplMatchFn *match_fn);

       The  cpl_complete_word()  is  normally  called  behind  the  scenes  by
       gl_get_line(3),  but  can  also  be called separately if you separately
       allocate a WordCompletion  object.  It  performs  word  completion,  as
       described  at  the  beginning  of this section. Its first argument is a
       resource object previously returned by new_WordCompletion().  The  line
       argument is the input line string, containing the word to be completed.
       The word_end 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 gl_get_line(), this is the character over which the user
       pressed  TAB.  The  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  argument  provides a way for the
       application to pass arbitrary data to the callback function.

       If no errors occur, the cpl_complete_word() function returns a  pointer
       to  a  CplMatches  container,  as  defined  below.  This  container  is
       allocated  as  part  of   the   cpl   object   that   was   passed   to
       cpl_complete_word(),  and  will thus change on each call which uses the
       same cpl argument.

         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;

       If an error occurs during completion, cpl_complete_word() returns NULL.
       A   description   of   the   error  can  be  acquired  by  calling  the
       cpl_last_error() function.

         const char *cpl_last_error(WordCompletion *cpl);

       The cpl_last_error() function returns a terse description of the  error
       which   occurred   on   the   last   call   to  cpl_complete_word()  or
       cpl_add_completion().

         CplMatches *cpl_recall_matches(WordCompletion *cpl);

       As  a  convenience,  the   return   value   of   the   last   call   to
       cpl_complete_word()  can  be  recalled  at  a  later  time  by  calling
       cpl_recall_matches(). If cpl_complete_word()  returned  NULL,  so  will
       cpl_recall_matches().

         int cpl_list_completions(CplMatches *result, FILE *fp,
                                  int terminal_width);

       When   the   cpl_complete_word()  function  returns  multiple  possible
       completions, the cpl_list_completions() 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
       type_suffix strings that  were  recorded  with  each  completion,  thus
       indicating their types to the user.

THE BUILT-IN FILENAME-COMPLETION CALLBACK

       By default the gl_get_line(3) function, passes the following completion
       callback function to cpl_complete_word(). This  function  can  also  be
       used  separately,  either  by  sending it to cpl_complete_word(), or by
       calling it directly from your own completion callback function.

         CPL_MATCH_FN(cpl_file_completions);

       Certain aspects of the behavior of this callback can be changed via its
       data  argument. If you are happy with its default behavior you can pass
       NULL  in  this  argument.  Otherwise  it  should  be  a  pointer  to  a
       CplFileConf object, previously allocated by calling new_CplFileConf().

         CplFileConf *new_CplFileConf(void);

       CplFileConf   objects   encapsulate  the  configuration  parameters  of
       cpl_file_completions(). These parameters, which start out with  default
       values,  can  be  changed  by  calling the accessor functions described
       below.

       By  default,  the  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() with the index
       at which the filename starts in the input line. Passing  start_index=-1
       re-enables the default behavior.

         void cfc_file_start(CplFileConf *cfc, int start_index);

       By  default,  when  cpl_file_completions()  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  cfc_literal_escapes()  with  a non-zero value in its
       literal argument.

         void cfc_literal_escapes(CplFileConf *cfc, int literal);

       By default, cpl_file_completions() 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 0 if the file should be ignored,  or  1
       if  the file should be included in the list of completions. To register
       such   a   function   for   use   by    cpl_file_completions(),    call
       cfc_set_check_fn(),  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.

         #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);

       The cpl_check_exe() function is a provided callback of the above  type,
       for  use  with  cpl_file_completions().  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
       cpl_file_completions() only list completions of executable files.

       When you have finished with a CplFileConf variable, you can pass it  to
       the del_CplFileConf() destructor function to reclaim its memory.

         CplFileConf *del_CplFileConf(CplFileConf *cfc);

THREAD SAFETY

       In  multi-threaded programs, you should use the libtecla_r.a version of
       the library. This uses POSIX reentrant functions where available (hence
       the _r 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     ~username/     expressions,     in
       cpl_file_completions().

       Using the libtecla_r.a 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  WordCompletion  object.  In  other
       words, if two threads want to do word completion, they should each call
       new_WordCompletion() to allocate their own completion objects.

FILES

       libtecla.a    -    The tecla library
       libtecla.h    -    The tecla header file.

SEE ALSO

       libtecla(3), gl_get_line(3), ef_expand_file(3),
       pca_lookup_file(3)

AUTHOR

       Martin Shepherd  (mcs@astro.caltech.edu)

                                                          cpl_complete_word(3)