Imported from ../bash-2.0.tar.gz.

[platform/upstream/bash.git] / lib / readline / doc / rltech.texinfo

diff --git a/lib/readline/doc/rltech.texinfo b/lib/readline/doc/rltech.texinfo
index 636c923..6704d0e 100644 (file)
--- 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.
 
 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
 
 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
 
 @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
 @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
 
 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
 
 @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.
 * 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
 @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
 
 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
 @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
 
 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
 @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
 
 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
 @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
 
 @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
 @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
 
 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.
 @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
 
 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
 @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
 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
 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
 @end deftypevar
 
 @deftypevar {Function *} rl_ignore_some_completions_function


@@ -1174,10 +1297,11 @@ initialize_readline ()
   rl_attempted_completion_function = (CPPFunction *)fileman_completion;
 @}
 
   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;
 char **
 fileman_completion (text, start, end)
      char *text;