If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline
treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when
performing case-insensitive filename matching and completion.
+The default value is @samp{off}.
@item completion-prefix-display-length
@vindex completion-prefix-display-length
@item emacs-mode-string
@vindex emacs-mode-string
-This string is displayed immediately before the last line of the primary
+If the @var{show-mode-in-prompt} variable is enabled,
+this string is displayed immediately before the last line of the primary
prompt when emacs editing mode is active. The value is expanded like a
key binding, so the standard set of meta- and control prefixes and
backslash escape sequences is available.
@item keymap
@vindex keymap
Sets Readline's idea of the current keymap for key binding commands.
-Acceptable @code{keymap} names are
+Built-in @code{keymap} names are
@code{emacs},
@code{emacs-standard},
@code{emacs-meta},
@code{vi-insert}.
@code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a
synonym); @code{emacs} is equivalent to @code{emacs-standard}.
+Applications may add additional names.
The default value is @code{emacs}.
The value of the @code{editing-mode} variable also affects the
default keymap.
@item show-mode-in-prompt
@vindex show-mode-in-prompt
-If set to @samp{on}, add a character to the beginning of the prompt
+If set to @samp{on}, add a string to the beginning of the prompt
indicating the editing mode: emacs, vi command, or vi insertion.
-The mode strings are user-settable.
+The mode strings are user-settable (e.g., @var{emacs-mode-string}).
The default value is @samp{off}.
@item skip-completed-text
@item vi-cmd-mode-string
@vindex vi-cmd-mode-string
-This string is displayed immediately before the last line of the primary
+If the @var{show-mode-in-prompt} variable is enabled,
+this string is displayed immediately before the last line of the primary
prompt when vi editing mode is active and in command mode.
The value is expanded like a
key binding, so the standard set of meta- and control prefixes and
@item vi-ins-mode-string
@vindex vi-ins-mode-string
-This string is displayed immediately before the last line of the primary
+If the @var{show-mode-in-prompt} variable is enabled,
+this string is displayed immediately before the last line of the primary
prompt when vi editing mode is active and in insertion mode.
The value is expanded like a
key binding, so the standard set of meta- and control prefixes and
Control-o: "> output"
@end example
-In the above example, @kbd{C-u} is bound to the function
+In the example above, @kbd{C-u} is bound to the function
@code{universal-argument},
@kbd{M-DEL} is bound to the function @code{backward-kill-word}, and
@kbd{C-o} is bound to run the macro
@item $if
The @code{$if} construct allows bindings to be made based on the
editing mode, the terminal being used, or the application using
-Readline. The text of the test extends to the end of the line;
-no characters are required to isolate it.
+Readline. The text of the test, after any comparison operator,
+extends to the end of the line;
+unless otherwise noted, no characters are required to isolate it.
@table @code
@item mode
allows @code{sun} to match both @code{sun} and @code{sun-cmd},
for instance.
+@item version
+The @code{version} test may be used to perform comparisons against
+specific Readline versions.
+The @code{version} expands to the current Readline version.
+The set of comparison operators includes
+@samp{=} (and @samp{==}), @samp{!=}, @samp{<=}, @samp{>=}, @samp{<},
+and @samp{>}.
+The version number supplied on the right side of the operator consists
+of a major version number, an optional decimal point, and an optional
+minor version (e.g., @samp{7.1}). If the minor version is omitted, it
+is assumed to be @samp{0}.
+The operator may be separated from the string @code{version} and
+from the version number argument by whitespace.
+The following example sets a variable if the Readline version being used
+is 7.0 or newer:
+@example
+$if version >= 7.0
+set show-mode-in-prompt on
+$endif
+@end example
+
@item application
The @var{application} construct is used to include
application-specific settings. Each program using the Readline
"\C-xq": "\eb\"\ef\""
$endif
@end example
+
+@item variable
+The @var{variable} construct provides simple equality tests for Readline
+variables and values.
+The permitted comparison operators are @samp{=}, @samp{==}, and @samp{!=}.
+The variable name must be separated from the comparison operator by
+whitespace; the operator may be separated from the value on the right hand
+side by whitespace.
+Both string and boolean variables may be tested. Boolean variables must be
+tested against the values @var{on} and @var{off}.
+The following example is equivalent to the @code{mode=emacs} test described
+above:
+@example
+$if editing-mode == emacs
+set show-mode-in-prompt on
+$endif
+@end example
@end table
@item $endif
Words are delimited by non-quoted shell metacharacters.
@end ifset
+@item previous-screen-line ()
+Attempt to move point to the same physical screen column on the previous
+physical screen line. This will not have the desired effect if the current
+Readline line does not take up more than one physical line or if point is not
+greater than the length of the prompt plus the screen width.
+
+@item next-screen-line ()
+Attempt to move point to the same physical screen column on the next
+physical screen line. This will not have the desired effect if the current
+Readline line does not take up more than one physical line or if the length
+of the current Readline line is not greater than the length of the prompt
+plus the screen width.
+
@item clear-screen (C-l)
Clear the screen and redraw the current line,
leaving the current line at the top of the screen.
This is a non-incremental search.
By default, this command is unbound.
-@item history-substr-search-forward ()
+@item history-substring-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 ()
+@item history-substring-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.
sequence sent by some terminals, and such a binding is assigned by default.
It allows Readline to insert the pasted text as a single unit without treating
each character as if it had been read from the keyboard. The characters
-are inserted as if each one was bound to @code{self-insert}) instead of
+are inserted as if each one was bound to @code{self-insert} instead of
executing any editing commands.
@item transpose-chars (C-t)
ring the terminal's bell (subject to the setting of
@code{bell-style}).
-@item do-uppercase-version (M-a, M-b, M-@var{x}, @dots{})
-If the metafied character @var{x} is lowercase, run the command
-that is bound to the corresponding uppercase character.
+@item do-lowercase-version (M-A, M-B, M-@var{x}, @dots{})
+If the metafied character @var{x} is upper case, run the command
+that is bound to the corresponding metafied lower case character.
+The behavior is undefined if @var{x} is already lower case.
@item prefix-meta (@key{ESC})
Metafy the next character typed. This is for keyboards
@item operate-and-get-next (C-o)
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.
+relative to the current line from the history for editing.
+A numeric argument, if supplied, specifies the history entry to use instead
+of the current line.
-@item edit-and-execute-command (C-xC-e)
+@item edit-and-execute-command (C-x C-e)
Invoke an editor on the current command line, and execute the result as shell
commands.
Bash attempts to invoke
find a compspec for the portion following the final slash.
If those searches do not result in a compspec, any compspec defined with
the @option{-D} option to @code{complete} is used as the default.
+If there is no default compspec, Bash attempts alias expansion
+on the command word as a final resort, and attempts to find a compspec
+for the command word from any successful expansion
Once a compspec has been found, it is used to generate the list of
matching words.
is considered.
The string is first split using the characters in the @env{IFS}
special variable as delimiters.
-Shell quoting is honored.
+Shell quoting is honored within the string, in order to provide a
+mechanism for the words to contain shell metacharacters or characters
+in the value of @env{IFS}.
Each word is then expanded using
brace expansion, tilde expansion, parameter and variable expansion,
command substitution, and arithmetic expansion,
@item complete
@btindex complete
@example
-@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DE] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
-[-F @var{function}] [-C @var{command}] [-X @var{filterpat}]
+@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DEI] [-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 [-DE] [@var{name} @dots{}]}
+@code{complete -pr [-DEI] [@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{-D} option indicates that the remaining options and actions should
+The @option{-D} option indicates that other supplied options and actions should
apply to the ``default'' command completion; that is, completion attempted
on a command for which no completion has previously been defined.
-The @option{-E} option indicates that the remaining options and actions should
+The @option{-E} option indicates that other supplied options and actions should
apply to ``empty'' command completion; that is, completion attempted on a
blank line.
+The @option{-I} option indicates that other supplied options and actions should
+apply to completion on the inital non-assignment word on the line, or after a
+command delimiter such as @samp{;} or @samp{|}, which is usually command
+name completion.
+If multiple options are supplied, the @option{-D} option takes precedence
+over @option{-E}, and both take precedence over @option{-I}.
+If any of @option{-D}, @option{-E}, or @option{-I} are supplied, any other
+@var{name} arguments are ignored; these completions only apply to the case
+specified by the option.
The process of applying these completion specifications when word completion
-is attempted is described above (@pxref{Programmable Completion}). The
-@option{-D} option takes precedence over @option{-E}.
+is attempted is described above (@pxref{Programmable Completion}).
Other options, if specified, have the following meanings.
The arguments to the @option{-G}, @option{-W}, and @option{-X} options
@item filenames
Tell Readline that the compspec generates filenames, so it can perform any
-filename-specific processing (like adding a slash to directory names
+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 compopt
@btindex compopt
@example
-@code{compopt} [-o @var{option}] [-DE] [+o @var{option}] [@var{name}]
+@code{compopt} [-o @var{option}] [-DEI] [+o @var{option}] [@var{name}]
@end example
Modify completion options for each @var{name} according to the
@var{option}s, or for the currently-executing completion if no @var{name}s
@var{name} or the current completion.
The possible values of @var{option} are those valid for the @code{complete}
builtin described above.
-The @option{-D} option indicates that the remaining options should
+The @option{-D} option indicates that other supplied options should
apply to the ``default'' command completion; that is, completion attempted
on a command for which no completion has previously been defined.
-The @option{-E} option indicates that the remaining options should
+The @option{-E} option indicates that other supplied options should
apply to ``empty'' command completion; that is, completion attempted on a
blank line.
+The @option{-I} option indicates that other supplied options should
+apply to completion on the inital non-assignment word on the line, or after a
+command delimiter such as @samp{;} or @samp{|}, which is usually command
+name completion.
-The @option{-D} option takes precedence over @option{-E}.
+If multiple options are supplied, the @option{-D} option takes precedence
+over @option{-E}, and both take precedence over @option{-I}
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
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}
+used for completion. This function uses the word passed 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.
local cur _skipdot _cdpath
local i j k
- # Tilde expansion, with side effect of expanding tilde to full pathname
+ # Tilde expansion, which also expands tilde to full pathname
case "$2" in
\~*) eval cur="$2" ;;
*) cur=$2 ;;