diff options
Diffstat (limited to 'libtecla-1.6.3/html/cpl_complete_word.html')
| -rw-r--r-- | libtecla-1.6.3/html/cpl_complete_word.html | 477 |
1 files changed, 477 insertions, 0 deletions
diff --git a/libtecla-1.6.3/html/cpl_complete_word.html b/libtecla-1.6.3/html/cpl_complete_word.html new file mode 100644 index 0000000..e69c8c0 --- /dev/null +++ b/libtecla-1.6.3/html/cpl_complete_word.html @@ -0,0 +1,477 @@ +Content-type: text/html + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML><HEAD><TITLE>Man page of cpl_complete_word</TITLE> +</HEAD><BODY> +<H1>cpl_complete_word</H1> +Section: C Library Functions (3)<BR><A HREF="#index">Index</A> +<A HREF="index.html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +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 +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<PRE> +#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>> +#include <<A HREF="file:///usr/include/libtecla.h">libtecla.h</A>> + +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); + +</PRE> + +<P> +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + +<P> +The <B>cpl_complete_word()</B> function is part of the tecla library +(see the <A HREF="libtecla.html">libtecla</A>(3) man page). It is usually called behind the scenes +by <B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B>, but can also be called separately. +<P> +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 <B>cpl_add_completion()</B>. +<P> +<P> +Descriptions of the functions of this module are as follows: +<P> +<PRE> + WordCompletion *new_WordCompletion(void) +</PRE> + +<P> +This function creates the resources used by the <B>cpl_complete_word()</B> +function. In particular, it maintains the memory that is used to +return the results of calling <B>cpl_complete_word()</B>. +<P> +<PRE> + WordCompletion *del_WordCompletion(WordCompletion *cpl) +</PRE> + +<P> +This function deletes the resources that were returned by a previous +call to <B>new_WordCompletion()</B>. It always returns <B>NULL</B> (ie. a +deleted object). It does nothing if the <B>cpl</B> argument is +<B>NULL</B>. +<P> +The callback functions which lookup possible completions should be +defined with the following macro (which is defined in libtecla.h). +<P> +<PRE> + #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \ + void *data, \ + const char *line, \ + int word_end) +</PRE> + +<P> +Functions of this type are called by <B>cpl_complete_word()</B>, and +all of the arguments of the callback are those that were passed to +said function. In particular, the <B>line</B> argument contains the +input line containing the word to be completed, and <B>word_end</B> 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 <B>word_end</B> 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 <B>cpl_add_completion()</B>. If the +callback needs access to an application-specific symbol table, it can +pass it and any other data that it needs, via the <B>data</B> +argument. This removes any need for globals. +<P> +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 <B>cpl_record_error()</B>. +<P> +<PRE> + void cpl_record_error(WordCompletion *cpl, + const char *errmsg); +</PRE> + +<P> +The last error message recorded by calling <B>cpl_record_error()</B>, +can subsequently be queried by calling <B>cpl_last_error()</B>, as +described later. +<P> +<PRE> + 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); +</PRE> + +<P> +The <B>cpl_add_completion()</B> function is called zero or more times +by the completion callback function to record each possible completion +in the specified <B>WordCompletion</B> object. These completions are +subsequently returned by <B>cpl_complete_word()</B>, as described +later. The <B>cpl</B>, <B>line</B>, and <B>word_end</B> arguments should +be those that were passed to the callback function. The +<B>word_start</B> argument should be the index within the input line +string of the start of the word that is being completed. This should +equal <B>word_end</B> if a zero-length string is being completed. The +<B>suffix</B> 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 <B>cpl_add_completion()</B> +returns. +<P> +Note that in the array of possible completions which the +<B>cpl_complete_word()</B> function returns, the suffix recorded by +<B>cpl_add_completion()</B> is listed along with the concatentation of +this suffix with the word that lies between <B>word_start</B> and +<B>word_end</B> in the input line. +<P> +The <B>type_suffix</B> argument specifies an optional string to be +appended to the completion if it is displayed as part of a list of +completions by <B>cpl_list_completions()</B>. 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 <B>type_suffix</B> to "()". Note that the +<B>type_suffix</B> 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 <B>cpl_complete_word()</B> +are needed. +<P> +The <B>cont_suffix</B> 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. +<P> +<PRE> + CplMatches *cpl_complete_word(WordCompletion *cpl, + const char *line, + int word_end, void *data, + CplMatchFn *match_fn); +</PRE> + +<P> +The <B>cpl_complete_word()</B> is normally called behind the scenes by +<B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B>, but can also be called separately if you +separately allocate a <B>WordCompletion</B> object. It performs word +completion, as described at the beginning of this section. Its first +argument is a resource object previously returned by +<B>new_WordCompletion()</B>. The <B>line</B> argument is the input line +string, containing the word to be completed. The <B>word_end</B> +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 <B>gl_get_line()</B>, this is the character over which the +user pressed <B>TAB</B>. The <B>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</B> +argument provides a way for the application to pass arbitrary data to +the callback function. +<P> +If no errors occur, the <B>cpl_complete_word()</B> function returns a +pointer to a <B>CplMatches</B> container, as defined below. This +container is allocated as part of the <B>cpl</B> object that was passed +to <B>cpl_complete_word()</B>, and will thus change on each call which +uses the same <B>cpl</B> argument. +<P> +<PRE> + 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; +</PRE> + +<P> +If an error occurs during completion, <B>cpl_complete_word()</B> +returns NULL. A description of the error can be acquired by calling +the <B>cpl_last_error() function. +<P> +</B><PRE> + const char *cpl_last_error(WordCompletion *cpl); +</PRE> + +<P> +The <B>cpl_last_error() function returns a terse description of the +error which occurred on the last call to cpl_complete_word()</B> or +<B>cpl_add_completion()</B>. +<P> +<PRE> + CplMatches *cpl_recall_matches(WordCompletion *cpl); +</PRE> + +<P> +As a convenience, the return value of the last call to +<B>cpl_complete_word()</B> can be recalled at a later time by calling +<B>cpl_recall_matches()</B>. If <B>cpl_complete_word()</B> returned +<B>NULL</B>, so will <B>cpl_recall_matches()</B>. +<P> +<PRE> + int cpl_list_completions(CplMatches *result, FILE *fp, + int terminal_width); +</PRE> + +<P> +When the <B>cpl_complete_word()</B> function returns multiple possible +completions, the <B>cpl_list_completions()</B> 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 <B>type_suffix</B> strings that were recorded with each completion, +thus indicating their types to the user. +<P> +<A NAME="lbAE"> </A> +<H2>THE BUILT-IN FILENAME-COMPLETION CALLBACK</H2> + +<P> +By default the <B><A HREF="gl_get_line.html">gl_get_line</A>(3)</B> function, passes the following +completion callback function to <B>cpl_complete_word()</B>. This +function can also be used separately, either by sending it to +<B>cpl_complete_word()</B>, or by calling it directly from your +own completion callback function. +<P> +<PRE> + CPL_MATCH_FN(cpl_file_completions); +</PRE> + +<P> +Certain aspects of the behavior of this callback can be changed via +its <B>data</B> argument. If you are happy with its default behavior +you can pass <B>NULL</B> in this argument. Otherwise it should be a +pointer to a <B>CplFileConf</B> object, previously allocated by calling +<B>new_CplFileConf()</B>. +<P> +<PRE> + CplFileConf *new_CplFileConf(void); +</PRE> + +<P> +<B>CplFileConf</B> objects encapsulate the configuration parameters of +<B>cpl_file_completions()</B>. These parameters, which start out with +default values, can be changed by calling the accessor functions +described below. +<P> +By default, the <B>cpl_file_completions() 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 +cfc_file_start()</B> with the index at which the filename starts in +the input line. Passing start_index=-1 re-enables the default +behavior. +<P> +<PRE> + void cfc_file_start(CplFileConf *cfc, int start_index); +</PRE> + +<P> +By default, when <B>cpl_file_completions()</B> 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 <B>cfc_literal_escapes()</B> with a +non-zero value in its <B>literal</B> argument. +<P> +<PRE> + void cfc_literal_escapes(CplFileConf *cfc, int literal); +</PRE> + +<P> +By default, <B>cpl_file_completions()</B> 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 <B>0</B> if the +file should be ignored, or <B>1</B> if the file should be included in +the list of completions. To register such a function for use by +<B>cpl_file_completions()</B>, call <B>cfc_set_check_fn()</B>, 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. +<P> +<PRE> + #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); +</PRE> + +<P> +The <B>cpl_check_exe()</B> function is a provided callback of the above +type, for use with <B>cpl_file_completions()</B>. 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 +<B>cpl_file_completions()</B> only list completions of executable +files. +<P> +When you have finished with a <B>CplFileConf</B> variable, you can pass +it to the <B>del_CplFileConf()</B> destructor function to reclaim its +memory. +<P> +<PRE> + CplFileConf *del_CplFileConf(CplFileConf *cfc); +</PRE> + +<P> +<P> +<A NAME="lbAF"> </A> +<H2>THREAD SAFETY</H2> + +<P> +In multi-threaded programs, you should use the <B>libtecla_r.a</B> +version of the library. This uses POSIX reentrant functions where +available (hence the <B>_r</B> 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 <B>~username/</B> +expressions, in <B>cpl_file_completions()</B>. +<P> +Using the <B>libtecla_r.a</B> 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 <B>WordCompletion</B> object. In +other words, if two threads want to do word completion, they should +each call <B>new_WordCompletion()</B> to allocate their own completion +objects. +<P> +<A NAME="lbAG"> </A> +<H2>FILES</H2> + +<PRE> +libtecla.a - The tecla library +libtecla.h - The tecla header file. +</PRE> + +<P> +<A NAME="lbAH"> </A> +<H2>SEE ALSO</H2> + +<P> +<PRE> +<A HREF="libtecla.html">libtecla</A>(3), <A HREF="gl_get_line.html">gl_get_line</A>(3), <A HREF="ef_expand_file.html">ef_expand_file</A>(3), +<A HREF="pca_lookup_file.html">pca_lookup_file</A>(3) +</PRE> + +<P> +<A NAME="lbAI"> </A> +<H2>AUTHOR</H2> + +Martin Shepherd (<A HREF="mailto:mcs@astro.caltech.edu">mcs@astro.caltech.edu</A>) +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DT><A HREF="#lbAE">THE BUILT-IN FILENAME-COMPLETION CALLBACK</A><DD> +<DT><A HREF="#lbAF">THREAD SAFETY</A><DD> +<DT><A HREF="#lbAG">FILES</A><DD> +<DT><A HREF="#lbAH">SEE ALSO</A><DD> +<DT><A HREF="#lbAI">AUTHOR</A><DD> +</DL> +<HR> +This document was created by +<A HREF="/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 22:21:57 GMT, November 09, 2014 +</BODY> +</HTML> |