Import readline 8.0

[deliverable/binutils-gdb.git] / readline / doc / rltech.texi

diff --git a/readline/doc/rltech.texi b/readline/doc/rltech.texi
index b8ce90f95d5b64bbe10d0272ad4e680ab4016521..28a02d99607344761b34c53f2ebc8b1100a3fe9a 100644 (file)
--- a/readline/doc/rltech.texi
+++ b/readline/doc/rltech.texi
@@ -90,6 +90,12 @@ If @code{readline} encounters an @code{EOF} while reading the line, and the
 line is empty at that point, then @code{(char *)NULL} is returned.
 Otherwise, the line is ended just as if a newline had been typed.
 
+Readline performs some expansion on the @var{prompt} before it is
+displayed on the screen.  See the description of @code{rl_expand_prompt}
+(@pxref{Redisplay}) for additional details, especially if @var{prompt}
+will contain characters that do not consume physical screen space when
+displayed.
+
 If you want the user to be able to get at the line later, (with
 @key{C-p} for example), you must call @code{add_history()} to save the
 line away in a @dfn{history} list of such lines.
@@ -688,6 +694,11 @@ Free all storage associated with @var{keymap}.  This calls
 @code{rl_discard_keymap} to free subordindate keymaps and macros.
 @end deftypefun
 
+@deftypefun int rl_empty_keymap (Keymap keymap)
+Return non-zero if there are no keys bound to functions in @var{keymap};
+zero if there are any keys bound.
+@end deftypefun
+
 Readline has several internal keymaps.  These functions allow you to
 change which keymap is active.
 
@@ -709,6 +720,24 @@ Return the name matching @var{keymap}.  @var{name} is one which would
 be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
 @end deftypefun
 
+@deftypefun int rl_set_keymap_name (const char *name, Keymap keymap)
+Set the name of @var{keymap}.  This name will then be "registered" and
+available for use in a @code{set keymap} inputrc directive
+@pxref{Readline Init File}).
+The @var{name} may not be one of Readline's builtin keymap names;
+you may not add a different name for one of Readline's builtin keymaps.
+You may replace the name associated with a given keymap by calling this
+function more than once with the same @var{keymap} argument.
+You may associate a registered @var{name} with a new keymap by calling this
+function more than once  with the same @var{name} argument.
+There is no way to remove a named keymap once the name has been
+registered.
+Readline will make a copy of @var{name}.
+The return value is greater than zero unless @var{name} is one of
+Readline's builtin keymap names or @var{keymap} is one of Readline's
+builtin keymaps.
+@end deftypefun
+
 @node Binding Keys
 @subsection Binding Keys
 
@@ -835,6 +864,16 @@ Return the function invoked by @var{keyseq} in keymap @var{map}.
 If @var{map} is @code{NULL}, the current keymap is used.  If @var{type} is
 not @code{NULL}, the type of the object is returned in the @code{int} variable
 it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).
+It takes a "translated" key sequence and should not be used if the key sequence
+can include NUL.
+@end deftypefun
+
+@deftypefun {rl_command_func_t *} rl_function_of_keyseq_len (const char *keyseq, size_t len, Keymap map, int *type)
+Return the function invoked by @var{keyseq} of length @var{len}
+in keymap @var{map}. Equivalent to @code{rl_function_of_keyseq} with the
+addition of the @var{len} parameter.
+It takes a "translated" key sequence and should be used if the key sequence
+can include NUL.
 @end deftypefun
 
 @deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function)
@@ -1679,6 +1718,19 @@ handlers, depending on the values of @code{rl_catch_signals} and
 @code{rl_catch_sigwinch}.
 @end deftypefun
 
+If an application wants to force Readline to handle any signals that
+have arrived while it has been executing, @code{rl_check_signals()}
+will call Readline's internal signal handler if there are any pending
+signals.  This is primarily intended for those applications that use
+a custom @code{rl_getc_function} (@pxref{Readline Variables}) and wish
+to handle signals received while waiting for input.
+
+@deftypefun void rl_check_signals (void)
+If there are any pending signals, call Readline's internal signal handling
+functions to process them. @code{rl_pending_signal()} can be used independently
+to determine whether or not there are any pending signals.
+@end deftypefun
+
 If an application does not wish Readline to catch @code{SIGWINCH}, it may
 call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force
 Readline to update its idea of the terminal size when a @code{SIGWINCH}
@@ -2094,6 +2146,8 @@ character (@samp{\0}) prevents anything being appended automatically.
 This can be changed in application-specific completion functions to
 provide the ``most sensible word separator character'' according to
 an application-specific command line syntax specification.
+It is set to the default before any application-specific completion function
+is called, and may only be changed within such a function.
 @end deftypevar
 
 @deftypevar int rl_completion_suppress_append