cpl_complete_word.3

xorp源码hg

.\" Copyright (C) 2000, 2001 by Martin C. Shepherd
.\" 
.\" All rights reserved.
.\" 
.\" Permission is hereby granted, free of charge, to any person obtaining a
.\" copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, and/or sell copies of the Software, and to permit persons
.\" to whom the Software is furnished to do so, provided that the above
.\" copyright notice(s) and this permission notice appear in all copies of
.\" the Software and that both the above copyright notice(s) and this
.\" permission notice appear in supporting documentation.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\" 
.\" Except as contained in this notice, the name of a copyright holder
.\" shall not be used in advertising or otherwise to promote the sale, use
.\" or other dealings in this Software without prior written authorization
.\" of the copyright holder.
.TH cpl_complete_word 3
.SH 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_record_error, del_CplFileConf, del_WordCompletion, new_CplFileConf, new_WordCompletion \- lookup possible completions for a word
.SH SYNOPSIS
.nf
#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);

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

.fi

.SH DESCRIPTION

The \f3cpl_complete_word()\f1 function is part of the tecla library
(see the libtecla(3) man page). It is usually called behind the scenes
by \f3gl_get_line(3)\f1, 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 \f3cpl_add_completion()\f1.

.sp
Descriptions of the functions of this module are as follows:
.sp
.nf
  CompleteWord *new_CompleteWord(void)
.fi
.sp
This function creates the resources used by the \f3cpl_complete_word()\f1
function. In particular, it maintains the memory that is used to
return the results of calling \f3cpl_complete_word()\f1.
.sp
.nf
  CompleteWord *del_CompleteWord(CompleteWord *cpl)
.fi
.sp
This function deletes the resources that were returned by a previous
call to \f3new_CompleteWord()\f1. It always returns \f3NULL\f1 (ie. a
deleted object). It does nothing if the \f3cpl\f1 argument is
\f3NULL\f1.
.sp
The callback functions which lookup possible completions should be
defined with the following macro (which is defined in libtecla.h).
.sp
.nf
  #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \\
                                    void *data, \\
                                    const char *line, \\
                                    int word_end)
.fi
.sp
Functions of this type are called by \f3cpl_complete_word()\f1, and
all of the arguments of the callback are those that were passed to
said function. In particular, the \f3line\f1 argument contains the
input line containing the word to be completed, and \f3word_end\f1 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 \f3word_end\f1 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 \f3cpl_add_completion()\f1. If the
callback needs access to an application-specific symbol table, it can
pass it and any other data that it needs, via the \f3data\f1
argument. This removes any need for globals.
.sp
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 \f3cpl_record_error()\f1.
.sp
.nf
  void cpl_record_error(WordCompletion *cpl,
                        const char *errmsg);
.fi
.sp
The last error message recorded by calling \f3cpl_record_error()\f1,
can subsequently be queried by calling \f3cpl_last_error()\f1, as
described later.
.sp
.nf
  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);
.fi
.sp
The \f3cpl_add_completion()\f1 function is called zero or more times
by the completion callback function to record each possible completion
in the specified \f3WordCompletion\f1 object. These completions are
subsequently returned by \f3cpl_complete_word()\f1, as described
later. The \f3cpl\f1, \f3line\f1, and \f3word_end\f1 arguments should
be those that were passed to the callback function. The
\f3word_start\f1 argument should be the index within the input line
string of the start of the word that is being completed. This should
equal \f3word_end\f1 if a zero-length string is being completed. The
\f3suffix\f1 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 included. A copy of
the suffix string is allocated internally, so there is no need to
maintain your copy of the string after \f3cpl_add_completion()\f1
returns.
.sp
Note that in the array of possible completions which the
\f3cpl_complete_word()\f1 function returns, the suffix recorded by
\f3cpl_add_completion()\f1 is listed along with the concatentation of
this suffix with the word that lies between \f3word_start\f1 and
\f3word_end\f1 in the input line.
.sp
The \f3type_suffix\f1 argument specifies an optional string to be
appended to the completion if it is displayed as part of a list of
completions by \f3cpl_list_completions()\f1. 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 \f3type_suffix\f1 to "()". Note that the
\f3type_suffix\f1 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 \f3cpl_complete_word()\f1
are needed.
.sp
The \f3cont_suffix\f1 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.
.sp
.nf
  CplMatches *cpl_complete_word(WordCompletion *cpl,
                                const char *line,
                                int word_end, void *data,
                                CplMatchFn *match_fn);