@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-2005 Free Software Foundation, Inc.
+Copyright (C) 1988--2016 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
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
@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.
@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.
+If set to @samp{on} (the default), Readline attempts to bind the control
+characters treated specially by the kernel's terminal driver to their
+Readline equivalents.
+
+@item blink-matching-paren
+@vindex blink-matching-paren
+If set to @samp{on}, Readline attempts to briefly move the cursor to an
+opening parenthesis when a closing parenthesis is inserted. The default
+is @samp{off}.
+
+@item colored-completion-prefix
+@vindex colored-completion-prefix
+If set to @samp{on}, when listing completions, Readline displays the
+common prefix of the set of possible completions using a different color.
+The color definitions are taken from the value of the @env{LS_COLORS}
+environment variable.
+The default is @samp{off}.
+
+@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
@code{insert-comment} command is executed. The default value
is @code{"#"}.
+@item completion-display-width
+@vindex completion-display-width
+The number of screen columns used to display possible matches
+when performing completion.
+The value is ignored if it is less than 0 or greater than the terminal
+screen width.
+A value of 0 will cause matches to be displayed one per line.
+The default value is -1.
+
@item completion-ignore-case
+@vindex completion-ignore-case
If set to @samp{on}, Readline performs filename matching and completion
in a case-insensitive fashion.
The default value is @samp{off}.
+@item completion-map-case
+@vindex completion-map-case
+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
+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
If set to @samp{on}, Readline will convert characters with the
eighth bit set to an @sc{ascii} key sequence by stripping the eighth
bit and prefixing an @key{ESC} character, converting them to a
-meta-prefixed key sequence. The default value is @samp{on}.
+meta-prefixed key sequence. The default value is @samp{on}, but
+will be set to @samp{off} if the locale is one that contains
+eight-bit characters.
@item disable-completion
@vindex disable-completion
Completion characters will be inserted into the line as if they had
been mapped to @code{self-insert}. The default is @samp{off}.
+@item echo-control-characters
+@vindex echo-control-characters
+When set to @samp{on}, on operating systems that indicate they support it,
+readline echoes a character corresponding to a signal generated from the
+keyboard. The default is @samp{on}.
+
@item editing-mode
@vindex editing-mode
The @code{editing-mode} variable controls which default set of
mode, where the keystrokes are most similar to Emacs. This variable can be
set to either @samp{emacs} or @samp{vi}.
+@item emacs-mode-string
+@vindex emacs-mode-string
+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.
+Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
+The default is @samp{@@}.
+
+@item enable-bracketed-paste
+@vindex enable-bracketed-paste
+When set to @samp{On}, Readline will configure the terminal in a way
+that will enable it to insert each paste into the editing buffer as a
+single string of characters, instead of treating each character as if
+it had been read from the keyboard. This can prevent pasted characters
+from being interpreted as editing commands. The default is @samp{off}.
+
@item enable-keypad
@vindex enable-keypad
When set to @samp{on}, Readline will try to enable the application
keypad when it is called. Some systems need this to enable the
arrow keys. The default is @samp{off}.
+@item enable-meta-key
+When set to @samp{on}, Readline will try to enable any meta modifier
+key the terminal claims to support when it is called. On many terminals,
+the meta key is used to send eight-bit characters.
+The default is @samp{on}.
+
@item expand-tilde
@vindex expand-tilde
If set to @samp{on}, tilde expansion is performed when Readline
@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}. 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, 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.
+If an attempt is made to set @var{history-size} to a non-numeric value,
+the maximum number of history entries will be set to 500.
+
@item horizontal-scroll-mode
@vindex horizontal-scroll-mode
This variable can be set to either @samp{on} or @samp{off}. Setting it
If set to @samp{on}, Readline will enable eight-bit input (it
will not clear the eighth bit in the characters it reads),
regardless of what the terminal claims it can support. The
-default value is @samp{off}. The name @code{meta-flag} is a
-synonym for this variable.
+default value is @samp{off}, but Readline will set it to @samp{on} if the
+locale contains eight-bit characters.
+The name @code{meta-flag} is a synonym for this variable.
@item isearch-terminators
@vindex isearch-terminators
@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-move},
@code{vi-command}, and
@code{vi-insert}.
-@code{vi} is equivalent to @code{vi-command}; @code{emacs} is
-equivalent to @code{emacs-standard}. The default value is @code{emacs}.
+@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 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}.
@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
+completion.
+If set to @samp{off}, the leading @samp{.} must be
supplied by the user in the filename to be completed.
This variable is @samp{on} by default.
+@item menu-complete-display-prefix
+@vindex menu-complete-display-prefix
+If set to @samp{on}, menu completion displays the common prefix of the
+list of possible completions (which may be empty) before cycling through
+the list. The default is @samp{off}.
+
@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}.
+sequence.
+The default is @samp{off}, but Readline will set it to @samp{on} if the
+locale contains eight-bit characters.
@item page-completions
@vindex page-completions
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
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 string to the beginning of the prompt
+indicating the editing mode: emacs, vi command, or vi insertion.
+The mode strings are user-settable (e.g., @var{emacs-mode-string}).
+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
+inserting a single match into the line. It's only active when
+performing completion in the middle of a word. If enabled, readline
+does not insert characters from the completion that match characters
+after point in the word being completed, so portions of the word
+following the cursor are not duplicated.
+For instance, if this is enabled, attempting completion when the cursor
+is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile}
+rather than @samp{Makefilefile}, assuming there is a single possible
+completion.
+The default value is @samp{off}.
+
+@item vi-cmd-mode-string
+@vindex vi-cmd-mode-string
+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
+backslash escape sequences is available.
+Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
+The default is @samp{(cmd)}.
+
+@item vi-ins-mode-string
+@vindex vi-ins-mode-string
+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
+backslash escape sequences is available.
+Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
+The default is @samp{(ins)}.
+
@item visible-stats
@vindex visible-stats
If set to @samp{on}, a character denoting a file's type
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}).
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
# 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
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 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,
@item forward-search-history (C-s)
Search forward starting at the current line and moving `down' through
-the the history as necessary. This is an incremental search.
+the history as necessary. This is an incremental search.
@item non-incremental-reverse-search-history (M-p)
Search backward starting at the current line and moving `up'
through the history as necessary using a non-incremental search
for a string supplied by the user.
+The search string may match anywhere in a history line.
@item non-incremental-forward-search-history (M-n)
Search forward starting at the current line and moving `down'
-through the the history as necessary using a non-incremental search
+through the history as necessary using a non-incremental search
for a string supplied by the user.
+The search string may match anywhere in a history line.
@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-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-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.
+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
@item yank-last-arg (M-. or M-_)
Insert last argument to the previous command (the last word of the
-previous history entry). With an
-argument, behave exactly like @code{yank-nth-arg}.
+previous history entry).
+With a numeric 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.
+list, inserting the last word (or the word specified by the argument to
+the first call) of each line in turn.
+Any numeric argument supplied to these successive calls determines
+the direction to move through the history. A negative argument switches
+the direction through the history (back or forward).
The history expansion facilities are used to extract the last argument,
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
@item self-insert (a, b, A, 1, !, @dots{})
Insert yourself.
+@item bracketed-paste-begin ()
+This function is intended to be bound to the "bracketed paste" escape
+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
+executing any editing commands.
+
@item transpose-chars (C-t)
Drag the character before the cursor forward over
the character at the cursor, moving the
Kill the text from point to the end of the line.
@item backward-kill-line (C-x Rubout)
-Kill backward to the beginning of the line.
+Kill backward from the cursor to the beginning of the current line.
@item unix-line-discard (C-u)
Kill backward from the cursor to the beginning of the current line.
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 shell-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.
If the command is followed by digits, executing @code{universal-argument}
again ends the numeric argument, but is otherwise ignored.
As a special case, if this command is immediately followed by a
-character that is neither a digit or minus sign, the argument count
+character that is neither a digit nor minus sign, the argument count
for the next command is multiplied by four.
The argument count is initially one, so executing this function the
first time makes the argument count four, a second time makes the
@item possible-completions (M-?)
List the possible completions of the text before point.
+When displaying completions, Readline sets the number of columns used
+for display to the value of @code{completion-display-width}, the value of
+the environment variable @env{COLUMNS}, or the screen width, in that order.
@item insert-completions (M-*)
Insert all completions of the text before point that would have
This command is intended to be bound to @key{TAB}, but is unbound
by default.
+@item menu-complete-backward ()
+Identical to @code{menu-complete}, but moves backward through the list
+of possible completions, as if @code{menu-complete} had been given a
+negative argument.
+
@item delete-char-or-list ()
Deletes the character under the cursor if not at the beginning or
end of the line (like @code{delete-char}).
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
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
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
of that character. A negative count searches for subsequent
occurrences.
+@item skip-csi-sequence ()
+Read enough characters to consume a multi-key sequence such as those
+defined for keys like Home and End. Such sequences begin with a
+Control Sequence Indicator (CSI), usually ESC-[. If this sequence is
+bound to "\e[", keys producing such sequences will have no effect
+unless explicitly bound to a readline command, instead of inserting
+stray characters into the editing buffer. This is unbound by default,
+but usually bound to ESC-[.
+
@item insert-comment (M-#)
Without a numeric argument, the value of the @code{comment-begin}
variable is inserted at the beginning of the current line.
@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
While the Readline library does not have a full set of @code{vi}
editing functions, it does contain enough to allow simple editing
of the line. The Readline @code{vi} mode behaves as specified in
-the @sc{posix} 1003.2 standard.
+the @sc{posix} standard.
@ifset BashFeatures
In order to switch interactively between @code{emacs} and @code{vi}
First, the command name is identified.
If a compspec has been defined for that command, the
compspec is used to generate the list of possible completions for the word.
+If the command word is the empty string (completion attempted at the
+beginning of an empty line), any compspec defined with
+the @option{-E} option to @code{complete} is used.
If the command word is a full pathname, a compspec for the full
pathname is searched for first.
If no compspec is found for the full pathname, an attempt is made to
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,
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
+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.
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.
+variable, one per array element.
Next, any command specified with the @option{-C} option is invoked
in an environment equivalent to command substitution.
Any completion that matches the pattern will be removed from the list.
A leading @samp{!} negates the pattern; in this case any completion
not matching the pattern will be removed.
+If the @code{nocasematch} shell option
+(see the description of @code{shopt} in @ref{The Shopt Builtin})
+is enabled, the match is performed without regard to the case
+of alphabetic characters.
Finally, any prefix and suffix specified with the @option{-P} and @option{-S}
options are added to each member of the completion list, and the result is
the value of the @var{mark-directories} Readline variable, regardless
of the setting of the @var{mark-symlinked-directories} Readline variable.
+There is some support for dynamically modifying completions. This is
+most useful when used in combination with a default completion specified
+with @option{-D}. It's possible for shell functions executed as completion
+handlers to indicate that completion should be retried by returning an
+exit status of 124. If a shell function returns 124, and changes
+the compspec associated with the command on which completion is being
+attempted (supplied as the first argument when the function is executed),
+programmable completion restarts from the beginning, with an
+attempt to find a new compspec for that command. This allows a set of
+completions to be built dynamically as completion is attempted, rather than
+being loaded all at once.
+
+For instance, assuming that there is a library of compspecs, each kept in a
+file corresponding to the name of the command, the following default
+completion function would load completions dynamically:
+
+@example
+_completion_loader()
+@{
+ . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
+@}
+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
@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}] [-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 [-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 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 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}).
@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 noquote
+Tell Readline not to quote the completed words if they are filenames
+(quoting filenames is the default).
+
+@item nosort
+Tell Readline not to sort the list of possible completions alphabetically.
@item nospace
Tell Readline not to append a space (the default) to words completed at
Names of all shell variables. May also be specified as @option{-v}.
@end table
-@item -G @var{globpat}
-The filename expansion pattern @var{globpat} is expanded to generate
-the possible completions.
-
-@item -W @var{wordlist}
-The @var{wordlist} is split using the characters in the
-@env{IFS} special variable as delimiters, and each resultant word
-is expanded.
-The possible completions are the members of the resultant list which
-match the word being completed.
-
@item -C @var{command}
@var{command} is executed in a subshell environment, and its output is
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.
-@item -X @var{filterpat}
-@var{filterpat} is a pattern as used for filename expansion.
-It is applied to the list of possible completions generated by the
-preceding options and arguments, and each completion matching
-@var{filterpat} is removed from the list.
-A leading @samp{!} in @var{filterpat} negates the pattern; in this
-case, any completion not matching @var{filterpat} is removed.
+@item -G @var{globpat}
+The filename expansion pattern @var{globpat} is expanded to generate
+the possible completions.
@item -P @var{prefix}
@var{prefix} is added at the beginning of each possible completion
@item -S @var{suffix}
@var{suffix} is appended to each possible completion
after all other options have been applied.
+
+@item -W @var{wordlist}
+The @var{wordlist} is split using the characters in the
+@env{IFS} special variable as delimiters, and each resultant word
+is expanded.
+The possible completions are the members of the resultant list which
+match the word being completed.
+
+@item -X @var{filterpat}
+@var{filterpat} is a pattern as used for filename expansion.
+It is applied to the list of possible completions generated by the
+preceding options and arguments, and each completion matching
+@var{filterpat} is removed from the list.
+A leading @samp{!} in @var{filterpat} negates the pattern; in this
+case, any completion not matching @var{filterpat} is removed.
@end table
The return value is true unless an invalid option is supplied, an option
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}] [-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
+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 @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 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.
+
+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
+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 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.
+
+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, which also expands 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
projects / deliverable / binutils-gdb.git / blobdiff