@comment %**start of header (This is for running Texinfo on a region.)
@setfilename rluser.info
@comment %**end of header (This is for running Texinfo on a region.)
-@setchapternewpage odd
@ignore
This file documents the end user interface to the GNU command line
which contains both end-user and programmer documentation for the
GNU Readline Library.
-Copyright (C) 1988-2004 Free Software Foundation, Inc.
+Copyright (C) 1988--2009 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
@ifset BashFeatures
Command line editing is provided by the Readline library, which is
used by several different programs, including Bash.
+Command line editing is enabled by default when using an interactive shell,
+unless the @option{--noediting} option is supplied at shell invocation.
+Line editing is also used when using the @option{-e} option to the
+@code{read} builtin command (@pxref{Bash Builtins}).
+By default, the line editing commands are similar to those of emacs.
+A vi-style line editing interface is also available.
+Line editing can be enabled at any time using the @option{-o emacs} or
+@option{-o vi} options to the @code{set} builtin command
+(@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or
+@option{+o vi} options to @code{set}.
@end ifset
@menu
@ifclear BashFeatures
file is taken from the value of the environment variable @env{INPUTRC}. If
@end ifclear
-that variable is unset, the default is @file{~/.inputrc}.
+that variable is unset, the default is @file{~/.inputrc}. If that
+file does not exist or cannot be read, the ultimate default is
+@file{/etc/inputrc}.
When a program which uses the Readline library starts up, the
init file is read, and the key bindings are set.
@end example
Variable names and values, where appropriate, are recognized without regard
-to case.
+to case. Unrecognized variable names are ignored.
+
+Boolean variables (those that can be set to on or off) are set to on if
+the value is null or empty, @var{on} (case-insensitive), or 1. Any other
+value results in the variable being set to off.
@ifset BashFeatures
The @w{@code{bind -V}} command lists the current Readline variable names
If set to @samp{audible} (the default), Readline attempts to ring
the terminal's bell.
+@item bind-tty-special-chars
+@vindex bind-tty-special-chars
+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 comment-begin
@vindex comment-begin
The string to insert at the beginning of the line when the
in a case-insensitive fashion.
The default value is @samp{off}.
+@item completion-prefix-display-length
+@vindex completion-prefix-display-length
+The length in characters of the common prefix of a list of possible
+completions that is displayed without modification. When set to a
+value greater than zero, common prefixes longer than this value are
+replaced with an ellipsis when displaying possible completions.
+
@item completion-query-items
@vindex completion-query-items
The number of possible completions that determines when the user is
Readline will ask the user whether or not he wishes to view
them; otherwise, they are simply listed.
This variable must be set to an integer value greater than or equal to 0.
+A negative value means Readline should never ask.
The default limit is @code{100}.
@item convert-meta
If set to @samp{on}, tilde expansion is performed when Readline
attempts word completion. The default is @samp{off}.
+@item history-preserve-point
@vindex history-preserve-point
-If set to @samp{on}, the history code attempts to place point at the
+If set to @samp{on}, the history code attempts to place the point (the
+current cursor position) at the
same location on each history line retrieved with @code{previous-history}
-or @code{next-history}.
+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.
@item horizontal-scroll-mode
@vindex horizontal-scroll-mode
sorted horizontally in alphabetical order, rather than down the screen.
The default is @samp{off}.
+@item revert-all-at-newline
+@vindex revert-all-at-newline
+If set to @samp{on}, Readline will undo all changes to history lines
+before returning when @code{accept-line} is executed. By default,
+history lines may be modified and retain individual undo lists across
+calls to @code{readline}. The default is @samp{off}.
+
@item show-all-if-ambiguous
@vindex show-all-if-ambiguous
This alters the default behavior of the completion functions. If
Once you know the name of the command, simply place on a line
in the init file the name of the key
you wish to bind the command to, a colon, and then the name of the
-command. The name of the key
-can be expressed in different ways, depending on what you find most
-comfortable.
+command.
+There can be no space between the key name and the colon -- that will be
+interpreted as part of the key name.
+The name of the key can be expressed in different ways, depending on
+what you find most comfortable.
In addition to command names, readline allows keys to be bound
to a string that is inserted when the key is pressed (a @var{macro}).
Move back a character.
@item forward-word (M-f)
-Move forward to the end of the next word. Words are composed of
-letters and digits.
+Move forward to the end of the next word.
+Words are composed of letters and digits.
@item backward-word (M-b)
-Move back to the start of the current or previous word. Words are
-composed of letters and digits.
+Move back to the start of the current or previous word.
+Words are composed of letters and digits.
+
+@ifset BashFeatures
+@item shell-forward-word ()
+Move forward to the end of the next word.
+Words are delimited by non-quoted shell metacharacters.
+
+@item shell-backward-word ()
+Move back to the start of the current or previous word.
+Words are delimited by non-quoted shell metacharacters.
+@end ifset
@item clear-screen (C-l)
Clear the screen and redraw the current line,
insert the @var{n}th word from the previous command (the words
in the previous command begin with word 0). A negative argument
inserts the @var{n}th word from the end of the previous command.
+Once the argument @var{n} is computed, the argument is extracted
+as if the @samp{!@var{n}} history expansion had been specified.
@item yank-last-arg (M-. or M-_)
Insert last argument to the previous command (the last word of the
argument, behave exactly like @code{yank-nth-arg}.
Successive calls to @code{yank-last-arg} move back through the history
list, inserting the last argument of each line in turn.
+The history expansion facilities are used to extract the last argument,
+as if the @samp{!$} history expansion had been specified.
@end ftable
Kill the word behind point.
Word boundaries are the same as @code{backward-word}.
+@ifset BashFeatures
+@item shell-kill-word ()
+Kill from point to the end of the current word, or if between
+words, to the end of the next word.
+Word boundaries are the same as @code{shell-forward-word}.
+
+@item backward-kill-word ()
+Kill the word behind point.
+Word boundaries are the same as @code{shell-backward-word}.
+@end ifset
+
@item unix-word-rubout (C-w)
Kill the word behind point, using white space as a word boundary.
The killed text is saved on the kill-ring.
the text against lines from the history list for possible
completion matches.
+@item dabbrev-expand ()
+Attempt menu completion on the text before point, comparing
+the text against lines from the history list for possible
+completion matches.
+
@item complete-into-braces (M-@{)
Perform filename completion and insert the list of possible completions
enclosed within braces so the list is available to the shell
Shell quoting is honored.
Each word is then expanded using
brace expansion, tilde expansion, parameter and variable expansion,
-command substitution, arithmetic expansion, and pathname expansion,
+command substitution, and arithmetic expansion,
as described above (@pxref{Shell Expansions}).
The results are split using the rules described above
(@pxref{Word Splitting}).
After these matches have been generated, any shell function or command
specified with the @option{-F} and @option{-C} options is invoked.
-When the command or function is invoked, the @env{COMP_LINE} and
-@env{COMP_POINT} variables are assigned values as described above
-(@pxref{Bash Variables}).
+When the command or function is invoked, the @env{COMP_LINE},
+@env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are
+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
Any function specified with @option{-F} is invoked first.
The function may use any of the shell facilities, including the
-@code{compgen} builtin described below
+@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.
@item complete
@btindex complete
@example
-@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{}]}
+@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-E] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
+[-F @var{function}] [-C @var{command}] [-X @var{filterpat}]
+[-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]}
+@code{complete -pr [-E] [@var{name} @dots{}]}
@end example
Specify how arguments to each @var{name} should be completed.
The @option{-r} option removes a completion specification for
each @var{name}, or, if no @var{name}s are supplied, all
completion specifications.
+The @option{-E} option indicates that the remaining options and actions should
+apply to ``empty'' command completion; that is, completion attempted on a
+blank line.
The process of applying these completion specifications when word completion
is attempted is described above (@pxref{Programmable Completion}).
@item filenames
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}.
+filename-specific processing (like adding a slash to directory names
+quoting special characters, 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.
+
+@item plusdirs
+After any matches defined by the compspec are generated,
+directory name completion is attempted and any
+matches are added to the results of the other actions.
+
@end table
@item -A @var{action}
a @var{name} for which no specification exists, or
an error occurs adding a completion specification.
+@item compopt
+@btindex compopt
+@example
+@code{compopt} [-o @var{option}] [+o @var{option}] [@var{name}]
+@end example
+Modify completion options for each @var{name} according to the
+@var{option}s, or for the currently-execution completion if no @var{name}s
+are supplied.
+If no @var{option}s are given, display the completion options for each
+@var{name} or the current completion.
+The possible values of @var{option} are those valid for the @code{complete}
+builtin described above.
+
+The return value is true unless an invalid option is supplied, an attempt
+is made to modify the options for a @var{name} for which no completion
+specification exists, or an output error occurs.
+
@end table
+
@end ifset