X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;ds=sidebyside;f=lib%2Freadline%2Fdoc%2Frltech.texinfo;h=6704d0e27a785e5c6bd88da33f10526f293d1f6c;hb=ccc6cda312fea9f0468ee65b8f368e9653e1380b;hp=636c92396a9813e128e5f438535470ed1ebb084d;hpb=726f63884db0132f01745f1fb4465e6621088ccf;p=platform%2Fupstream%2Fbash.git diff --git a/lib/readline/doc/rltech.texinfo b/lib/readline/doc/rltech.texinfo index 636c923..6704d0e 100644 --- a/lib/readline/doc/rltech.texinfo +++ b/lib/readline/doc/rltech.texinfo @@ -8,7 +8,7 @@ This document describes the GNU Readline Library, a utility for aiding in the consitency of user interface across discrete programs that need to provide a command line interface. -Copyright (C) 1988, 1994 Free Software Foundation, Inc. +Copyright (C) 1988, 1994, 1996 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -273,6 +273,10 @@ The prompt Readline uses. This is set from the argument to @code{readline ()}, and should not be assigned to directly. @end deftypevar +@deftypevar {char *} rl_library_version +The version number of this revision of the library. +@end deftypevar + @deftypevar {char *} rl_terminal_name The terminal type, used for initialization. @end deftypevar @@ -301,6 +305,30 @@ If non-zero, this is the address of a function to call periodically when readline is waiting for terminal input. @end deftypevar +@deftypevar {Function *} rl_getc_function +If non-zero, @code{readline} will call indirectly through this pointer +to get a character from the input stream. By default, it is set to +@code{rl_getc}, the default @code{readline} character input function +(@pxref{Utility Functions}). +@end deftypevar + +@deftypevar {Function *} rl_redisplay_function +If non-zero, @code{readline} will call indirectly through this pointer +to update the display with the current contents of the editing buffer. +By default, it is set to @code{rl_redisplay}, the default @code{readline} +redisplay function (@pxref{Redisplay}). +@end deftypevar + +@deftypevar {Keymap} rl_executing_keymap +This variable is set to the keymap (@pxref{Keymaps}) in which the +currently executing readline function was found. +@end deftypevar + +@deftypevar {Keymap} rl_binding_keymap +This variable is set to the keymap (@pxref{Keymaps}) in which the +last key binding occurred. +@end deftypevar + @node Readline Convenience Functions @section Readline Convenience Functions @@ -314,6 +342,7 @@ when readline is waiting for terminal input. * Redisplay:: Functions to control line display. * Modifying Text:: Functions to modify @code{rl_line_buffer}. * Utility Functions:: Generally useful functions and hooks. +* Alternate Interface:: Using Readline in a `callback' fashion. @end menu @node Function Naming @@ -611,6 +640,10 @@ the input stream via @var{pending input} (@pxref{Readline Variables}) and @code{rl_stuff_char ()}, macros, and characters read from the keyboard. @end deftypefun +@deftypefun int rl_getc (FILE *) +Return the next character available from the keyboard. +@end deftypefun + @deftypefun int rl_stuff_char (int c) Insert @var{c} into the Readline input stream. It will be "read" before Readline attempts to read characters from the terminal with @@ -666,6 +699,37 @@ lowercase character. If @var{c} is a number, return the value it represents. @end deftypefun +@node Alternate Interface +@subsection Alternate Interface + +An alternate interface is available to plain @code{readline()}. Some +applications need to interleave keyboard I/O with file, device, or +window system I/O, typically by using a main loop to @code{select()} +on various file descriptors. To accomodate this need, readline can +also be invoked as a `callback' function from an event loop. There +are functions available to make this easy. + +@deftypefun void rl_callback_handler_install (char *prompt, Vfunction *lhandler) +Set up the terminal for readline I/O and display the initial +expanded value of @var{prompt}. Save the value of @var{lhandler} to +use as a callback when a complete line of input has been entered. +@end deftypefun + +@deftypefun void rl_callback_read_char () +Whenever an application determines that keyboard input is available, it +should call @code{rl_callback_read_char()}, which will read the next +character from the current input source. If that character completes the +line, @code{rl_callback_read_char} will invoke the @var{lhandler} +function saved by @code{rl_callback_handler_install} to process the +line. @code{EOF} is indicated by calling @var{lhandler} with a +@code{NULL} line. +@end deftypefun + +@deftypefun void rl_callback_handler_remove () +Restore the terminal to its initial state and remove the line handler. +This may be called from within a callback as well as independently. +@end deftypefun + @subsection An Example Here is a function which changes lowercase characters to their uppercase @@ -894,6 +958,40 @@ returns @code{NULL}, or if this variable is set to @code{NULL}, then array of strings returned will be used. @end deftypevar +@deftypevar {CPFunction *} rl_filename_quoting_function +A pointer to a function that will quote a filename in an application- +specific fashion. This is called if filename completion is being +attempted and one of the characters in @code{rl_filename_quote_characters} +appears in a completed filename. The function is called with +@var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text} +is the filename to be quoted. The @var{match_type} is either +@code{SINGLE_MATCH}, if there is only one completion match, or +@code{MULT_MATCH}. Some functions use this to decide whether or not to +insert a closing quote character. The @var{quote_pointer} is a pointer +to any opening quote character the user typed. Some functions choose +to reset this character. +@end deftypevar + +@deftypevar {CPFunction *} rl_filename_dequoting_function +A pointer to a function that will remove application-specific quoting +characters from a filename before completion is attempted, so those +characters do not interfere with matching the text against names in +the filesystem. It is called with @var{text}, the text of the word +to be dequoted, and @var{quote_char}, which is the quoting character +that delimits the filename (usually @samp{'} or @samp{"}). If +@var{quote_char} is zero, the filename was not in an embedded string. +@end deftypevar + +@deftypevar {Function *} rl_char_is_quoted_p +A pointer to a function to call that determines whether or not a specific +character in the line buffer is quoted, according to whatever quoting +mechanism the program calling readline uses. The function is called with +two arguments: @var{text}, the text of the line, and @var{index}, the +index of the character in the line. It is used to decide whether a +character found in @code{rl_completer_word_break_characters} should be +used to break words for the completer. +@end deftypevar + @deftypevar int rl_completion_query_items Up to this many items will be displayed in response to a possible-completions call. After that, we ask the user if she is sure @@ -907,6 +1005,10 @@ which break words for completion in Bash, i.e., @code{" \t\n\"\\'`@@$><=;|&@{("}. @end deftypevar +@deftypevar {char *} rl_basic_quote_characters +List of quote characters which can cause a word break. +@end deftypevar + @deftypevar {char *} rl_completer_word_break_characters The list of characters that signal a break between words for @code{rl_complete_internal ()}. The default list is the value of @@ -920,6 +1022,11 @@ Completion occurs on the entire substring, and within the substring unless they also appear within this list. @end deftypevar +@deftypevar {char *} rl_filename_quote_characters +A list of characters that cause a filename to be quoted by the completer +when they appear in a completed filename. The default is empty. +@end deftypevar + @deftypevar {char *} rl_special_prefixes The list of characters that are word break characters, but should be left in @var{text} when it is passed to the completion function. @@ -928,6 +1035,16 @@ For instance, Bash sets this variable to "$@@" so that it can complete shell variables and hostnames. @end deftypevar +@deftypevar {int} rl_completion_append_character +When a single completion alternative matches at the end of the command +line, this character is appended to the inserted completion text. The +default is a space character (@samp{ }). Setting this to the null +character (@samp{\0}) prevents anything being appended automatically. +This can be changed in custom completion functions to +provide the ``most sensible word separator character'' according to +an application-specific command line syntax specification. +@end deftypevar + @deftypevar int rl_ignore_completion_duplicates If non-zero, then disallow duplicates in the matches. Default is 1. @end deftypevar @@ -945,9 +1062,15 @@ characters. Non-zero means that the results of the matches are to be quoted using double quotes (or an application-specific quoting mechanism) if the completed filename contains any characters in -@code{rl_completer_word_break_chars}. This is @emph{always} non-zero +@code{rl_filename_quote_chars}. This is @emph{always} non-zero on entry, and can only be changed within a completion entry generator -function. +function. The quoting is effected via a call to the function pointed to +by @code{rl_filename_quoting_function}. +@end deftypevar + +@deftypevar int rl_inhibit_completion +If this variable is non-zero, completion is inhibited. The completion +character will be inserted as any other bound to @code{self-insert}. @end deftypevar @deftypevar {Function *} rl_ignore_some_completions_function @@ -1174,10 +1297,11 @@ initialize_readline () rl_attempted_completion_function = (CPPFunction *)fileman_completion; @} -/* Attempt to complete on the contents of TEXT. START and END show the - region of TEXT that contains the word to complete. We can use the - entire line in case we want to do some simple parsing. Return the - array of matches, or NULL if there aren't any. */ +/* Attempt to complete on the contents of TEXT. START and END bound the + region of rl_line_buffer that contains the word to complete. TEXT is + the word to complete. We can use the entire contents of rl_line_buffer + in case we want to do some simple parsing. Return the array of matches, + or NULL if there aren't any. */ char ** fileman_completion (text, start, end) char *text;