diff options
Diffstat (limited to 'libtecla-1.4.1/html/cpl_complete_word.html')
| -rw-r--r-- | libtecla-1.4.1/html/cpl_complete_word.html | 423 |
1 files changed, 423 insertions, 0 deletions
diff --git a/libtecla-1.4.1/html/cpl_complete_word.html b/libtecla-1.4.1/html/cpl_complete_word.html new file mode 100644 index 0000000..063359d --- /dev/null +++ b/libtecla-1.4.1/html/cpl_complete_word.html @@ -0,0 +1,423 @@ +<head> +<title>Manual Page</title> +</head> +<body> +<pre> +</pre><h2>NAME</h2><pre> + 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 + +</pre><h2>SYNOPSIS</h2><pre> + #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); + + + +</pre><h2>DESCRIPTION</h2><pre> + The cpl_complete_word() function is part of the tecla + library (see the <a href="libtecla.html">libtecla(3)</a> man page). It is usually called + behind the scenes by <a href="gl_get_line.html">gl_get_line(3)</a>, but can also be called + separately. + + Given an input line containing an incomplete word to be com- + pleted, 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 comple- + tions of that word and record them, one at a time by calling + cpl_add_completion(). + + + Descriptions of the functions of this module are as follows: + + CompleteWord *new_CompleteWord(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(). + + CompleteWord *del_CompleteWord(CompleteWord *cpl) + + This function deletes the resources that were returned by a + previous call to new_CompleteWord(). It always returns NULL + (ie. a deleted object). It does nothing if the cpl argument + is NULL. + + The callback functions which lookup possible completions + should be defined 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 function. In particular, the line argument + contains the input line containing 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 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 + 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 calling cpl_record_error(). + + void cpl_record_error(WordCompletion *cpl, + const char *errmsg); + + The last error message recorded by calling + cpl_record_error(), can subsequently 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 returned 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 incom- + plete 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 inter- + nally, 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_complete_word() function 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 comple- + tion. 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 com- + pletion 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_complete_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 comple- + tion. 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. + + 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 <a href="gl_get_line.html">gl_get_line(3)</a>, but can also be called separately if you + separately allocate a WordCompletion object. It performs + word completion, as described at the beginning of this sec- + tion. Its first argument is a resource object previously + returned by new_CompleteWord(). 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 application to pass arbitrary data to the callback func- + tion. + + If no errors occur, the cpl_complete_word() function returns + a pointer to a CplMatches container, as defined below. This + container is allocated 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. + + 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_completion(). + + int cpl_list_completions(CplMatches *result, FILE *fp, + int terminal_width); + + When the cpl_complete_word() function returns multiple pos- + sible completions, 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. + + +</pre><h2>THE BUILT-IN FILENAME-COMPLETION CALLBACK</h2><pre> + By default the <a href="gl_get_line.html">gl_get_line(3)</a> 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. + + 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. Other- + wise it should be a pointer to a CplFileConf object, previ- + ously 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 below. + + By default, the cpl_file_completions() callback function + searches backwards for the start of the filename being com- + pleted, looking for the first un-escaped space or the start + of the input line. If you wish to specify a different loca- + tion, 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 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 + cfc_literal_escapes() with a non-zero value in its literal + argument. + + 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 func- + tion, 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 read- + able, 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 filename that it is given represents a nor- + mal file that the user has execute permission to. You could + use this to have cpl_file_completions() only list comple- + tions 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); + + + +</pre><h2>THREAD SAFETY</h2><pre> + 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 comple- + tion in ~username/ expressions, in cpl_file_completions(). + + Using the libtecla_r.a version of the library, it is safe to + use the facilities of this module in multiple threads, pro- + vided that each thread uses a separately allocated WordCom- + pletion object. In other words, if two threads want to do + word completion, they should each call new_WordCompletion() + to allocate their own completion objects. + + +</pre><h2>FILES</h2><pre> + libtecla.a - The tecla library + libtecla.h - The tecla header file. + + +</pre><h2>SEE ALSO</h2><pre> + <a href="libtecla.html">libtecla(3)</a>, <a href="gl_get_line.html">gl_get_line(3)</a>, <a href="ef_expand_file.html">ef_expand_file(3)</a>, + <a href="pca_lookup_file.html">pca_lookup_file(3)</a> + + +</pre><h2>AUTHOR</h2><pre> + Martin Shepherd (mcs@astro.caltech.edu) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</pre> +</body> |