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

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

## 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 com-
         pleted,  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  comple-
         tions 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:

           CompleteWord *new_CompleteWord(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().

           CompleteWord *del_CompleteWord(CompleteWord *cpl)

         This function deletes the resources that were returned by  a
         previous  call to new_CompleteWord(). 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  incom-
         plete  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  inter-
         nally,  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 comple-
         tion. 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  com-
         pletion 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 comple-
         tion. 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 sec-
         tion. Its first argument is  a  resource  object  previously
         returned  by  new_CompleteWord().   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 func-
         tion.

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

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

         When the cpl_complete_word() function returns multiple  pos-
         sible  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.  Other-
         wise  it should be a pointer to a CplFileConf object, previ-
         ously 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 com-
         pleted, looking for the first un-escaped space or the  start
         of  the input line. If you wish to specify a different loca-
         tion, 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  func-
         tion,  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 read-
         able, 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  nor-
         mal  file that the user has execute permission to. You could
         use this to have cpl_file_completions()  only  list  comple-
         tions 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  comple-
         tion 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, pro-
         vided that each thread uses a separately allocated  WordCom-
         pletion  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)