summaryrefslogtreecommitdiffstats
path: root/contrib/libreadline/doc
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/libreadline/doc')
-rw-r--r--contrib/libreadline/doc/Makefile.in90
-rw-r--r--contrib/libreadline/doc/hist.texinfo4
-rw-r--r--contrib/libreadline/doc/history.311
-rw-r--r--contrib/libreadline/doc/hstech.texinfo9
-rw-r--r--contrib/libreadline/doc/hsuser.texinfo2
-rw-r--r--contrib/libreadline/doc/manvers.texinfo14
-rw-r--r--contrib/libreadline/doc/rlman.texinfo4
-rw-r--r--contrib/libreadline/doc/rltech.texinfo200
-rw-r--r--contrib/libreadline/doc/rluser.texinfo148
-rw-r--r--contrib/libreadline/doc/rluserman.texinfo4
10 files changed, 355 insertions, 131 deletions
diff --git a/contrib/libreadline/doc/Makefile.in b/contrib/libreadline/doc/Makefile.in
index bf3a5a3..8a85ae1 100644
--- a/contrib/libreadline/doc/Makefile.in
+++ b/contrib/libreadline/doc/Makefile.in
@@ -27,10 +27,16 @@ infodir = @infodir@
mandir = @mandir@
manpfx = man
-man1ext = 1
-man1dir = $(mandir)/$(manpfx)$(man1ext)
-man3ext = 3
-man3dir = $(mandir)/$(manpfx)$(man3ext)
+man1ext = .1
+man1dir = $(mandir)/$(manpfx)1
+man3ext = .3
+man3dir = $(mandir)/$(manpfx)3
+
+# set this to a value to have the HTML documentation installed
+htmldir =
+
+# Support an alternate destination root directory for package building
+DESTDIR =
SHELL = @MAKE_SHELL@
RM = rm -f
@@ -112,10 +118,12 @@ history.ps: history.dvi
$(RM) $@
$(DVIPS) history.dvi
+#
+# This leaves readline.html and rlman.html -- rlman.html is for www.gnu.org
+#
readline.html: ${RLSRC}
$(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/rlman.texinfo
sed -e 's:rlman.html:readline.html:g' rlman.html > readline.html
- $(RM) rlman.html
rluserman.html: ${RLSRC}
$(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/rluserman.texinfo
@@ -145,13 +153,18 @@ history_3.ps: history.3
clean:
$(RM) *.aux *.cp *.fn *.ky *.log *.pg *.toc *.tp *.vr *.cps *.pgs \
- *.fns *.kys *.tps *.vrs *.bt *.bts *.o core
+ *.fns *.kys *.tps *.vrs *.bt *.bts *.o core *.core
-distclean: clean
+mostlyclean: clean
+
+distclean: clean maybe-clean
$(RM) $(INTERMEDIATE_OBJ)
$(RM) Makefile
-mostlyclean: clean
+maybe-clean:
+ -if test "X$(topdir)" != "X$(BUILD_DIR)"; then \
+ $(RM) $(DIST_DOCS); \
+ fi
maintainer-clean: clean
$(RM) $(DIST_DOCS)
@@ -159,34 +172,63 @@ maintainer-clean: clean
$(RM) Makefile
installdirs: $(topdir)/support/mkdirs
- -$(SHELL) $(topdir)/support/mkdirs $(infodir) $(man3dir)
+ -$(SHELL) $(topdir)/support/mkdirs $(DESTDIR)$(infodir) $(DESTDIR)$(man3dir)
+ -if test -n "${htmldir}" ; then \
+ $(SHELL) $(topdir)/support/mkdirs $(DESTDIR)$(htmldir) ; \
+ fi
install: installdirs
if test -f readline.info; then \
- ${INSTALL_DATA} readline.info $(infodir)/readline.info; \
+ ${INSTALL_DATA} readline.info $(DESTDIR)$(infodir)/readline.info; \
else \
- ${INSTALL_DATA} $(srcdir)/readline.info $(infodir)/readline.info; \
+ ${INSTALL_DATA} $(srcdir)/readline.info $(DESTDIR)$(infodir)/readline.info; \
fi
if test -f rluserman.info; then \
- ${INSTALL_DATA} rluserman.info $(infodir)/rluserman.info; \
+ ${INSTALL_DATA} rluserman.info $(DESTDIR)$(infodir)/rluserman.info; \
else \
- ${INSTALL_DATA} $(srcdir)/rluserman.info $(infodir)/rluserman.info; \
+ ${INSTALL_DATA} $(srcdir)/rluserman.info $(DESTDIR)$(infodir)/rluserman.info; \
fi
if test -f history.info; then \
- ${INSTALL_DATA} history.info $(infodir)/history.info; \
+ ${INSTALL_DATA} history.info $(DESTDIR)$(infodir)/history.info; \
else \
- ${INSTALL_DATA} $(srcdir)/history.info $(infodir)/history.info; \
+ ${INSTALL_DATA} $(srcdir)/history.info $(DESTDIR)$(infodir)/history.info; \
fi
-if $(SHELL) -c 'install-info --version' >/dev/null 2>&1; then \
- install-info --dir-file=$(infodir)/dir $(infodir)/readline.info ; \
- install-info --dir-file=$(infodir)/dir $(infodir)/history.info ; \
+ install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+ $(DESTDIR)$(infodir)/readline.info ; \
+ install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+ $(DESTDIR)$(infodir)/history.info ; \
+ install-info --dir-file=$(DESTDIR)$(infodir)/dir \
+ $(DESTDIR)$(infodir)/rluserman.info ; \
else true; fi
- -${INSTALL_DATA} $(srcdir)/readline.3 $(man3dir)/readline.3
- -${INSTALL_DATA} $(srcdir)/history.3 $(man3dir)/history.3
+ -${INSTALL_DATA} $(srcdir)/readline.3 $(DESTDIR)$(man3dir)/readline$(man3ext)
+ -${INSTALL_DATA} $(srcdir)/history.3 $(DESTDIR)$(man3dir)/history$(man3ext)
+ -if test -n "${htmldir}" ; then \
+ if test -f readline.html; then \
+ ${INSTALL_DATA} readline.html $(DESTDIR)$(htmldir)/readline.html; \
+ else \
+ ${INSTALL_DATA} $(srcdir)/readline.html $(DESTDIR)$(htmldir)/readline.html; \
+ fi ; \
+ if test -f history.html; then \
+ ${INSTALL_DATA} history.html $(DESTDIR)$(htmldir)/history.html; \
+ else \
+ ${INSTALL_DATA} $(srcdir)/history.html $(DESTDIR)$(htmldir)/history.html; \
+ fi ; \
+ if test -f rluserman.html; then \
+ ${INSTALL_DATA} rluserman.html $(DESTDIR)$(htmldir)/rluserman.html; \
+ else \
+ ${INSTALL_DATA} $(srcdir)/rluserman.html $(DESTDIR)$(htmldir)/rluserman.html; \
+ fi ; \
+ fi
uninstall:
- $(RM) $(infodir)/readline.info
- $(RM) $(infodir)/rluserman.info
- $(RM) $(infodir)/history.info
- $(RM) $(man3dir)/readline.3
- $(RM) $(man3dir)/history.3
+ $(RM) $(DESTDIR)$(infodir)/readline.info
+ $(RM) $(DESTDIR)$(infodir)/rluserman.info
+ $(RM) $(DESTDIR)$(infodir)/history.info
+ $(RM) $(DESTDIR)$(man3dir)/readline$(man3ext)
+ $(RM) $(DESTDIR)$(man3dir)/history$(man3ext)
+ -if test -n "${htmldir}" ; then \
+ $(RM) $(DESTDIR)$(htmldir)/readline.html ; \
+ $(RM) $(DESTDIR)$(htmldir)/rluserman.html ; \
+ $(RM) $(DESTDIR)$(htmldir)/history.html ; \
+ fi
diff --git a/contrib/libreadline/doc/hist.texinfo b/contrib/libreadline/doc/hist.texinfo
index 90ace3c..63ceb16 100644
--- a/contrib/libreadline/doc/hist.texinfo
+++ b/contrib/libreadline/doc/hist.texinfo
@@ -18,7 +18,7 @@ This document describes the GNU History library, a programming tool that
provides a consistent user interface for recalling lines of previously
typed input.
-Copyright (C) 1988-2001 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -73,7 +73,7 @@ except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988-2001 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2002 Free Software Foundation, Inc.
@end titlepage
@ifinfo
diff --git a/contrib/libreadline/doc/history.3 b/contrib/libreadline/doc/history.3
index 93702b4..ed0cb9f 100644
--- a/contrib/libreadline/doc/history.3
+++ b/contrib/libreadline/doc/history.3
@@ -6,9 +6,9 @@
.\" Case Western Reserve University
.\" chet@ins.CWRU.Edu
.\"
-.\" Last Change: Tue Mar 6 12:50:54 EST 2001
+.\" Last Change: Thu Jan 31 16:08:07 EST 2002
.\"
-.TH HISTORY 3 "2001 Mar 6" "GNU History 4.2"
+.TH HISTORY 3 "2002 January 31" "GNU History 4.3"
.\"
.\" File Name macro. This used to be `.PN', for Path Name,
.\" but Sun doesn't seem to like that very much.
@@ -40,8 +40,8 @@
.SH NAME
history \- GNU History Library
.SH COPYRIGHT
-.if t The GNU History Library is Copyright \(co 1989-2001 by the Free Software Foundation, Inc.
-.if n The GNU History Library is Copyright (C) 1989-2001 by the Free Software Foundation, Inc.
+.if t The GNU History Library is Copyright \(co 1989-2002 by the Free Software Foundation, Inc.
+.if n The GNU History Library is Copyright (C) 1989-2002 by the Free Software Foundation, Inc.
.SH DESCRIPTION
Many programs read input from the user a line at a time. The GNU
History library is able to keep track of those lines, associate arbitrary
@@ -362,7 +362,8 @@ Clear the history list by deleting all the entries.
Stifle the history list, remembering only the last \fImax\fP entries.
.Fn1 int unstifle_history "void"
-Stop stifling the history. This returns the previous amount the
+Stop stifling the history. This returns the previously-set
+maximum number of history entries (as set by \fBstifle_history()\fP).
history was stifled. The value is positive if the history was
stifled, negative if it wasn't.
diff --git a/contrib/libreadline/doc/hstech.texinfo b/contrib/libreadline/doc/hstech.texinfo
index e4ac50c..9494446 100644
--- a/contrib/libreadline/doc/hstech.texinfo
+++ b/contrib/libreadline/doc/hstech.texinfo
@@ -1,7 +1,7 @@
@ignore
This file documents the user interface to the GNU History library.
-Copyright (C) 1988-2001 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
Permission is granted to make and distribute verbatim copies of this manual
@@ -188,8 +188,9 @@ Stifle the history list, remembering only the last @var{max} entries.
@end deftypefun
@deftypefun int unstifle_history (void)
-Stop stifling the history. This returns the previous amount the
-history was stifled. The value is positive if the history was
+Stop stifling the history. This returns the previously-set
+maximum number of history entries (as set by @code{stifle_history()}).
+The value is positive if the history was
stifled, negative if it wasn't.
@end deftypefun
@@ -422,7 +423,7 @@ This is disabled by default.
@end deftypevar
@deftypevar {char *} history_word_delimiters
-The characters that separate tokens for \fBhistory_tokenize()\fP.
+The characters that separate tokens for @code{history_tokenize()}.
The default value is @code{" \t\n()<>;&|"}.
@end deftypevar
diff --git a/contrib/libreadline/doc/hsuser.texinfo b/contrib/libreadline/doc/hsuser.texinfo
index 6926b26..418bfa8 100644
--- a/contrib/libreadline/doc/hsuser.texinfo
+++ b/contrib/libreadline/doc/hsuser.texinfo
@@ -1,7 +1,7 @@
@ignore
This file documents the user interface to the GNU History library.
-Copyright (C) 1988-1999 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
Permission is granted to make and distribute verbatim copies of this manual
diff --git a/contrib/libreadline/doc/manvers.texinfo b/contrib/libreadline/doc/manvers.texinfo
index 23d3073..1206cf0 100644
--- a/contrib/libreadline/doc/manvers.texinfo
+++ b/contrib/libreadline/doc/manvers.texinfo
@@ -1,6 +1,10 @@
-@set EDITION 4.2-beta
-@set VERSION 4.2-beta
-@set UPDATED 2001 Mar 12
-@set UPDATE-MONTH Mar 2001
+@ignore
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
+@end ignore
-@set LASTCHANGE Mon Mar 12 05:36:44 EST 2001
+@set EDITION 4.3
+@set VERSION 4.3
+@set UPDATED 2002 March 4
+@set UPDATE-MONTH March 2002
+
+@set LASTCHANGE Mon Mar 4 12:00:16 EST 2002
diff --git a/contrib/libreadline/doc/rlman.texinfo b/contrib/libreadline/doc/rlman.texinfo
index 894c516..1ffebad 100644
--- a/contrib/libreadline/doc/rlman.texinfo
+++ b/contrib/libreadline/doc/rlman.texinfo
@@ -18,7 +18,7 @@ This document describes the GNU Readline Library, a utility which aids
in the consistency of user interface across discrete programs that need
to provide a command line interface.
-Copyright (C) 1988-2001 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -73,7 +73,7 @@ except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988-2001 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2002 Free Software Foundation, Inc.
@end titlepage
@ifinfo
diff --git a/contrib/libreadline/doc/rltech.texinfo b/contrib/libreadline/doc/rltech.texinfo
index acc8d4d..037e824 100644
--- a/contrib/libreadline/doc/rltech.texinfo
+++ b/contrib/libreadline/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-2001 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -111,12 +111,13 @@ function, and has the advantage of no static buffer to overflow:
/* A static variable for holding the line. */
static char *line_read = (char *)NULL;
-/* Read a string, and return a pointer to it. Returns NULL on EOF. */
+/* Read a string, and return a pointer to it.
+ Returns NULL on EOF. */
char *
rl_gets ()
@{
- /* If the buffer has already been allocated, return the memory
- to the free pool. */
+ /* If the buffer has already been allocated,
+ return the memory to the free pool. */
if (line_read)
@{
free (line_read);
@@ -126,7 +127,8 @@ rl_gets ()
/* Get a line from the user. */
line_read = readline ("");
- /* If the line has any text in it, save it on the history. */
+ /* If the line has any text in it,
+ save it on the history. */
if (line_read && *line_read)
add_history (line_read);
@@ -176,6 +178,16 @@ in any file that uses Readline's features. Since some of the definitions
in @code{readline.h} use the @code{stdio} library, the file
@code{<stdio.h>} should be included before @code{readline.h}.
+@code{readline.h} defines a C preprocessor variable that should
+be treated as an integer, @code{RL_READLINE_VERSION}, which may
+be used to conditionally compile application code depending on
+the installed Readline version. The value is a hexadecimal
+encoding of the major and minor version numbers of the library,
+of the form 0x@var{MMmm}. @var{MM} is the two-digit major
+version number; @var{mm} is the two-digit minor version number.
+For Readline 4.2, for example, the value of
+@code{RL_READLINE_VERSION} would be @code{0x0402}.
+
@menu
* Readline Typedefs:: C declarations to make code readable.
* Function Writing:: Variables and calling conventions.
@@ -253,7 +265,7 @@ variables that describe the current state of the line read so far.
The calling sequence for a command @code{foo} looks like
@example
-@code{foo (int count, int key)}
+@code{int foo (int count, int key)}
@end example
@noindent
@@ -270,6 +282,9 @@ to do something useful with both negative and positive arguments.
At the very least, it should be aware that it can be passed a
negative argument.
+A command function should return 0 if its action completes successfully,
+and a non-zero value if some error occurs.
+
@node Readline Variables
@section Readline Variables
@@ -348,6 +363,14 @@ never sets it.
The version number of this revision of the library.
@end deftypevar
+@deftypevar int rl_readline_version
+An integer encoding the current version of the library. The encoding is
+of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version
+number, and @var{mm} is the two-digit minor version number.
+For example, for Readline-4.2, @code{rl_readline_version} would have the
+value 0x0402.
+@end deftypevar
+
@deftypevar {int} rl_gnu_readline_p
Always set to 1, denoting that this is @sc{gnu} readline rather than some
emulation.
@@ -367,10 +390,12 @@ The value allows conditional parsing of the inputrc file
@deftypevar {FILE *} rl_instream
The stdio stream from which Readline reads input.
+If @code{NULL}, Readline defaults to @var{stdin}.
@end deftypevar
@deftypevar {FILE *} rl_outstream
The stdio stream to which Readline performs output.
+If @code{NULL}, Readline defaults to @var{stdout}.
@end deftypevar
@deftypevar {rl_command_func_t *} rl_last_func
@@ -748,9 +773,9 @@ This is done with @code{rl_begin_undo_group()} and
The types of events that can be undone are:
-@example
+@smallexample
enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
-@end example
+@end smallexample
Notice that @code{UNDO_DELETE} means to insert some text, and
@code{UNDO_INSERT} means to delete some text. That is, the undo code
@@ -883,10 +908,12 @@ to the result.
@deftypefun int rl_insert_text (const char *text)
Insert @var{text} into the line at the current cursor position.
+Returns the number of characters inserted.
@end deftypefun
@deftypefun int rl_delete_text (int start, int end)
Delete the text between @var{start} and @var{end} in the current line.
+Returns the number of characters deleted.
@end deftypefun
@deftypefun {char *} rl_copy_text (int start, int end)
@@ -929,7 +956,9 @@ be the keyboard.
@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
-@code{rl_read_key()}.
+@code{rl_read_key()}. Up to 512 characters may be pushed back.
+@code{rl_stuff_char} returns 1 if the character was successfully inserted;
+0 otherwise.
@end deftypefun
@deftypefun int rl_execute_next (int c)
@@ -982,6 +1011,13 @@ environment variable is used.
@node Utility Functions
@subsection Utility Functions
+@deftypefun void rl_replace_line (const char *text, int clear_undo)
+Replace the contents of @code{rl_line_buffer} with @var{text}.
+The point and mark are preserved, if possible.
+If @var{clear_undo} is non-zero, the undo list associated with the
+current line is cleared.
+@end deftypefun
+
@deftypefun int rl_extend_line_buffer (int len)
Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
characters, possibly reallocating it if necessary.
@@ -1076,6 +1112,15 @@ Set the time interval (in microseconds) that Readline waits when showing
a balancing character when @code{blink-matching-paren} has been enabled.
@end deftypefun
+@deftypefun {char *} rl_get_termcap (const char *cap)
+Retrieve the string value of the termcap capability @var{cap}.
+Readline fetches the termcap entry for the current terminal name and
+uses those capabilities to move around the screen line and perform other
+terminal-specific operations, like erasing a line. Readline does not
+use all of a terminal's capabilities, and this function will return
+values for only those capabilities Readline uses.
+@end deftypefun
+
@node Alternate Interface
@subsection Alternate Interface
@@ -1096,16 +1141,26 @@ The function takes the text of the line as an argument.
@deftypefun void rl_callback_read_char (void)
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
+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.
+Before calling the @var{lhandler} function, the terminal settings are
+reset to the values they had before calling
+@code{rl_callback_handler_install}.
+If the @var{lhandler} function returns,
+the terminal settings are modified for Readline's use again.
+@code{EOF} is indicated by calling @var{lhandler} with a
@code{NULL} line.
@end deftypefun
@deftypefun void rl_callback_handler_remove (void)
Restore the terminal to its initial state and remove the line handler.
This may be called from within a callback as well as independently.
+If the @var{lhandler} installed by @code{rl_callback_handler_install}
+does not exit the program, either this function or the function referred
+to by the value of @code{rl_deprep_term_function} should be called before
+the program exits to reset the terminal settings.
@end deftypefun
@node A Readline Example
@@ -1158,8 +1213,8 @@ invert_case_line (count, key)
end = temp;
@}
- /* Tell readline that we are modifying the line, so it will save
- the undo information. */
+ /* Tell readline that we are modifying the line,
+ so it will save the undo information. */
rl_modifying (start, end);
for (i = start; i != end; i++)
@@ -1415,6 +1470,14 @@ partially-completed word. See description of @code{rl_complete()}.
This calls @code{rl_complete_internal()} with an argument of @samp{*}.
@end deftypefun
+@deftypefun int rl_completion_mode (rl_command_func_t *cfunc)
+Returns the apppriate value to pass to @code{rl_complete_internal()}
+depending on whether @var{cfunc} was called twice in succession and
+the value of the @code{show-all-if-ambiguous} variable.
+Application-specific completion functions may use this function to present
+the same interface as @code{rl_complete()}.
+@end deftypefun
+
@deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)
Returns an array of strings which is a list of completions for
@var{text}. If there are no completions, returns @code{NULL}.
@@ -1501,10 +1564,41 @@ 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
-she wants to see them all. The default value is 100.
+@deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function
+This function, if defined, is called by the completer when real filename
+completion is done, after all the matching names have been generated.
+It is passed a @code{NULL} terminated array of matches.
+The first element (@code{matches[0]}) is the
+maximal substring common to all matches. This function can
+re-arrange the list of matches as required, but each element deleted
+from the array must be freed.
+@end deftypevar
+
+@deftypevar {rl_icppfunc_t *} rl_directory_completion_hook
+This function, if defined, is allowed to modify the directory portion
+of filenames Readline completes. It is called with the address of a
+string (the current directory name) as an argument, and may modify that string.
+If the string is replaced with a new string, the old value should be freed.
+Any modified directory name should have a trailing slash.
+The modified value will be displayed as part of the completion, replacing
+the directory portion of the pathname the user typed.
+It returns an integer that should be non-zero if the function modifies
+its directory argument.
+It could be used to expand symbolic links or shell variables in pathnames.
+@end deftypevar
+
+@deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook
+If non-zero, then this is the address of a function to call when
+completing a word would normally display the list of possible matches.
+This function is called in lieu of Readline displaying the list.
+It takes three arguments:
+(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
+where @var{matches} is the array of matching strings,
+@var{num_matches} is the number of strings in that array, and
+@var{max_length} is the length of the longest string in that array.
+Readline provides a convenience function, @code{rl_display_match_list},
+that takes care of doing the display to Readline's output stream. That
+function may be called from this hook.
@end deftypevar
@deftypevar {const char *} rl_basic_word_break_characters
@@ -1544,6 +1638,12 @@ For instance, Bash sets this variable to "$@@" so that it can complete
shell variables and hostnames.
@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
+she wants to see them all. The default value is 100.
+@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
@@ -1554,6 +1654,24 @@ provide the ``most sensible word separator character'' according to
an application-specific command line syntax specification.
@end deftypevar
+@deftypevar int rl_completion_suppress_append
+If non-zero, @var{rl_completion_append_character} is not appended to
+matches at the end of the command line, as described above. It is
+set to 0 before any application-specific completion function is called.
+@end deftypevar
+
+@deftypevar int rl_completion_mark_symlink_dirs
+If non-zero, a slash will be appended to completed filenames that are
+symbolic links to directory names, subject to the value of the
+user-settable @var{mark-directories} variable.
+This variable exists so that application completion functions can
+override the user's global preference (set via the
+@var{mark-symlinked-directories} Readline variable) if appropriate.
+This variable is set to the user's preference before any
+application completion function is called, so unless that function
+modifies the value, the user's preferences are honored.
+@end deftypevar
+
@deftypevar int rl_ignore_completion_duplicates
If non-zero, then duplicates in the matches are removed.
The default is 1.
@@ -1598,43 +1716,6 @@ 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 {rl_compignore_func_t *} rl_ignore_some_completions_function
-This function, if defined, is called by the completer when real filename
-completion is done, after all the matching names have been generated.
-It is passed a @code{NULL} terminated array of matches.
-The first element (@code{matches[0]}) is the
-maximal substring common to all matches. This function can
-re-arrange the list of matches as required, but each element deleted
-from the array must be freed.
-@end deftypevar
-
-@deftypevar {rl_icppfunc_t *} rl_directory_completion_hook
-This function, if defined, is allowed to modify the directory portion
-of filenames Readline completes. It is called with the address of a
-string (the current directory name) as an argument, and may modify that string.
-If the string is replaced with a new string, the old value should be freed.
-Any modified directory name should have a trailing slash.
-The modified value will be displayed as part of the completion, replacing
-the directory portion of the pathname the user typed.
-It returns an integer that should be non-zero if the function modifies
-its directory argument.
-It could be used to expand symbolic links or shell variables in pathnames.
-@end deftypevar
-
-@deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook
-If non-zero, then this is the address of a function to call when
-completing a word would normally display the list of possible matches.
-This function is called in lieu of Readline displaying the list.
-It takes three arguments:
-(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
-where @var{matches} is the array of matching strings,
-@var{num_matches} is the number of strings in that array, and
-@var{max_length} is the length of the longest string in that array.
-Readline provides a convenience function, @code{rl_display_match_list},
-that takes care of doing the display to Readline's output stream. That
-function may be called from this hook.
-@end deftypevar
-
@node A Short Completion Example
@subsection A Short Completion Example
@@ -2062,12 +2143,13 @@ too_dangerous (caller)
char *caller;
@{
fprintf (stderr,
- "%s: Too dangerous for me to distribute. Write it yourself.\n",
+ "%s: Too dangerous for me to distribute.\n"
caller);
+ fprintf (stderr, "Write it yourself.\n");
@}
-/* Return non-zero if ARG is a valid argument for CALLER, else print
- an error message and return zero. */
+/* Return non-zero if ARG is a valid argument for CALLER,
+ else print an error message and return zero. */
int
valid_argument (caller, arg)
char *caller, *arg;
diff --git a/contrib/libreadline/doc/rluser.texinfo b/contrib/libreadline/doc/rluser.texinfo
index e5bf54d..94f851e 100644
--- a/contrib/libreadline/doc/rluser.texinfo
+++ b/contrib/libreadline/doc/rluser.texinfo
@@ -10,7 +10,7 @@ use these features. There is a document entitled "readline.texinfo"
which contains both end-user and programmer documentation for the
GNU Readline Library.
-Copyright (C) 1988-2000 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
@@ -235,7 +235,7 @@ words, to the end of the next word.
Word boundaries are the same as those used by @kbd{M-f}.
@item M-@key{DEL}
-Kill from the cursor the start of the previous word, or, if between
+Kill from the cursor the start of the current word, or, if between
words, to the start of the previous word.
Word boundaries are the same as those used by @kbd{M-b}.
@@ -312,6 +312,10 @@ the line, thereby executing the command from the history list.
A movement command will terminate the search, make the last line found
the current line, and begin editing.
+Readline remembers the last incremental search string. If two
+@kbd{C-r}s are typed without any intervening characters defining a new
+search string, any remembered search string is used.
+
Non-incremental searches read the entire search string before starting
to search for matching history lines. The search string may be
typed by the user or be part of the contents of the current line.
@@ -452,6 +456,11 @@ arrow keys. The default is @samp{off}.
If set to @samp{on}, tilde expansion is performed when Readline
attempts word completion. The default is @samp{off}.
+@vindex history-preserve-point
+If set to @samp{on}, the history code attempts to place point at the
+same location on each history line retrived with @code{previous-history}
+or @code{next-history}.
+
@item horizontal-scroll-mode
@vindex horizontal-scroll-mode
This variable can be set to either @samp{on} or @samp{off}. Setting it
@@ -503,12 +512,33 @@ This variable, when set to @samp{on}, causes Readline to display an
asterisk (@samp{*}) at the start of history lines which have been modified.
This variable is @samp{off} by default.
+@item mark-symlinked-directories
+@vindex mark-symlinked-directories
+If set to @samp{on}, completed names which are symbolic links
+to directories have a slash appended (subject to the value of
+@code{mark-directories}).
+The default is @samp{off}.
+
+@item match-hidden-files
+@vindex match-hidden-files
+This variable, when set to @samp{on}, causes Readline to match files whose
+names begin with a @samp{.} (hidden files) when performing filename
+completion, unless the leading @samp{.} is
+supplied by the user in the filename to be completed.
+This variable is @samp{on} by default.
+
@item output-meta
@vindex output-meta
If set to @samp{on}, Readline will display characters with the
eighth bit set directly rather than as a meta-prefixed escape
sequence. The default is @samp{off}.
+@item page-completions
+@vindex page-completions
+If set to @samp{on}, Readline uses an internal @code{more}-like pager
+to display a screenful of possible completions at a time.
+This variable is @samp{on} by default.
+
@item print-completions-horizontally
If set to @samp{on}, Readline will display completions with matches
sorted horizontally in alphabetical order, rather than down the screen.
@@ -644,11 +674,11 @@ horizontal tab
@item \v
vertical tab
@item \@var{nnn}
-the character whose @sc{ascii} code is the octal value @var{nnn}
-(one to three digits)
-@item \x@var{nnn}
-the character whose @sc{ascii} code is the hexadecimal value @var{nnn}
+the eight-bit character whose value is the octal value @var{nnn}
(one to three digits)
+@item \x@var{HH}
+the eight-bit character whose value is the hexadecimal value @var{HH}
+(one or two hex digits)
@end table
When entering the text of a macro, single or double quotes must
@@ -740,14 +770,14 @@ binding, variable assignment, and conditional syntax.
@example
@page
# This file controls the behaviour of line input editing for
-# programs that use the Gnu Readline library. Existing programs
-# include FTP, Bash, and Gdb.
+# programs that use the GNU Readline library. Existing
+# programs include FTP, Bash, and GDB.
#
# You can re-read the inputrc file with C-x C-r.
# Lines beginning with '#' are comments.
#
-# First, include any systemwide bindings and variable assignments from
-# /etc/Inputrc
+# First, include any systemwide bindings and variable
+# assignments from /etc/Inputrc
$include /etc/Inputrc
#
@@ -799,10 +829,12 @@ TAB: complete
$if Bash
# edit the path
"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f"
-# prepare to type a quoted word -- insert open and close double quotes
+# prepare to type a quoted word --
+# insert open and close double quotes
# and move to just after the open quote
"\C-x\"": "\"\"\C-b"
-# insert a backslash (testing backslash escapes in sequences and macros)
+# insert a backslash (testing backslash escapes
+# in sequences and macros)
"\C-x\\": "\\"
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
@@ -818,16 +850,16 @@ set bell-style visible
# don't strip characters to 7 bits when reading
set input-meta on
-# allow iso-latin1 characters to be inserted rather than converted to
-# prefix-meta sequences
+# allow iso-latin1 characters to be inserted rather
+# than converted to prefix-meta sequences
set convert-meta off
-# display characters with the eighth bit set directly rather than
-# as meta-prefixed characters
+# display characters with the eighth bit set directly
+# rather than as meta-prefixed characters
set output-meta on
-# if there are more than 150 possible completions for a word, ask the
-# user if he wants to see all of them
+# if there are more than 150 possible completions for
+# a word, ask the user if he wants to see all of them
set completion-query-items 150
# For FTP
@@ -1021,6 +1053,8 @@ Negative arguments have no effect.
@item transpose-words (M-t)
Drag the word before point past the word after point,
moving point past that word as well.
+If the insertion point is at the end of the line, this transposes
+the last two words on the line.
@item upcase-word (M-u)
Uppercase the current (or following) word. With a negative argument,
@@ -1034,6 +1068,20 @@ lowercase the previous word, but do not move the cursor.
Capitalize the current (or following) word. With a negative argument,
capitalize the previous word, but do not move the cursor.
+@item overwrite-mode ()
+Toggle overwrite mode. With an explicit positive numeric argument,
+switches to overwrite mode. With an explicit non-positive numeric
+argument, switches to insert mode. This command affects only
+@code{emacs} mode; @code{vi} mode does overwrite differently.
+Each call to @code{readline()} starts in insert mode.
+
+In overwrite mode, characters bound to @code{self-insert} replace
+the text at point rather than pushing the text to the right.
+Characters bound to @code{backward-delete-char} replace the character
+before point with a space.
+
+By default, this command is unbound.
+
@end ftable
@node Commands For Killing
@@ -1293,12 +1341,19 @@ of that character. A negative count searches for subsequent
occurrences.
@item insert-comment (M-#)
-The value of the @code{comment-begin}
-variable is inserted at the beginning of the current line,
-and the line is accepted as if a newline had been typed.
+Without a numeric argument, the value of the @code{comment-begin}
+variable is inserted at the beginning of the current line.
+If a numeric argument is supplied, this command acts as a toggle: if
+the characters at the beginning of the line do not match the value
+of @code{comment-begin}, the value is inserted, otherwise
+the characters in @code{comment-begin} are deleted from the beginning of
+the line.
+In either case, the line is accepted as if a newline had been typed.
@ifset BashFeatures
The default value of @code{comment-begin} causes this command
to make the current line a shell comment.
+If a numeric argument causes the comment character to be removed, the line
+will be executed by the shell.
@end ifset
@item dump-functions ()
@@ -1320,13 +1375,22 @@ the output is formatted in such a way that it can be made part
of an @var{inputrc} file. This command is unbound by default.
@ifset BashFeatures
+@item glob-complete-word (M-g)
+The word before point is treated as a pattern for pathname expansion,
+with an asterisk implicitly appended. This pattern is used to
+generate a list of matching file names for possible completions.
+
@item glob-expand-word (C-x *)
The word before point is treated as a pattern for pathname expansion,
and the list of matching file names is inserted, replacing the word.
+If a numeric argument is supplied, a @samp{*} is appended before
+pathname expansion.
@item glob-list-expansions (C-x g)
The list of expansions that would have been generated by
@code{glob-expand-word} is displayed, and the line is redrawn.
+If a numeric argument is supplied, a @samp{*} is appended before
+pathname expansion.
@item display-shell-version (C-x C-v)
Display version information about the current instance of Bash.
@@ -1357,13 +1421,26 @@ Accept the current line for execution and fetch the next line
relative to the current line from the history for editing. Any
argument is ignored.
-@item emacs-editing-mode (C-e)
-When in @code{vi} editing mode, this causes a switch back to
-@code{emacs} editing mode, as if the command @samp{set -o emacs} had
-been executed.
+@item edit-and-execute-command (C-xC-e)
+Invoke an editor on the current command line, and execute the result as shell
+commands.
+Bash attempts to invoke
+@code{$FCEDIT}, @code{$EDITOR}, and @code{emacs}
+as the editor, in that order.
@end ifset
+@ifclear BashFeatures
+@item emacs-editing-mode (C-e)
+When in @code{vi} command mode, this causes a switch to @code{emacs}
+editing mode.
+
+@item vi-editing-mode (M-C-j)
+When in @code{emacs} editing mode, this causes a switch to @code{vi}
+editing mode.
+
+@end ifclear
+
@end ftable
@node Readline vi Mode
@@ -1499,6 +1576,12 @@ If the @option{-o default} option was supplied to @code{complete} when the
compspec was defined, Readline's default completion will be performed
if the compspec generates no matches.
+When a compspec indicates that directory name completion is desired,
+the programmable completion functions force Readline to append a slash
+to completed names which are symbolic links to directories, subject to
+the value of the @var{mark-directories} Readline variable, regardless
+of the setting of the @var{mark-symlinked-directories} Readline variable.
+
@node Programmable Completion Builtins
@section Programmable Completion Builtins
@cindex completion builtins
@@ -1534,7 +1617,7 @@ matches were generated.
@item complete
@btindex complete
@example
-@code{complete [-abcdefjkvu] [-o @var{comp-option}] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
+@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
[-P @var{prefix}] [-S @var{suffix}] [-X @var{filterpat}] [-F @var{function}]
[-C @var{command}] @var{name} [@var{name} @dots{}]}
@code{complete -pr [@var{name} @dots{}]}
@@ -1567,7 +1650,8 @@ beyond the simple generation of completions.
@table @code
@item default
-Use readline's default completion if the compspec generates no matches.
+Use Readline's default filename completion if the compspec generates
+no matches.
@item dirnames
Perform directory name completion if the compspec generates no matches.
@@ -1577,6 +1661,10 @@ Tell Readline that the compspec generates filenames, so it can perform any
filename\-specific processing (like adding a slash to directory names or
suppressing trailing spaces). This option is intended to be used with
shell functions specified with @option{-F}.
+
+@item nospace
+Tell Readline not to append a space (the default) to words completed at
+the end of the line.
@end table
@item -A @var{action}
@@ -1617,6 +1705,9 @@ File names. May also be specified as @option{-f}.
@item function
Names of shell functions.
+@item group
+Group names. May also be specified as @option{-g}.
+
@item helptopic
Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}).
@@ -1633,6 +1724,9 @@ Shell reserved words. May also be specified as @option{-k}.
@item running
Names of running jobs, if job control is active.
+@item service
+Service names. May also be specified as @option{-s}.
+
@item setopt
Valid arguments for the @option{-o} option to the @code{set} builtin
(@pxref{The Set Builtin}).
diff --git a/contrib/libreadline/doc/rluserman.texinfo b/contrib/libreadline/doc/rluserman.texinfo
index db560b9..89abe31 100644
--- a/contrib/libreadline/doc/rluserman.texinfo
+++ b/contrib/libreadline/doc/rluserman.texinfo
@@ -17,7 +17,7 @@ This document describes the end user interface of the GNU Readline Library,
a utility which aids in the consistency of user interface across discrete
programs that need to provide a command line interface.
-Copyright (C) 1988-2001 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -72,7 +72,7 @@ except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988-2001 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2002 Free Software Foundation, Inc.
@end titlepage
@ifinfo
OpenPOWER on IntegriCloud