cpl_complete_word man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

CPL_COMPLETE_WORD(3TECLA)			     CPL_COMPLETE_WORD(3TECLA)

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,  cpl_check_exe,  del_WordCompletion,
       new_CplFileConf,	 new_WordCompletion - look up possible completions for
       a word

SYNOPSIS
       cc [ flag... ] file... -ltecla [ library... ]
       #include <stdio.h>
       #include <libtecla.h>

       WordCompletion *new_WordCompletion(void);

       WordCompletion *del_WordCompletion(WordCompletion *cpl);

       CPL_MATCH_FN(cpl_file_completions);

       CplFileConf *new_CplFileConf(void);

       void cfc_file_start((CplFileConf *cfc, int start_index);

       void cfc_literal_escapes(CplFileConf *cfc, int literal);

       void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn,
	    void *chk_data);

       CPL_CHECK_FN(cpl_check_exe);

       CplFileConf *del_CplFileConf(CplFileConf *cfc);

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

DESCRIPTION
       The cpl_complete_word() function is part of the libtecla(3LIB) library.
       It  is usually called behind the scenes by gl_get_line(3TECLA), 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‐
       tion().

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

       The  del_WordCompletion()  function  deletes  the  resources  that were
       returned by a previous call to new_WordCompletion(). It always  returns
       NULL  (that  is, a deleted object). It takes no action if the cpl argu‐
       ment is NULL.

       The callback functions that look	 up  possible  completions  should  be
       defined	with  the  CPL_MATCH_FN()  macro,  which is defined in <libte‐
       cla.h>.	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 con‐
       taining	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 file‐
       name  completion	 function  looks  backwards  until  it	encounters  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 with separate calls to cpl_add_comple‐
       tion().	If the callback needs access to an application-specific symbol
       table, it can pass it and any other data that it needs using  the  data
       argument. This removes any need for global variables.

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

       The  last error message recorded by calling cpl_record_error() can sub‐
       sequently be queried by calling cpl_last_error().

       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(). 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 argu‐
       ment is the string that would have to be	 appended  to  the  incomplete
       word  to complete it. If this needs any quoting (for example, 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.

       In the array of possible completions that the cpl_complete_word() func‐
       tion 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 is not copied, so if the argu‐
       ment is not 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 argument is a continuation suffix to append to the com‐
       pleted  word  in the input line if this is the only completion. This is
       something that is not 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.

       The  cpl_complete_word()	 is  normally  called  behind  the  scenes  by
       gl_get_line(3TECLA), but can also be called  separately	if  you	 sepa‐
       rately  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 appli‐
       cation 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_error() function.

       The cpl_last_error() function returns a terse description of the	 error
       which occurred on the last call to cpl_com plete_word() or cpl_add_com‐
       pletion().

       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_recall_matches(). If cpl_complete_word()  returned  NULL,  so  will
       cpl_recall_matches().

       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.

   Builtin Filename completion Callback
       By     default	  the	  gl_get_line()	    function,	 passes	   the
       CPL_MATCH_FN(cps_file_completions)  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.

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

       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  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 back‐
       wards for the start of the filename being completed,  looking  for  the
       first  unescaped	 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
       reenables the default behavior.

       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 back slashes in  the
       list  of	 completions. To have unescaped back slashes treated as normal
       characters, call cfc_literal_escapes() with a  non-zero	value  in  its
       literal argument.

       By  default, cpl_file_completions() reports all files whose 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	 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.

   Thread Safety
       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.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Evolving	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ MT-Safe	      │
       └────────────────────┴─────────────────┘

SEE ALSO
       ef_expand_file(3TECLA),	    gl_get_line(3TECLA),       libtecla(3LIB),
       pca_lookup_file(3TECLA), attributes(5)

				  Jun 1, 2004	     CPL_COMPLETE_WORD(3TECLA)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net