home | help 
cpl_complete_word(3)	    Library Functions Manual	    cpl_complete_word(3)

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_comple-
     tions,  cpl_recall_matches, cpl_record_error, del_CplFileConf, del_WordCom-
     pletion, 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 com-
     pleted, 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() func-
     tion. In particular, it maintains the memory that is used to return the re-
     sults 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	applica-
     tion,  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_com-
     pletion().  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  argu-
     ment. 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 subse-
     quently 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  com-
     pletion  callback function to record each possible completion in the speci-
     fied WordCompletion object. These completions are subsequently returned  by
     cpl_complete_word(),  as described later. The cpl, line, and word_end argu-
     ments 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 in-
     cluded. 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()  re-
     turns.

     Note  that  in  the  array  of  possible  completions  which  the	cpl_com-
     plete_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-comple-
     tion  callback function adds a directory separator if the completed word is
     a directory. If the completed word were a function name,  you  could  simi-
     larly 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  allo-
     cate  a WordCompletion object. It performs word completion, as described at
     the beginning of this section. Its first argument is a resource object pre-
     viously 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_comple-
     tion().

       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 comple-
     tions, 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 val-
     ues, 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-es-
     caped  space  or the start of the input line. If you wish to specify a dif-
     ferent 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 be-
     havior.

       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 spe-
     cial 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  back-
     slashes  are  thus  ignored while looking for completions, and subsequently
     added before spaces, tabs and literal backslashes in the  list  of  comple-
     tions.  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 in-
     cluded 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 comple-
     tion in ~username/ expressions, in cpl_file_completions().

     Using the libtecla_r.a version of the library, it is safe to use the facil-
     ities 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)
home | help