which contains both end-user and programmer documentation for the
GNU Readline Library.
-Copyright (C) 1988--2014 Free Software Foundation, Inc.
+Copyright (C) 1988--2011 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} (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}.
+If set to @samp{on}, Readline attempts to bind the control characters
+treated specially by the kernel's terminal driver to their Readline
+equivalents.
@item comment-begin
@vindex comment-begin
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
-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 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 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
@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.
+Set the maximum number of history entries saved in the history list. If
+set to zero, the number of entries in the history list is not limited.
@item horizontal-scroll-mode
@vindex horizontal-scroll-mode
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}.
of ringing the bell.
The default value is @samp{off}.
-@item show-mode-in-prompt
-@vindex show-mode-in-prompt
-If set to @samp{on}, add a character to the beginning of the prompt
-indicating the editing mode: emacs, vi command, or vi insertion.
-The mode strings are user-settable.
-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
-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
-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
# You can re-read the inputrc file with C-x C-r.
# Lines beginning with '#' are comments.
#
-# First, include any system-wide bindings and variable
+# First, include any systemwide bindings and variable
# assignments from /etc/Inputrc
$include /etc/Inputrc
@item forward-search-history (C-s)
Search forward starting at the current line and moving `down' through
-the history as necessary. This is an incremental search.
+the 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 history as necessary using a non-incremental search
+through the 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.
-The search string must match at the beginning of a history line.
-This is a non-incremental search.
-By default, this command is unbound.
-
-@item history-substr-search-forward ()
-Search forward through the history for the string of characters
-between the start of the current line and the point.
-The search string may match anywhere in a history line.
-This is a non-incremental search.
-By default, this command is unbound.
-
-@item history-substr-search-backward ()
-Search backward through the history for the string of characters
-between the start of the current line and the point.
-The search string may match anywhere in a history line.
-This is a non-incremental search.
-By default, this command is unbound.
+between the start of the current line and the point. 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 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.
+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}.
@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 from the cursor to the beginning of the current line.
+Kill backward to the beginning of the 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 nor minus sign, the argument count
+character that is neither a digit or 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
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 ($1) is the
+When the function or command is invoked, the first argument is the
name of the command whose arguments are being completed, the
-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.
+second argument is the word being completed, and the third argument
+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, one per array element.
+variable.
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 -o bashdefault -o default
+complete -D -F _completion_loader
@end example
@node Programmable Completion Builtins
@section Programmable Completion Builtins
@cindex completion builtins
-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.
+Two builtin commands are available to manipulate the programmable completion
+facilities.
@table @code
@item compgen
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.
@end table
-@node A Programmable Completion Example
-@section A Programmable Completion Example
-
-The most common way to obtain additional completion functionality beyond
-the default actions @code{complete} and @code{compgen} provide is to use
-a shell function and bind it to a particular command using @code{complete -F}.
-
-The following function provides completions for the @code{cd} builtin.
-It is a reasonably good example of what shell functions must do when
-used for completion. This function uses the word passsed as @code{$2}
-to determine the directory name to complete. You can also use the
-@code{COMP_WORDS} array variable; the current word is indexed by the
-@code{COMP_CWORD} variable.
-
-The function relies on the @code{complete} and @code{compgen} builtins
-to do much of the work, adding only the things that the Bash @code{cd}
-does beyond accepting basic directory names:
-tilde expansion (@pxref{Tilde Expansion}),
-searching directories in @var{$CDPATH}, which is described above
-(@pxref{Bourne Shell Builtins}),
-and basic support for the @code{cdable_vars} shell option
-(@pxref{The Shopt Builtin}).
-@code{_comp_cd} modifies the value of @var{IFS} so that it contains only
-a newline to accommodate file names containing spaces and tabs --
-@code{compgen} prints the possible completions it generates one per line.
-
-Possible completions go into the @var{COMPREPLY} array variable, one
-completion per array element. The programmable completion system retrieves
-the completions from there when the function returns.
-
-@example
-# A completion function for the cd builtin
-# based on the cd completion function from the bash_completion package
-_comp_cd()
-@{
- local IFS=$' \t\n' # normalize IFS
- local cur _skipdot _cdpath
- local i j k
-
- # Tilde expansion, with side effect of expanding tilde to full pathname
- case "$2" in
- \~*) eval cur="$2" ;;
- *) cur=$2 ;;
- esac
-
- # no cdpath or absolute pathname -- straight directory completion
- if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then
- # compgen prints paths one per line; could also use while loop
- IFS=$'\n'
- COMPREPLY=( $(compgen -d -- "$cur") )
- IFS=$' \t\n'
- # CDPATH+directories in the current directory if not in CDPATH
- else
- IFS=$'\n'
- _skipdot=false
- # preprocess CDPATH to convert null directory names to .
- _cdpath=$@{CDPATH/#:/.:@}
- _cdpath=$@{_cdpath//::/:.:@}
- _cdpath=$@{_cdpath/%:/:.@}
- for i in $@{_cdpath//:/$'\n'@}; do
- if [[ $i -ef . ]]; then _skipdot=true; fi
- k="$@{#COMPREPLY[@@]@}"
- for j in $( compgen -d -- "$i/$cur" ); do
- COMPREPLY[k++]=$@{j#$i/@} # cut off directory
- done
- done
- $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") )
- IFS=$' \t\n'
- fi
-
- # variable names if appropriate shell option set and no completions
- if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then
- COMPREPLY=( $(compgen -v -- "$cur") )
- fi
-
- return 0
-@}
-@end example
-
-We install the completion function using the @option{-F} option to
-@code{complete}:
-
-@example
-# Tell readline to quote appropriate and append slashes to directories;
-# use the bash default completion for other arguments
-complete -o filenames -o nospace -o bashdefault -F _comp_cd cd
-@end example
-
-@noindent
-Since we'd like Bash and Readline to take care of some
-of the other details for us, we use several other options to tell Bash
-and Readline what to do. The @option{-o filenames} option tells Readline
-that the possible completions should be treated as filenames, and quoted
-appropriately. That option will also cause Readline to append a slash to
-filenames it can determine are directories (which is why we might want to
-extend @code{_comp_cd} to append a slash if we're using directories found
-via @var{CDPATH}: Readline can't tell those completions are directories).
-The @option{-o nospace} option tells Readline to not append a space
-character to the directory name, in case we want to append to it.
-The @option{-o bashdefault} option brings in the rest of the "Bash default"
-completions -- possible completion that Bash adds to the default Readline
-set. These include things like command name completion, variable completion
-for words beginning with @samp{@{}, completions containing pathname
-expansion patterns (@pxref{Filename Expansion}), and so on.
-
-Once installed using @code{complete}, @code{_comp_cd} will be called every
-time we attempt word completion for a @code{cd} command.
-
-Many more examples -- an extensive collection of completions for most of
-the common GNU, Unix, and Linux commands -- are available as part of the
-bash_completion project. This is installed by default on many GNU/Linux
-distributions. Originally written by Ian Macdonald, the project now lives
-at @url{http://bash-completion.alioth.debian.org/}. There are ports for
-other systems such as Solaris and Mac OS X.
-
-An older version of the bash_completion package is distributed with bash
-in the @file{examples/complete} subdirectory.
-
@end ifset
projects / deliverable / binutils-gdb.git / blobdiff