dmbcs/i-bash
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Bash-4.3 distribution sources and documentation

Browse source
This commit is contained in:
Chet Ramey 2014-02-26 09:36:43 -05:00
commit ac50fbac37
497 changed files with 129395 additions and 87598 deletions
Download patch file Download diff file Expand all files Collapse all files

26
lib/readline/doc/history.texi
View file

@ -2,33 +2,25 @@
@c %**start of header (This is for running Texinfo on a region.)
@setfilename history.info
@settitle GNU History Library
@c %**end of header (This is for running Texinfo on a region.)
@include version.texi
@c %**end of header (This is for running Texinfo on a region.)
@copying
This document describes the GNU History library
(version @value{VERSION}, @value{UPDATED}),
a programming tool that provides a consistent user interface for
recalling lines of previously typed input.
Copyright @copyright{} 1988--2011 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Copyright @copyright{} 1988--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license is
included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: You are free to copy and modify
this GNU manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@ -50,12 +42,6 @@ developing GNU and promoting software freedom.''
@vskip 0pt plus 1filll
@insertcopying
@sp 1
Published by the Free Software Foundation @*
59 Temple Place, Suite 330, @*
Boston, MA 02111-1307 @*
USA @*
@end titlepage
@contents

4
lib/readline/doc/hstech.texi
View file

@ -1,7 +1,7 @@
@ignore
This file documents the user interface to the GNU History library.
Copyright (C) 1988-2011 Free Software Foundation, Inc.
Copyright (C) 1988-2014 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
Permission is granted to make and distribute verbatim copies of this manual
@ -377,7 +377,7 @@ if the returned line should be displayed, but not executed,
as with the @code{:p} modifier (@pxref{Modifiers}).
@end table
If an error ocurred in expansion, then @var{output} contains a descriptive
If an error occurred in expansion, then @var{output} contains a descriptive
error message.
@end deftypefun

24
lib/readline/doc/hsuser.texi
View file

@ -1,7 +1,7 @@
@ignore
This file documents the user interface to the GNU History library.
Copyright (C) 1988--2011 Free Software Foundation, Inc.
Copyright (C) 1988--2014 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
Permission is granted to make and distribute verbatim copies of this manual
@ -84,17 +84,18 @@ file named by the @env{HISTFILE} variable (default @file{~/.bash_history}).
The file named by the value of @env{HISTFILE} is truncated, if
necessary, to contain no more than the number of lines specified by
the value of the @env{HISTFILESIZE} variable.
When an interactive shell exits, the last
When a shell with history enabled exits, the last
@env{$HISTSIZE} lines are copied from the history list to the file
named by @env{$HISTFILE}.
If the @code{histappend} shell option is set (@pxref{Bash Builtins}),
the lines are appended to the history file,
otherwise the history file is overwritten.
If @env{HISTFILE}
is unset, or if the history file is unwritable, the history is
not saved. After saving the history, the history file is truncated
to contain no more than @env{$HISTFILESIZE}
lines. If @env{HISTFILESIZE} is not set, no truncation is performed.
is unset, or if the history file is unwritable, the history is not saved.
After saving the history, the history file is truncated
to contain no more than @env{$HISTFILESIZE} lines.
If @env{HISTFILESIZE} is unset, or set to null, a non-numeric value, or
a numeric value less than zero, the history file is not truncated.
If the @env{HISTTIMEFORMAT} is set, the time stamp information
associated with each history entry is written to the history file,
@ -141,8 +142,10 @@ history list and history file.
@code{fc -s [@var{pat}=@var{rep}] [@var{command}]}
@end example
Fix Command. In the first form, a range of commands from @var{first} to
@var{last} is selected from the history list. Both @var{first} and
The first form selects a range of commands from @var{first} to
@var{last} from the history list and displays or edits and re-executes
them.
Both @var{first} and
@var{last} may be specified as a string (to locate the most recent
command beginning with that string) or as a number (an index into the
history list, where a negative number is used as an offset from the
@ -161,6 +164,7 @@ When editing is complete, the edited commands are echoed and executed.
In the second form, @var{command} is re-executed after each instance
of @var{pat} in the selected command is replaced by @var{rep}.
@var{command} is intepreted the same as @var{first} above.
A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so
that typing @samp{r cc} runs the last command beginning with @code{cc}
@ -208,11 +212,11 @@ to the current history list. These are lines appended to the history
file since the beginning of the current Bash session.
@item -r
Read the current history file and append its contents to
Read the history file and append its contents to
the history list.
@item -w
Write out the current history to the history file.
Write out the current history list to the history file.
@item -p
Perform history substitution on the @var{arg}s and display the result

27
lib/readline/doc/rlman.texi
View file

@ -2,34 +2,26 @@
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename readline.info
@settitle GNU Readline Library
@include version.texi
@comment %**end of header (This is for running Texinfo on a region.)
@synindex vr fn
@include version.texi
@copying
This manual describes the GNU Readline Library
(version @value{VERSION}, @value{UPDATED}), a library which aids in the
consistency of user interface across discrete programs which provide
a command line interface.
Copyright @copyright{} 1988--2011 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Copyright @copyright{} 1988--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license is
included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: You are free to copy and modify
this GNU manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@ -50,12 +42,6 @@ developing GNU and promoting software freedom.''
@vskip 0pt plus 1filll
@insertcopying
@sp 1
Published by the Free Software Foundation @*
59 Temple Place, Suite 330, @*
Boston, MA 02111-1307 @*
USA @*
@end titlepage
@contents
@ -67,6 +53,7 @@ USA @*
This document describes the GNU Readline Library, a utility which aids
in the consistency of user interface across discrete programs which
provide a command line interface.
The Readline home page is @url{http://www.gnu.org/software/readline/}.
@menu
* Command Line Editing:: GNU Readline User's Manual.

210
lib/readline/doc/rltech.texi
View file

@ -7,7 +7,7 @@ This document describes the GNU Readline Library, a utility for aiding
in the consistency of user interface across discrete programs that need
to provide a command line interface.
Copyright (C) 1988--2011 Free Software Foundation, Inc.
Copyright (C) 1988--2014 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@ -195,7 +195,7 @@ For Readline 4.2, for example, the value of
@node Readline Typedefs
@subsection Readline Typedefs
For readabilty, we declare a number of new object types, all pointers
For readability, we declare a number of new object types, all pointers
to functions.
The reason for declaring these new types is to make it easier to write
@ -440,6 +440,35 @@ If non-zero, 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 Readline character input function
(@pxref{Character Input}).
In general, an application that sets @var{rl_getc_function} should consider
setting @var{rl_input_available_hook} as well.
@end deftypevar
@deftypevar {rl_hook_func_t *} rl_signal_event_hook
If non-zero, this is the address of a function to call if a read system
call is interrupted when Readline is reading terminal input.
@end deftypevar
@deftypevar {rl_hook_func_t *} rl_input_available_hook
If non-zero, Readline will use this function's return value when it needs
to determine whether or not there is available input on the current input
source.
The default hook checks @code{rl_instream}; if an application is using a
different input source, it should set the hook appropriately.
Readline queries for available input when implementing intra-key-sequence
timeouts during input and incremental searches.
This may use an application-specific timeout before returning a value;
Readline uses the value passed to @code{rl_set_keyboard_input_timeout()}
or the value of the user-settable @var{keyseq-timeout} variable.
This is designed for use by applications using Readline's callback interface
(@pxref{Alternate Interface}), which may not use the traditional
@code{read(2)} and file descriptor interface, or other applications using
a different input mechanism.
If an application uses an input mechanism or hook that can potentially exceed
the value of @var{keyseq-timeout}, it should increase the timeout or set
this hook appropriately even when not using the callback interface.
In general, an application that sets @var{rl_getc_function} should consider
setting @var{rl_input_available_hook} as well.
@end deftypevar
@deftypevar {rl_voidfunc_t *} rl_redisplay_function
@ -479,6 +508,19 @@ last key binding occurred.
This variable is set to the text of any currently-executing macro.
@end deftypevar
@deftypevar int rl_executing_key
The key that caused the dispatch to the currently-executing Readline function.
@end deftypevar
@deftypevar {char *} rl_executing_keyseq
The full key sequence that caused the dispatch to the currently-executing
Readline function.
@end deftypevar
@deftypevar int rl_key_sequence_length
The number of characters in @var{rl_executing_keyseq}.
@end deftypevar
@deftypevar {int} rl_readline_state
A variable with bit values that encapsulate the current Readline state.
A bit is set with the @code{RL_SETSTATE} macro, and unset with the
@ -487,7 +529,7 @@ whether a particular state bit is set. Current state bits include:
@table @code
@item RL_STATE_NONE
Readline has not yet been called, nor has it begun to intialize.
Readline has not yet been called, nor has it begun to initialize.
@item RL_STATE_INITIALIZING
Readline is initializing its internal data structures.
@item RL_STATE_INITIALIZED
@ -580,6 +622,7 @@ means that vi mode is active.
* Miscellaneous Functions:: Functions that don't fall into any category.
* Alternate Interface:: Using Readline in a `callback' fashion.
* A Readline Example:: An example Readline function.
* Alternate Interface Example:: An example program using the alternate interface.
@end menu
@node Function Naming
@ -908,7 +951,7 @@ Readline thinks the screen display is correct.
@deftypefun int rl_on_new_line (void)
Tell the update functions that we have moved onto a new (empty) line,
usually after ouputting a newline.
usually after outputting a newline.
@end deftypefun
@deftypefun int rl_on_new_line_with_prompt (void)
@ -1241,21 +1284,29 @@ use all of a terminal's capabilities, and this function will return
values for only those capabilities Readline uses.
@end deftypefun
@deftypefun {void} rl_clear_history (void)
Clear the history list by deleting all of the entries, in the same manner
as the History library's @code{clear_history()} function.
This differs from @code{clear_history} because it frees private data
Readline saves in the history list.
@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
on various file descriptors. To accommodate 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 (const char *prompt, rl_vcpfunc_t *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 function to call when a complete line of input has been entered.
The function takes the text of the line as an argument.
use as a handler function to call when a complete line of input has been
entered.
The handler function receives the text of the line as an argument.
@end deftypefun
@deftypefun void rl_callback_read_char (void)
@ -1263,14 +1314,15 @@ 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.
invoke the @var{lhandler} function installed 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,
and the line handler remains installed,
the terminal settings are modified for Readline's use again.
@code{EOF} is indicated by calling @var{lhandler} with a
@code{EOF} is indicated by calling @var{lhandler} with a
@code{NULL} line.
@end deftypefun
@ -1350,6 +1402,98 @@ invert_case_line (count, key)
@}
@end example
@node Alternate Interface Example
@subsection Alternate Interface Example
Here is a complete program that illustrates Readline's alternate interface.
It reads lines from the terminal and displays them, providing the
standard history and TAB completion functions.
It understands the EOF character or "exit" to exit the program.
@example
/* Standard include files. stdio.h is required. */
#include <stdlib.h>
#include <unistd.h>
/* Used for select(2) */
#include <sys/types.h>
#include <sys/select.h>
#include <stdio.h>
/* Standard readline include files. */
#include <readline/readline.h>
#include <readline/history.h>
static void cb_linehandler (char *);
int running;
const char *prompt = "rltest$ ";
/* Callback function called for each line when accept-line executed, EOF
seen, or EOF character read. This sets a flag and returns; it could
also call exit(3). */
static void
cb_linehandler (char *line)
@{
/* Can use ^D (stty eof) or `exit' to exit. */
if (line == NULL || strcmp (line, "exit") == 0)
@{
if (line == 0)
printf ("\n");
printf ("exit\n");
/* This function needs to be called to reset the terminal settings,
and calling it from the line handler keeps one extra prompt from
being displayed. */
rl_callback_handler_remove ();
running = 0;
@}
else
@{
if (*line)
add_history (line);
printf ("input line: %s\n", line);
free (line);
@}
@}
int
main (int c, char **v)
@{
fd_set fds;
int r;
/* Install the line handler. */
rl_callback_handler_install (prompt, cb_linehandler);
/* Enter a simple event loop. This waits until something is available
to read on readline's input stream (defaults to standard input) and
calls the builtin character read callback to read it. It does not
have to modify the user's terminal settings. */
running = 1;
while (running)
@{
FD_ZERO (&fds);
FD_SET (fileno (rl_instream), &fds);
r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
if (r < 0)
@{
perror ("rltest: select");
rl_callback_handler_remove ();
break;
@}
if (FD_ISSET (fileno (rl_instream), &fds))
rl_callback_read_char ();
@}
printf ("rltest: Event loop has exited\n");
return 0;
@}
@end example
@node Readline Signal Handling
@section Readline Signal Handling
@ -1365,6 +1509,7 @@ functions to do so manually.
Readline contains an internal signal handler that is installed for a
number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
@code{SIGHUP},
@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
When one of these signals is received, the signal handler
will reset the terminal attributes to those that were in effect before
@ -1397,19 +1542,28 @@ a signal handler, so Readline's internal signal state is not corrupted.
@deftypevar int rl_catch_signals
If this variable is non-zero, Readline will install signal handlers for
@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGALRM},
@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM},
@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
The default value of @code{rl_catch_signals} is 1.
@end deftypevar
@deftypevar int rl_catch_sigwinch
If this variable is non-zero, Readline will install a signal handler for
@code{SIGWINCH}.
If this variable is set to a non-zero value,
Readline will install a signal handler for @code{SIGWINCH}.
The default value of @code{rl_catch_sigwinch} is 1.
@end deftypevar
@deftypevar int rl_change_environment
If this variable is set to a non-zero value,
and Readline is handling @code{SIGWINCH}, Readline will modify the
@var{LINES} and @var{COLUMNS} environment variables upon receipt of a
@code{SIGWINCH}
The default value of @code{rl_change_environment} is 1.
@end deftypevar
If an application does not wish to have Readline catch any signals, or
to handle signals other than those Readline catches (@code{SIGHUP},
for example),
@ -1477,7 +1631,7 @@ The following functions install and remove Readline's signal handlers.
@deftypefun int rl_set_signals (void)
Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
@code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
@code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
@code{rl_catch_signals} and @code{rl_catch_sigwinch}.
@end deftypefun
@ -1611,7 +1765,7 @@ 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()}
Returns the appropriate value to pass to @code{rl_complete_internal()}
depending on whether @var{cfunc} was called twice in succession and
the values of the @code{show-all-if-ambiguous} and
@code{show-all-if-unmodified} variables.
@ -1728,29 +1882,45 @@ the directory portion of the pathname the user typed.
At the least, even if no other expansion is performed, this function should
remove any quote characters from the directory name, because its result will
be passed directly to @code{opendir()}.
The directory completion hook returns an integer that should be non-zero if
the function modifies its directory argument.
The function should not modify the directory argument if it returns 0.
@end deftypevar
@ignore
@deftypevar extern rl_icppfunc_t *rl_directory_rewrite_hook;
@deftypevar {rl_icppfunc_t *} rl_directory_rewrite_hook;
If non-zero, this is the address of a function to call when completing
a directory name. This function takes the address of the directory name
to be modified as an argument. Unlike @code{rl_directory_completion_hook},
it only modifies the directory name used in @code{opendir}, not what is
displayed when the possible completions are printed or inserted. It is
called before rl_directory_completion_hook.
At the least, even if no other expansion is performed, this function should
remove any quote characters from the directory name, because its result will
be passed directly to @code{opendir()}.
I'm not happy with how this works yet, so it's undocumented.
The directory rewrite hook returns an integer that should be non-zero if
the function modfies its directory argument.
The function should not modify the directory argument if it returns 0.
@end deftypevar
@deftypevar {rl_icppfunc_t *} rl_filename_stat_hook
If non-zero, this is the address of a function for the completer to
call before deciding which character to append to a completed name.
This function modifies its filename name argument, and the modified value
is passed to @code{stat()} to determine the file's type and characteristics.
This function does not need to remove quote characters from the filename.
The stat hook returns an integer that should be non-zero if
the function modfies its directory argument.
The function should not modify the directory argument if it returns 0.
@end deftypevar
@end ignore
@deftypevar {rl_dequote_func_t *} rl_filename_rewrite_hook
If non-zero, this is the address of a function called when reading
directory entries from the filesystem for completion and comparing
them to the partial word to be completed. The function should
perform any necesary application or system-specific conversion on
perform any necessary application or system-specific conversion on
the filename, such as converting between character sets or converting
from a filesystem format to a character input format.
The function takes two arguments: @var{fname}, the filename to be converted,

228
lib/readline/doc/rluser.texi
View file

@ -9,7 +9,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--2011 Free Software Foundation, Inc.
Copyright (C) 1988--2014 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
@ -72,6 +72,8 @@ Line editing can be enabled at any time using the @option{-o emacs} or
a specific command.
* Programmable Completion Builtins:: Builtin commands to specify how to
complete arguments for a particular command.
* A Programmable Completion Example:: An example shell function for
generating possible completions.
@end ifset
@end menu
@ -425,6 +427,14 @@ If set to @samp{on}, Readline attempts to bind the control characters
treated specially by the kernel's terminal driver to their Readline
equivalents.
@item colored-stats
@vindex colored-stats
If set to @samp{on}, Readline displays possible completions using different
colors to indicate their file type.
The color definitions are taken from the value of the @env{LS_COLORS}
environment variable.
The default is @samp{off}.
@item comment-begin
@vindex comment-begin
The string to insert at the beginning of the line when the
@ -521,8 +531,12 @@ or @code{next-history}. The default is @samp{off}.
@item history-size
@vindex history-size
Set the maximum number of history entries saved in the history list. If
set to zero, the number of entries in the history list is not limited.
Set the maximum number of history entries saved in the history list.
If set to zero, any existing history entries are deleted and no new entries
are saved.
If set to a value less than zero, the number of history entries is not
limited.
By default, the number of history entries is not limited.
@item horizontal-scroll-mode
@vindex horizontal-scroll-mode
@ -565,6 +579,22 @@ equivalent to @code{emacs-standard}. The default value is @code{emacs}.
The value of the @code{editing-mode} variable also affects the
default keymap.
@item keyseq-timeout
Specifies the duration Readline will wait for a character when reading an
ambiguous key sequence (one that can form a complete key sequence using
the input read so far, or can take additional input to complete a longer
key sequence).
If no input is received within the timeout, Readline will use the shorter
but complete key sequence.
Readline uses this value to determine whether or not input is
available on the current input source (@code{rl_instream} by default).
The value is specified in milliseconds, so a value of 1000 means that
Readline will wait one second for additional input.
If this variable is set to a value less than or equal to zero, or to a
non-numeric value, Readline will wait until another key is pressed to
decide which key sequence to complete.
The default value is @code{500}.
@item mark-directories
If set to @samp{on}, completed directory names have a slash
appended. The default is @samp{on}.
@ -640,6 +670,13 @@ a common prefix) cause the matches to be listed immediately instead
of ringing the bell.
The default value is @samp{off}.
@item show-mode-in-prompt
@vindex show-mode-in-prompt
If set to @samp{on}, add a character to the beginning of the prompt
indicating the editing mode: emacs (@samp{@@}), vi command (@samp{:}),
or vi insertion (@samp{+}).
The default value is @samp{off}.
@item skip-completed-text
@vindex skip-completed-text
If set to @samp{on}, this alters the default completion behavior when
@ -880,7 +917,7 @@ binding, variable assignment, and conditional syntax.
# You can re-read the inputrc file with C-x C-r.
# Lines beginning with '#' are comments.
#
# First, include any systemwide bindings and variable
# First, include any system-wide bindings and variable
# assignments from /etc/Inputrc
$include /etc/Inputrc
@ -1100,13 +1137,30 @@ for a string supplied by the user.
@item history-search-forward ()
Search forward through the history for the string of characters
between the start of the current line and the point.
The search string must match at the beginning of a history line.
This is a non-incremental search.
By default, this command is unbound.
@item history-search-backward ()
Search backward through the history for the string of characters
between the start of the current line and the point. This
is a non-incremental search. By default, this command is unbound.
between the start of the current line and the point.
The search string must match at the beginning of a history line.
This is a non-incremental search.
By default, this command is unbound.
@item history-substr-search-forward ()
Search forward through the history for the string of characters
between the start of the current line and the point.
The search string may match anywhere in a history line.
This is a non-incremental search.
By default, this command is unbound.
@item history-substr-search-backward ()
Search backward through the history for the string of characters
between the start of the current line and the point.
The search string may match anywhere in a history line.
This is a non-incremental search.
By default, this command is unbound.
@item yank-nth-arg (M-C-y)
Insert the first argument to the previous command (usually
@ -1137,11 +1191,17 @@ as if the @samp{!$} history expansion had been specified.
@subsection Commands For Changing Text
@ftable @code
@item @i{end-of-file} (usually C-d)
The character indicating end-of-file as set, for example, by
@code{stty}. If this character is read when there are no characters
on the line, and point is at the beginning of the line, Readline
interprets it as the end of input and returns @sc{eof}.
@item delete-char (C-d)
Delete the character at point. If point is at the
beginning of the line, there are no characters in the line, and
the last character typed was not bound to @code{delete-char}, then
return @sc{eof}.
Delete the character at point. If this function is bound to the
same character as the tty @sc{eof} character, as @kbd{C-d}
commonly is, see above for the effects.
@item backward-delete-char (Rubout)
Delete the character behind the cursor. A numeric argument means
@ -1435,6 +1495,10 @@ and save the definition.
Re-execute the last keyboard macro defined, by making the characters
in the macro appear as if typed at the keyboard.
@item print-last-kbd-macro ()
Print the last keboard macro defined in a format suitable for the
@var{inputrc} file.
@end ftable
@node Miscellaneous Commands
@ -1693,10 +1757,11 @@ When the command or function is invoked, the @env{COMP_LINE},
assigned values as described above (@pxref{Bash Variables}).
If a shell function is being invoked, the @env{COMP_WORDS} and
@env{COMP_CWORD} variables are also set.
When the function or command is invoked, the first argument is the
When the function or command is invoked, the first argument ($1) is the
name of the command whose arguments are being completed, the
second argument is the word being completed, and the third argument
is the word preceding the word being completed on the current command line.
second argument ($2) is the word being completed, and the third argument
($3) is the word preceding the word being completed on the current command
line.
No filtering of the generated completions against the word being completed
is performed; the function or command has complete freedom in generating
the matches.
@ -1706,7 +1771,7 @@ The function may use any of the shell facilities, including the
@code{compgen} and @code{compopt} builtins described below
(@pxref{Programmable Completion Builtins}), to generate the matches.
It must put the possible completions in the @env{COMPREPLY} array
variable.
variable, one per array element.
Next, any command specified with the @option{-C} option is invoked
in an environment equivalent to command substitution.
@ -1774,17 +1839,18 @@ completion function would load completions dynamically:
@example
_completion_loader()
@{
. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
@}
complete -D -F _completion_loader
complete -D -F _completion_loader -o bashdefault -o default
@end example
@node Programmable Completion Builtins
@section Programmable Completion Builtins
@cindex completion builtins
Two builtin commands are available to manipulate the programmable completion
facilities.
Three builtin commands are available to manipulate the programmable completion
facilities: one to specify how the arguments to a particular command are to
be completed, and two to modify the completion as it is happening.
@table @code
@item compgen
@ -1871,6 +1937,10 @@ quoting special characters, or suppressing trailing spaces).
This option is intended to be used with shell functions specified
with @option{-F}.
@item noquote
Tell Readline not to quote the completed words if they are filenames
(quoting filenames is the default).
@item nospace
Tell Readline not to append a space (the default) to words completed at
the end of the line.
@ -1970,6 +2040,10 @@ used as the possible completions.
@item -F @var{function}
The shell function @var{function} is executed in the current shell
environment.
When it is executed, $1 is the name of the command whose arguments are
being completed, $2 is the word being completed, and $3 is the word
preceding the word being completed, as described above
(@pxref{Programmable Completion}).
When it finishes, the possible completions are retrieved from the value
of the @env{COMPREPLY} array variable.
@ -2034,4 +2108,122 @@ specification exists, or an output error occurs.
@end table
@node A Programmable Completion Example
@section A Programmable Completion Example
The most common way to obtain additional completion functionality beyond
the default actions @code{complete} and @code{compgen} provide is to use
a shell function and bind it to a particular command using @code{complete -F}.
The following function provides completions for the @code{cd} builtin.
It is a reasonably good example of what shell functions must do when
used for completion. This function uses the word passsed as @code{$2}
to determine the directory name to complete. You can also use the
@code{COMP_WORDS} array variable; the current word is indexed by the
@code{COMP_CWORD} variable.
The function relies on the @code{complete} and @code{compgen} builtins
to do much of the work, adding only the things that the Bash @code{cd}
does beyond accepting basic directory names:
tilde expansion (@pxref{Tilde Expansion}),
searching directories in @var{$CDPATH}, which is described above
(@pxref{Bourne Shell Builtins}),
and basic support for the @code{cdable_vars} shell option
(@pxref{The Shopt Builtin}).
@code{_comp_cd} modifies the value of @var{IFS} so that it contains only
a newline to accommodate file names containing spaces and tabs --
@code{compgen} prints the possible completions it generates one per line.
Possible completions go into the @var{COMPREPLY} array variable, one
completion per array element. The programmable completion system retrieves
the completions from there when the function returns.
@example
# A completion function for the cd builtin
# based on the cd completion function from the bash_completion package
_comp_cd()
@{
local IFS=$' \t\n' # normalize IFS
local cur _skipdot _cdpath
local i j k
# Tilde expansion, with side effect of expanding tilde to full pathname
case "$2" in
\~*) eval cur="$2" ;;
*) cur=$2 ;;
esac
# no cdpath or absolute pathname -- straight directory completion
if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then
# compgen prints paths one per line; could also use while loop
IFS=$'\n'
COMPREPLY=( $(compgen -d -- "$cur") )
IFS=$' \t\n'
# CDPATH+directories in the current directory if not in CDPATH
else
IFS=$'\n'
_skipdot=false
# preprocess CDPATH to convert null directory names to .
_cdpath=$@{CDPATH/#:/.:@}
_cdpath=$@{_cdpath//::/:.:@}
_cdpath=$@{_cdpath/%:/:.@}
for i in $@{_cdpath//:/$'\n'@}; do
if [[ $i -ef . ]]; then _skipdot=true; fi
k="$@{#COMPREPLY[@@]@}"
for j in $( compgen -d -- "$i/$cur" ); do
COMPREPLY[k++]=$@{j#$i/@} # cut off directory
done
done
$_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") )
IFS=$' \t\n'
fi
# variable names if appropriate shell option set and no completions
if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then
COMPREPLY=( $(compgen -v -- "$cur") )
fi
return 0
@}
@end example
We install the completion function using the @option{-F} option to
@code{complete}:
@example
# Tell readline to quote appropriate and append slashes to directories;
# use the bash default completion for other arguments
complete -o filenames -o nospace -o bashdefault -F _comp_cd cd
@end example
@noindent
Since we'd like Bash and Readline to take care of some
of the other details for us, we use several other options to tell Bash
and Readline what to do. The @option{-o filenames} option tells Readline
that the possible completions should be treated as filenames, and quoted
appropriately. That option will also cause Readline to append a slash to
filenames it can determine are directories (which is why we might want to
extend @code{_comp_cd} to append a slash if we're using directories found
via @var{CDPATH}: Readline can't tell those completions are directories).
The @option{-o nospace} option tells Readline to not append a space
character to the directory name, in case we want to append to it.
The @option{-o bashdefault} option brings in the rest of the "Bash default"
completions -- possible completion that Bash adds to the default Readline
set. These include things like command name completion, variable completion
for words beginning with @samp{@{}, completions containing pathname
expansion patterns (@pxref{Filename Expansion}), and so on.
Once installed using @code{complete}, @code{_comp_cd} will be called every
time we attempt word completion for a @code{cd} command.
Many more examples -- an extensive collection of completions for most of
the common GNU, Unix, and Linux commands -- are available as part of the
bash_completion project. This is installed by default on many GNU/Linux
distributions. Originally written by Ian Macdonald, the project now lives
at @url{http://bash-completion.alioth.debian.org/}. There are ports for
other systems such as Solaris and Mac OS X.
An older version of the bash_completion package is distributed with bash
in the @file{examples/complete} subdirectory.
@end ifset

27
lib/readline/doc/rluserman.texi
View file

@ -2,33 +2,25 @@
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename rluserman.info
@settitle GNU Readline Library
@comment %**end of header (This is for running Texinfo on a region.)
@include version.texi
@comment %**end of header (This is for running Texinfo on a region.)
@copying
This manual describes the end user interface of the GNU Readline Library
(version @value{VERSION}, @value{UPDATED}), a library which aids in the
consistency of user interface across discrete programs which provide
a command line interface.
Copyright @copyright{} 1988--2011 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
Copyright @copyright{} 1988--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license is
included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: You are free to copy and modify
this GNU manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@ -49,12 +41,6 @@ developing GNU and promoting software freedom.''
@vskip 0pt plus 1filll
@insertcopying
@sp 1
Published by the Free Software Foundation @*
59 Temple Place, Suite 330, @*
Boston, MA 02111-1307 @*
USA @*
@end titlepage
@contents
@ -66,6 +52,7 @@ USA @*
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 which provide a command line interface.
The Readline home page is @url{http://www.gnu.org/software/readline/}.
@menu
* Command Line Editing:: GNU Readline User's Manual.

12
lib/readline/doc/version.texi
View file

@ -1,10 +1,10 @@
@ignore
Copyright (C) 1988-2011 Free Software Foundation, Inc.
Copyright (C) 1988-2014 Free Software Foundation, Inc.
@end ignore
@set EDITION 6.2
@set VERSION 6.2
@set UPDATED September 6 2010
@set UPDATED-MONTH September 2010
@set EDITION 6.3
@set VERSION 6.3
@set UPDATED 6 January 2014
@set UPDATED-MONTH January 2014
@set LASTCHANGE Mon Sep 6 22:07:10 EDT 2010
@set LASTCHANGE Mon Jan 6 16:26:51 EST 2014