which contains both end-user and programmer documentation for the GNU
Readline Library.
-Copyright (C) 1988 Free Software Foundation, Inc.
+Copyright (C) 1988, 1991, 1993, 1996 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
@node Command Line Editing
@chapter Command Line Editing
-This chapter describes the basic features of the GNU
+This chapter describes the basic features of the @sc{GNU}
command line editing interface.
@menu
keystrokes.
The text @key{C-k} is read as `Control-K' and describes the character
-produced when the Control key is depressed and the @key{k} key is struck.
+produced when the @key{k} key is pressed while the Control key
+is depressed.
The text @key{M-k} is read as `Meta-K' and describes the character
produced when the meta key (if you have one) is depressed, and the @key{k}
-key is struck. If you do not have a meta key, the identical keystroke
+key is pressed. If you do not have a meta key, the identical keystroke
can be generated by typing @key{ESC} @i{first}, and then typing @key{k}.
Either process is known as @dfn{metafying} the @key{k} key.
In addition, several keys have their own names. Specifically,
@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all
stand for themselves when seen in this text, or in an init file
-(@pxref{Readline Init File}, for more info).
+(@pxref{Readline Init File}).
@node Readline Interaction
@section Readline Interaction
* Readline Movement Commands:: Moving about the input line.
* Readline Killing Commands:: How to delete text, and how to get it back!
* Readline Arguments:: Giving numeric arguments to commands.
-@end menu
+* Searching:: Searching through previous lines.
+ @end menu
@node Readline Bare Essentials
@subsection Readline Bare Essentials
+@cindex notation, readline
+@cindex command editing
+@cindex editing command lines
In order to enter characters into the line, simply type them. The typed
character appears where the cursor was, and then the cursor moves one
@node Readline Killing Commands
@subsection Readline Killing Commands
-@cindex Killing text
-@cindex Yanking text
+@cindex killing text
+@cindex yanking text
@dfn{Killing} text means to delete the text from the line, but to save
it away for later use, usually by @dfn{yanking} (re-inserting)
ring is not line specific; the text that you killed on a previously
typed line is available to be yanked back later, when you are typing
another line.
-@cindex Kill ring
+@cindex kill ring
Here is the list of commands for killing text.
argument that is significant. If you pass a negative argument to a
command which normally acts in a forward direction, that command will
act in a backward direction. For example, to kill text back to the
-start of the line, you might type @key{M--} @key{C-k}.
+start of the line, you might type @w{@kbd{M-- C-k}}.
The general way to pass numeric arguments to a command is to type meta
digits before the command. If the first `digit' you type is a minus
sign (@key{-}), then the sign of the argument will be negative. Once
you have typed one meta digit to get the argument started, you can type
the remainder of the digits, and then the command. For example, to give
-the @key{C-d} command an argument of 10, you could type @key{M-1 0 C-d}.
+the @key{C-d} command an argument of 10, you could type @samp{M-1 0 C-d}.
+
+@node Searching
+@subsection Searching for Commands in the History
+Readline provides commands for searching through the command history
+@ifset BashFeatures
+(@pxref{Bash History Facilities})
+@end ifset
+for lines containing a specified string.
+There are two search modes: @var{incremental} and @var{non-incremental}.
+
+Incremental searches begin before the user has finished typing the
+search string.
+As each character of the search string is typed, readline displays
+the next entry from the history matching the string typed so far.
+An incremental search requires only as many characters as needed to
+find the desired history entry.
+The Escape character is used to terminate an incremental search.
+Control-J will also terminate the search.
+Control-G will abort an incremental search and restore the original
+line.
+When the search is terminated, the history entry containing the
+search string becomes the current line.
+To find other matching entries in the history list, type Control-S or
+Control-R as appropriate.
+This will search backward or forward in the history for the next
+entry matching the search string typed so far.
+Any other key sequence bound to a readline command will terminate
+the search and execute that command.
+For instance, a @code{newline} will terminate the search and accept
+the line, thereby executing the command from the history list.
+
+Non-incremental searches read the entire search string before starting
+to search for matching history lines. The search string may be
+typed by the user or part of the contents of the current line.
@node Readline Init File
@section Readline Init File
+@cindex initialization file, readline
-Although the Readline library comes with a set of Emacs-like
+Although the Readline library comes with a set of @code{emacs}-like
keybindings installed by default,
it is possible that you would like to use a different set
of keybindings. You can customize programs that use Readline by putting
-commands in an @dfn{init} file in your home directory. The name of this
+commands in an @dfn{inputrc} file in your home directory. The name of this
@ifset BashFeatures
file is taken from the value of the shell variable @code{INPUTRC}. If
@end ifset
incorporating any changes that you might have made to it.
@menu
-* Readline Init Syntax:: Syntax for the commands in the inputrc file.
+* Readline Init File Syntax:: Syntax for the commands in the inputrc file.
+
* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
+
+* Sample Init File:: An example inputrc file.
@end menu
-@node Readline Init Syntax
-@subsection Readline Init Syntax
+@node Readline Init File Syntax
+@subsection Readline Init File Syntax
There are only a few basic constructs allowed in the
Readline init file. Blank lines are ignored.
-Lines beginning with a @key{#} are comments.
-Lines beginning with a @key{$} indicate conditional
+Lines beginning with a @samp{#} are comments.
+Lines beginning with a @samp{$} indicate conditional
constructs (@pxref{Conditional Init Constructs}). Other lines
denote variable settings and key bindings.
@table @code
-@item editing-mode
-@vindex editing-mode
-The @code{editing-mode} variable controls which editing mode you are
-using. By default, Readline starts up in Emacs editing mode, where
-the keystrokes are most similar to Emacs. This variable can be
-set to either @code{emacs} or @code{vi}.
-
-@item horizontal-scroll-mode
-@vindex horizontal-scroll-mode
-This variable can be set to either @code{On} or @code{Off}. Setting it
-to @code{On} means that the text of the lines that you edit will scroll
-horizontally on a single screen line when they are longer than the width
-of the screen, instead of wrapping onto a new screen line. By default,
-this variable is set to @code{Off}.
-
-@item mark-modified-lines
-@vindex mark-modified-lines
-This variable, when set to @code{On}, says to display an asterisk
-(@samp{*}) at the start of history lines which have been modified.
-This variable is @code{off} by default.
-
@item bell-style
@vindex bell-style
Controls what happens when Readline wants to ring the terminal bell.
-If set to @code{none}, Readline never rings the bell. If set to
-@code{visible}, Readline uses a visible bell if one is available.
-If set to @code{audible} (the default), Readline attempts to ring
+If set to @samp{none}, Readline never rings the bell. If set to
+@samp{visible}, Readline uses a visible bell if one is available.
+If set to @samp{audible} (the default), Readline attempts to ring
the terminal's bell.
@item comment-begin
@vindex comment-begin
The string to insert at the beginning of the line when the
-@code{vi-comment} command is executed. The default value
+@code{insert-comment} command is executed. The default value
is @code{"#"}.
-@item meta-flag
-@vindex meta-flag
-If set to @code{on}, Readline will enable eight-bit input (it
-will not strip the eighth bit from the characters it reads),
-regardless of what the terminal claims it can support. The
-default value is @code{off}.
-
-@item convert-meta
-@vindex convert-meta
-If set to @code{on}, Readline will convert characters with the
-eigth bit set to an ASCII key sequence by stripping the eigth
-bit and prepending an @key{ESC} character, converting them to a
-meta-prefixed key sequence. The default value is @code{on}.
-
-@item output-meta
-@vindex output-meta
-If set to @code{on}, Readline will display characters with the
-eighth bit set directly rather than as a meta-prefixed escape
-sequence. The default is @code{off}.
-
@item completion-query-items
@vindex completion-query-items
The number of possible completions that determines when the user is
them; otherwise, they are simply listed. The default limit is
@code{100}.
+@item convert-meta
+@vindex convert-meta
+If set to @samp{on}, Readline will convert characters with the
+eigth bit set to an ASCII key sequence by stripping the eigth
+bit and prepending an @key{ESC} character, converting them to a
+meta-prefixed key sequence. The default value is @samp{on}.
+
+@item disable-completion
+@vindex disable-completion
+If set to @samp{On}, readline will inhibit word 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 editing-mode
+@vindex editing-mode
+The @code{editing-mode} variable controls which editing mode you are
+using. By default, Readline starts up in Emacs editing mode, where
+the keystrokes are most similar to Emacs. This variable can be
+set to either @samp{emacs} or @samp{vi}.
+
+@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 expand-tilde
+@vindex expand-tilde
+If set to @samp{on}, tilde expansion is performed when Readline
+attempts word completion. The default is @samp{off}.
+
+@item horizontal-scroll-mode
+@vindex horizontal-scroll-mode
+This variable can be set to either @samp{on} or @samp{off}. Setting it
+to @samp{on} means that the text of the lines that you edit will scroll
+horizontally on a single screen line when they are longer than the width
+of the screen, instead of wrapping onto a new screen line. By default,
+this variable is set to @samp{off}.
+
@item keymap
@vindex keymap
Sets Readline's idea of the current keymap for key binding commands.
@code{emacs-meta},
@code{emacs-ctlx},
@code{vi},
-@code{vi-move},
@code{vi-command}, and
@code{vi-insert}.
@code{vi} is equivalent to @code{vi-command}; @code{emacs} is
The value of the @code{editing-mode} variable also affects the
default keymap.
+@item mark-directories
+If set to @samp{on}, completed directory names have a slash
+appended. The default is @samp{on}.
+
+@item mark-modified-lines
+@vindex mark-modified-lines
+This variable, when set to @samp{on}, says to display an asterisk
+(@samp{*}) at the start of history lines which have been modified.
+This variable is @samp{off} by default.
+
+@item input-meta
+@vindex input-meta
+@vindex meta-flag
+If set to @samp{on}, Readline will enable eight-bit input (it
+will not strip the eighth bit from 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.
+
+@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}.
+
@item show-all-if-ambiguous
@vindex show-all-if-ambiguous
This alters the default behavior of the completion functions. If
-set to @code{on},
+set to @samp{on},
words which have more than one possible completion cause the
matches to be listed immediately instead of ringing the bell.
-The default value is @code{off}.
+The default value is @samp{off}.
-@item expand-tilde
-@vindex expand-tilde
-If set to @code{on}, tilde expansion is performed when Readline
-attempts word completion. The default is @code{off}.
+@item visible-stats
+@vindex visible-stats
+If set to @samp{on}, a character denoting a file's type
+is appended to the filename when listing possible
+completions. The default is @samp{off}.
@end table
@example
Control-u: universal-argument
Meta-Rubout: backward-kill-word
-Control-o: ">&output"
+Control-o: "> output"
@end example
In the above example, @samp{C-u} is bound to the function
@code{universal-argument}, and @samp{C-o} is bound to run the macro
expressed on the right hand side (that is, to insert the text
-@samp{>&output} into the line).
+@samp{> output} into the line).
@item @w{"@var{keyseq}": @var{function-name} or @var{macro}}
@var{keyseq} differs from @var{keyname} above in that strings
When entering the text of a macro, single or double quotes should
be used to indicate a macro definition. Unquoted text
is assumed to be a function name. Backslash
-will quote any character in the macro text, including @key{"}
-and @key{'}.
-For example, the following binding will make @kbd{C-x \}
-insert a single @key{\} into the line:
+will quote any character in the macro text, including @samp{"}
+and @samp{'}.
+For example, the following binding will make @samp{C-x \}
+insert a single @samp{\} into the line:
@example
"\C-x\\": "\\"
@end example
bindings and variable settings to be performed as the result
of tests. There are three parser directives used.
-@ftable @code
+@table @code
@item $if
The @code{$if} construct allows bindings to be made based on the
editing mode, the terminal being used, or the application using
terminal's function keys. The word on the right side of the
@samp{=} is tested against the full name of the terminal and the
portion of the terminal name before the first @samp{-}. This
-allows @var{sun} to match both @var{sun} and @var{sun-cmd},
+allows @code{sun} to match both @code{sun} and @code{sun-cmd},
for instance.
@item application
a specific program. For instance, the following command adds a
key sequence that quotes the current or previous word in Bash:
@example
-$if bash
+$if Bash
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
$endif
@item $else
Commands in this branch of the @code{$if} directive are executed if
the test fails.
-@end ftable
+@end table
+
+@node Sample Init File
+@subsection Sample Init File
+
+Here is an example of an inputrc file. This illustrates key
+binding, variable assignment, and conditional syntax.
+
+@example
+@page
+# This file controls the behaviour of line input editing for
+# programs that use the Gnu Readline library. Existing programs
+# include FTP, Bash, and Gdb.
+#
+# You can re-read the inputrc file with C-x C-r.
+# Lines beginning with '#' are comments.
+#
+# Set various bindings for emacs mode.
+
+set editing-mode emacs
+
+$if mode=emacs
+
+Meta-Control-h: backward-kill-word Text after the function name is ignored
+
+#
+# Arrow keys in keypad mode
+#
+#"\M-OD" backward-char
+#"\M-OC" forward-char
+#"\M-OA" previous-history
+#"\M-OB" next-history
+#
+# Arrow keys in ANSI mode
+#
+"\M-[D" backward-char
+"\M-[C" forward-char
+"\M-[A" previous-history
+"\M-[B" next-history
+#
+# Arrow keys in 8 bit keypad mode
+#
+#"\M-\C-OD" backward-char
+#"\M-\C-OC" forward-char
+#"\M-\C-OA" previous-history
+#"\M-\C-OB" next-history
+#
+# Arrow keys in 8 bit ANSI mode
+#
+#"\M-\C-[D" backward-char
+#"\M-\C-[C" forward-char
+#"\M-\C-[A" previous-history
+#"\M-\C-[B" next-history
+
+C-q: quoted-insert
+
+$endif
+
+# An old-style binding. This happens to be the default.
+TAB: complete
+
+# Macros that are convenient for shell interaction
+$if Bash
+# edit the path
+"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f"
+# prepare to type a quoted word -- insert open and close double quotes
+# and move to just after the open quote
+"\C-x\"": "\"\"\C-b"
+# insert a backslash (testing backslash escapes in sequences and macros)
+"\C-x\\": "\\"
+# Quote the current or previous word
+"\C-xq": "\eb\"\ef\""
+# Add a binding to refresh the line, which is unbound
+"\C-xr": redraw-current-line
+# Edit variable on current line.
+"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
+$endif
+
+# use a visible bell if one is available
+set bell-style visible
+
+# don't strip characters to 7 bits when reading
+set input-meta on
+
+# allow iso-latin1 characters to be inserted rather than converted to
+# prefix-meta sequences
+set convert-meta off
+
+# display characters with the eighth bit set directly rather than
+# as meta-prefixed characters
+set output-meta on
+
+# if there are more than 150 possible completions for a word, ask the
+# user if he wants to see all of them
+set completion-query-items 150
+
+# For FTP
+$if Ftp
+"\C-xg": "get \M-?"
+"\C-xt": "put \M-?"
+"\M-.": yank-last-arg
+$endif
+@end example
@node Bindable Readline Commands
@section Bindable Readline Commands
* Miscellaneous Commands:: Other miscellaneous commands.
@end menu
+This section describes Readline commands that may be bound to key
+sequences.
+
@node Commands For Moving
@subsection Commands For Moving
@ftable @code
@item history-search-forward ()
Search forward through the history for the string of characters
-between the start of the current line and the current point. This
-is a non-incremental search. By default, this command is unbound.
+between the start of the current line and the current cursor
+position (the `point'). 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 current point. This
+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)
inserts the @var{n}th word from the end of the previous command.
@item yank-last-arg (M-., M-_)
-Insert last argument to the previous command (the last word on the
-previous line). With an
+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}.
@end ftable
@item delete-char (C-d)
Delete the character under the cursor. If the cursor is at the
beginning of the line, there are no characters in the line, and
-the last character typed was not C-d, then return EOF.
+the last character typed was not @kbd{C-d}, then return @code{EOF}.
@item backward-delete-char (Rubout)
Delete the character behind the cursor. A numeric arg says to kill
@item delete-horizontal-space ()
Delete all spaces and tabs around point. By default, this is unbound.
+@item kill-region ()
+Kill the text between the point and the @emph{mark} (saved
+cursor position. This text is referred to as the @var{region}.
+By default, this command is unbound.
+
+@item copy-region-as-kill ()
+Copy the text in the region to the kill buffer, so you can yank it
+right away. By default, this command is unbound.
+
+@item copy-backward-word ()
+Copy the word before point to the kill buffer.
+By default, this command is unbound.
+
+@item copy-forward-word ()
+Copy the word following point to the kill buffer.
+By default, this command is unbound.
+
@item yank (C-y)
Yank the top of the kill ring into the buffer at the current
cursor position.
@item digit-argument (M-0, M-1, ... M--)
Add this digit to the argument already accumulating, or start a new
-argument. M-- starts a negative argument.
+argument. @key{M--} starts a negative argument.
@item universal-argument ()
Each time this is executed, the argument count is multiplied by four.
can do symbol name completion, if you are typing in a variable to Bash,
you can do variable name completion, and so on.
@ifset BashFeatures
-See the Bash manual page for a complete list of available completion
-functions.
+Bash attempts completion treating the text as a variable (if the
+text begins with @samp{$}), username (if the text begins with
+@samp{~}), hostname (if the text begins with @samp{@@}), or
+command (including aliases and functions) in turn. If none
+of these produces a match, filename completion is attempted.
@end ifset
@item possible-completions (M-?)
List the possible completions of the text before the cursor.
-@item insert-completions ()
+@item insert-completions (M-*)
Insert all completions of the text before point that would have
-been generated by @code{possible-completions}. By default, this
-is not bound to a key.
+been generated by @code{possible-completions}.
+@ifset BashFeatures
+@item complete-filename (M-/)
+Attempt filename completion on the text before point.
+
+@item possible-filename-completions (C-x /)
+List the possible completions of the text before point,
+treating it as a filename.
+
+@item complete-username (M-~)
+Attempt completion on the text before point, treating
+it as a username.
+
+@item possible-username-completions (C-x ~)
+List the possible completions of the text before point,
+treating it as a username.
+
+@item complete-variable (M-$)
+Attempt completion on the text before point, treating
+it as a shell variable.
+
+@item possible-variable-completions (C-x $)
+List the possible completions of the text before point,
+treating it as a shell variable.
+
+@item complete-hostname (M-@@)
+Attempt completion on the text before point, treating
+it as a hostname.
+
+@item possible-hostname-completions (C-x @@)
+List the possible completions of the text before point,
+treating it as a hostname.
+
+@item complete-command (M-!)
+Attempt completion on the text before point, treating
+it as a command name. Command completion attempts to
+match the text against aliases, reserved words, shell
+functions, builtins, and finally executable filenames,
+in that order.
+
+@item possible-command-completions (C-x !)
+List the possible completions of the text before point,
+treating it as a command name.
+
+@item dynamic-complete-history (M-TAB)
+Attempt 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 return the list of possible completions
+enclosed within braces so the list is available to the shell
+(@pxref{Brace Expansion}).
+
+@end ifset
@end ftable
@node Keyboard Macros
@ftable @code
@item re-read-init-file (C-x C-r)
-Read in the contents of your init file, and incorporate
+Read in the contents of the inputrc file, and incorporate
any bindings or variable assignments found there.
@item abort (C-g)
ring the terminal's bell (subject to the setting of
@code{bell-style}).
-@item do-uppercase-version (M-a, M-b, ...)
-Run the command that is bound to the corresoponding uppercase
-character.
+@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 prefix-meta (ESC)
Make the next character that you type be metafied. This is for people
@item tilde-expand (M-~)
Perform tilde expansion on the current word.
+@item set-mark (C-@@)
+Set the mark to the current point. If a
+numeric argument is supplied, the mark is set to that position.
+
+@item exchange-point-and-mark (C-x C-x)
+Swap the point with the mark. The current cursor position is set to
+the saved position, and the old cursor position is saved as the mark.
+
+@item character-search (C-])
+A character is read and point is moved to the next occurrence of that
+character. A negative count searches for previous occurrences.
+
+@item character-search-backward (M-C-])
+A character is read and point is moved to the previous occurrence
+of that character. A negative count searches for subsequent
+occurrences.
+
+@item insert-comment (M-#)
+The value of the @code{comment-begin}
+variable is inserted at the beginning of the current line,
+and the line is accepted as if a newline had been typed.
+@ifset BashFeatures
+This makes the current line a shell comment.
+@end ifset
+
@item dump-functions ()
Print all of the functions and their key bindings to the
readline output stream. If a numeric argument is supplied,
the output is formatted in such a way that it can be made part
-of an @var{inputrc} file.
+of an @var{inputrc} file. This command is unbound by default.
+
+@item dump-variables ()
+Print all of the settable variables and their values to the
+readline output stream. If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an @var{inputrc} file. This command is unbound by default.
+
+@item dump-macros ()
+Print all of the readline key sequences bound to macros and the
+strings they ouput. If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an @var{inputrc} file. This command is unbound by default.
@ifset BashFeatures
+@item glob-expand-word (C-x *)
+The word before point is treated as a pattern for pathname expansion,
+and the list of matching file names is inserted, replacing the word.
+
+@item glob-list-expansions (C-x g)
+The list of expansions that would have been generated by
+@code{glob-expand-word}
+is inserted into the line, replacing the word before point.
+
@item display-shell-version (C-x C-v)
Display version information about the current instance of Bash.
@item emacs-editing-mode (C-e)
When in @code{vi} editing mode, this causes a switch back to
-emacs editing mode, as if the command @code{set -o emacs} had
+@code{emacs} editing mode, as if the command @samp{set -o emacs} had
been executed.
@end ifset
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 Posix 1003.2 standard.
+the @sc{POSIX} 1003.2 standard.
@ifset BashFeatures
-In order to switch interactively between @code{Emacs} and @code{Vi}
-editing modes, use the @code{set -o emacs} and @code{set -o vi}
+In order to switch interactively between @code{emacs} and @code{vi}
+editing modes, use the @samp{set -o emacs} and @samp{set -o vi}
commands (@pxref{The Set Builtin}).
@end ifset
@ifclear BashFeatures
-In order to switch interactively between @code{Emacs} and @code{Vi}
+In order to switch interactively between @code{emacs} and @code{vi}
editing modes, use the command M-C-j (toggle-editing-mode).
@end ifclear
The Readline default is @code{emacs} mode.
`insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC}
switches you into `command' mode, where you can edit the text of the
line with the standard @code{vi} movement keys, move to previous
-history lines with @samp{k}, and following lines with @samp{j}, and
+history lines with @samp{k} and subsequent lines with @samp{j}, and
so forth.
projects / platform / upstream / bash.git / blobdiff