cpl_complete_word.3

xorp源码hg

.fi
.sp
The \f3cpl_complete_word()\f1 is normally called behind the scenes by
\f3gl_get_line(3)\f1, but can also be called separately if you
separately allocate a \f3WordCompletion\f1 object. It performs word
completion, as described at the beginning of this section. Its first
argument is a resource object previously returned by
\f3new_CompleteWord()\f1.  The \f3line\f1 argument is the input line
string, containing the word to be completed. The \f3word_end\f1
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 \f3gl_get_line()\f1, this is the character over which the
user pressed \f3TAB\f1. The \f3match_fn\f3 argument is the function
pointer of the callback function which will lookup possible
completions of the word, as described above, and the \f3data\f1
argument provides a way for the application to pass arbitrary data to
the callback function.
.sp
If no errors occur, the \f3cpl_complete_word()\f1 function returns a
pointer to a \f3CplMatches\f1 container, as defined below. This
container is allocated as part of the \f3cpl\f1 object that was passed
to \f3cpl_complete_word()\f1, and will thus change on each call which
uses the same \f3cpl\f1 argument.
.sp
.nf
  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;
.fi
.sp
If an error occurs during completion, \f3cpl_complete_word()\f1
returns NULL. A description of the error can be acquired by calling
the \f3cpl_last_error()\f3 function.
.sp
.nf
  const char *cpl_last_error(WordCompletion *cpl);
.fi
.sp
The \f3cpl_last_error()\f3 function returns a terse description of the
error which occurred on the last call to \f3cpl_complete_word()\f1 or
\f3cpl_add_completion()\f1.
.sp
.nf
  int cpl_list_completions(CplMatches *result, FILE *fp,
                           int terminal_width);
.fi
.sp
When the \f3cpl_complete_word()\f1 function returns multiple possible
completions, the \f3cpl_list_completions()\f1 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 \f3type_suffix\f1 strings that were recorded with each completion,
thus indicating their types to the user.

.SH THE BUILT-IN FILENAME-COMPLETION CALLBACK

By default the \f3gl_get_line(3)\f1 function, passes the following
completion callback function to \f3cpl_complete_word()\f1. This
function can also be used separately, either by sending it to
\f3cpl_complete_word()\f1, or by calling it directly from your
own completion callback function.
.sp
.nf
  CPL_MATCH_FN(cpl_file_completions);
.fi
.sp
Certain aspects of the behavior of this callback can be changed via
its \f3data\f1 argument. If you are happy with its default behavior
you can pass \f3NULL\f1 in this argument. Otherwise it should be a
pointer to a \f3CplFileConf\f1 object, previously allocated by calling
\f3new_CplFileConf()\f1.
.sp
.nf
  CplFileConf *new_CplFileConf(void);
.fi
.sp
\f3CplFileConf\f1 objects encapsulate the configuration parameters of
\f3cpl_file_completions()\f1. These parameters, which start out with
default values, can be changed by calling the accessor functions
described below.
.sp
By default, the \f3cpl_file_completions()\f3 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
\f3cfc_file_start()\f1 with the index at which the filename starts in
the input line. Passing start_index=-1 re-enables the default
behavior.
.sp
.nf
  void cfc_file_start(CplFileConf *cfc, int start_index);
.fi
.sp
By default, when \f3cpl_file_completions()\f1 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 \f3cfc_literal_escapes()\f1 with a
non-zero value in its \f3literal\f1 argument.
.sp
.nf
  void cfc_literal_escapes(CplFileConf *cfc, int literal);
.fi
.sp
By default, \f3cpl_file_completions()\f1 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 \f30\f1 if the
file should be ignored, or \f31\f1 if the file should be included in
the list of completions. To register such a function for use by
\f3cpl_file_completions()\f1, call \f3cfc_set_check_fn()\f1, 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.
.sp
.nf
  #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);
.fi
.sp
The \f3cpl_check_exe()\f1 function is a provided callback of the above
type, for use with \f3cpl_file_completions()\f1. 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
\f3cpl_file_completions()\f1 only list completions of executable
files.
.sp
When you have finished with a \f3CplFileConf\f1 variable, you can pass
it to the \f3del_CplFileConf()\f1 destructor function to reclaim its
memory.
.sp
.nf
  CplFileConf *del_CplFileConf(CplFileConf *cfc);
.fi
.sp

.SH THREAD SAFETY

In multi-threaded programs, you should use the \f3libtecla_r.a\f1
version of the library. This uses POSIX reentrant functions where
available (hence the \f3_r\f1 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 \f3~username/\f1
expressions, in \f3cpl_file_completions()\f1.

Using the \f3libtecla_r.a\f1 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 \f3WordCompletion\f1 object. In
other words, if two threads want to do word completion, they should
each call \f3new_WordCompletion()\f1 to allocate their own completion
objects.

.SH FILES
.nf
libtecla.a    -    The tecla library
libtecla.h    -    The tecla header file.
.fi

.SH SEE ALSO
libtecla(3), gl_get_line(3), ef_expand_file(3), pca_lookup_file(3)
  
.SH AUTHOR
Martin Shepherd  ([e-mail])