Provided by: libtecla-dev_1.6.3-3.1build1_amd64 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 characters) 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)