which contains both end-user and programmer documentation for the
GNU Readline Library.
-Copyright (C) 1988--2011 Free Software Foundation, Inc.
+Copyright (C) 1988--2016 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
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
@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
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
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 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 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
@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.
+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
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 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
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
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
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
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.
@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
@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.
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
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
@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,
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.
@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
@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
@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 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
the end of the line.
@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 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
@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