Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


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

       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

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


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


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

       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-comple-
       tion 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_comple-

       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 ob-
       ject). It does nothing if the cpl argument is NULL.

       The callback functions which lookup possible completions	should be  de-
       fined 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	 func-
       tion. In	particular, the	line argument contains the input line contain-
       ing the word to be completed, and word_end is the index of the  charac-
       ter  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 com-
       pletion function	looks backwards	until it hits an unescaped  space,  or
       the  start  of the line.	 Having	found the start	of the word, the call-
       back 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 call-
       ing cpl_record_error().

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

       The last	error message recorded by calling cpl_record_error(), can sub-
       sequently 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 re-
       turned 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 in-
       complete	word to	complete it.  If this needs any	quoting	(eg. the addi-
       tion  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_com-
       plete_word()  function  returns,	the suffix recorded by cpl_add_comple-
       tion() 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_com-
       plete_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	 some-
       thing 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 separa-
       tor 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 al-
       locate a	WordCompletion object. It performs  word  completion,  as  de-
       scribed	at  the	beginning of this section. Its first argument is a re-
       source 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 call-
       back function which will	lookup possible	completions of	the  word,  as
       described  above, and the data argument provides	a way for the applica-
       tion 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 allo-
       cated 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_er-
       ror() 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_com-

	 CplMatches *cpl_recall_matches(WordCompletion *cpl);

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

	 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.

       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.


       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 CplFile-
       Conf 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  be-

       By default, the cpl_file_completions() callback function	searches back-
       wards 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  in-
       put line, each lone backslash in	the input line is interpreted as being
       a special character which removes any special significance of the char-
       acter  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	subse-
       quently added before spaces, tabs and literal backslashes in  the  list
       of completions. To have unescaped backslashes treated as	normal charac-
       ters, call cfc_literal_escapes()	with a non-zero	value in  its  literal

	 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

	 #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	 file-
       name  that  it is given represents a normal file	that the user has exe-
       cute 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);

       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_comple-

       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.

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

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

       Martin Shepherd	(



Want to link to this manual page? Use this URL:

home | help