diff options
Diffstat (limited to 'libtecla-1.6.1/html/cpl_complete_word.html')
| -rw-r--r-- | libtecla-1.6.1/html/cpl_complete_word.html | 382 |
1 files changed, 382 insertions, 0 deletions
diff --git a/libtecla-1.6.1/html/cpl_complete_word.html b/libtecla-1.6.1/html/cpl_complete_word.html new file mode 100644 index 0000000..0c976c0 --- /dev/null +++ b/libtecla-1.6.1/html/cpl_complete_word.html @@ -0,0 +1,382 @@ +<head> +<title>Manual Page</title> +</head> +<body> +<pre> +<a href="cpl_complete_word.html"><b>cpl_complete_word</b></a> <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a> + + + +</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_recall_matches, + 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); + + 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><h2>DESCRIPTION</h2><pre> + The cpl_complete_word() function is part of the tecla library (see the + <a href="libtecla.html"><b>libtecla</b></a> man page). It is usually called behind the + scenes by <a href="gl_get_line.html"><b>gl_get_line</b></a>, but can also be called sepa- + rately. + + Given an input line containing an incomplete word to be completed, it + calls a user-provided callback function (or the provided file-comple- + tion 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 cpl_add_comple- + tion(). + + + Descriptions of the functions of this module are as follows: + + WordCompletion *new_WordCompletion(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(). + + WordCompletion *del_WordCompletion(WordCompletion *cpl) + + This function deletes the resources that were returned by a previous + call to new_WordCompletion(). 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 func- + tion. In particular, the line argument contains the input line contain- + ing the word to be completed, and word_end is the index of the charac- + ter 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 com- + pletion function looks backwards until it hits an unescaped space, or + the start of the line. Having found the start of the word, the call- + back 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 call- + ing cpl_record_error(). + + void cpl_record_error(WordCompletion *cpl, + const char *errmsg); + + The last error message recorded by calling cpl_record_error(), can sub- + sequently 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 + 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 cpl_add_completion() returns. + + Note that in the array of possible completions which the cpl_com- + plete_word() function returns, the suffix recorded by cpl_add_comple- + tion() 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 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 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_com- + plete_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 completion. This is some- + thing 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 separa- + tor 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"><b>gl_get_line</b></a>, but can also be called separately if you + separately allocate a WordCompletion object. It performs word comple- + tion, as described at the beginning of this section. Its first argument + is a resource object previously returned by new_WordCompletion(). The + line argument is the input line string, containing the word to be com- + pleted. 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 function. + + If no errors occur, the cpl_complete_word() function returns a pointer + to a CplMatches container, as defined below. This container is allo- + cated 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_com- + pletion(). + + CplMatches *cpl_recall_matches(WordCompletion *cpl); + + As a convenience, the return value of the last call to cpl_com- + plete_word() can be recalled at a later time by calling + cpl_recall_matches(). If cpl_complete_word() returned NULL, so will + cpl_recall_matches(). + + int cpl_list_completions(CplMatches *result, FILE *fp, + int terminal_width); + + When the cpl_complete_word() function returns multiple possible comple- + tions, 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"><b>gl_get_line</b></a> function, passes the follow- + ing completion callback function to cpl_complete_word(). This function + can also be used separately, either by sending it to cpl_com- + plete_word(), or by calling it directly from your own completion call- + back 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. Otherwise it should be a pointer to a CplFile- + Conf object, previously 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 back- + wards 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() 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 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. + + #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 file- + name that it is given represents a normal file that the user has exe- + cute permission to. You could use this to have cpl_file_completions() + only list completions 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 completion in ~username/ expressions, in cpl_file_comple- + tions(). + + Using the libtecla_r.a 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 WordCompletion 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"><b>libtecla</b></a>, <a href="gl_get_line.html"><b>gl_get_line</b></a>, <a href="ef_expand_file.html"><b>ef_expand_file</b></a>, + <a href="pca_lookup_file.html"><b>pca_lookup_file</b></a> + + +</pre><h2>AUTHOR</h2><pre> + Martin Shepherd (mcs@astro.caltech.edu) + + + + <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a> +</pre> +</body> |