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, 0 insertions, 423 deletions
diff --git a/libtecla-1.4.1/html/cpl_complete_word.html b/libtecla-1.4.1/html/cpl_complete_word.html deleted file mode 100644 index 063359d..0000000 --- a/libtecla-1.4.1/html/cpl_complete_word.html +++ /dev/null @@ -1,423 +0,0 @@ -<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> |