EDITLINE(7) | Miscellaneous Information Manual | EDITLINE(7) |
editline
— line
editing user interface
When a program using the
editline(3) library prompts for an
input string using the function
el_wgets(3), it reads characters from
the terminal. Invalid input bytes that do not form characters are silently
discarded. For each character read, one editor command is executed. The
mapping of input characters to editor commands depends on the editing mode.
There are three editing modes: vi insert mode, vi command mode, and emacs
mode. The default is vi insert mode. The program can switch the default to
emacs mode by using the el_set(3) or
el_parse(3) functions, and the user can
switch to emacs mode either in the
editrc(5) configuration file or
interactively with the ed-command
editor command, in
all three cases executing the bind
-e
builtin command.
If trying to read from the terminal results in end of file or an error, the library signals end of file to the program and does not return a string.
All default bindings described below can be overridden by
individual programs and can be changed with the
editrc(5) bind
builtin command.
In the following tables, ‘Ctrl-’ indicates a
character with the bit 0x40 flipped, and ‘Meta-’ indicates a
character with the bit 0x80 set. In vi insert mode and in emacs mode, all
Meta-characters considered printable by the current
locale(1) are bound to
ed-insert
instead of to the editor command listed
below. Consequently, in UTF-8 mode, most of the Meta-characters are not
directly accessible because their code points are occupied by printable
Unicode characters, and Meta-characters are usually input using the
em-meta-next
editor command. For example, to enter
‘Meta-B’ in order to call the
ed-prev-word
editor command in emacs mode, call
em-meta-next
by pressing and releasing the escape
key (or equivalently, Ctrl-[), then press and release the ‘B’
key. If you have configured a Meta-key on your keyboard, for example with
‘setxkbmap -option
altwin:left_meta_win
’, the Ctrl-Meta-characters are directly
accessible. For example, to enter ‘Ctrl-Meta-H’ in order to
call the ed-delete-prev-word
editor command in emacs
mode, hold down the keys ‘Ctrl’, ‘Meta’, and
‘H’ at the same time. Alternatively, press and release the
escape key, then press and release ‘Ctrl-H’.
In vi input mode, input characters are bound to the following editor commands by default:
Ctrl-D, EOF | vi-list-or-eof |
Ctrl-H, BS | vi-delete-prev-char |
Ctrl-J, LF | ed-newline |
Ctrl-M, CR | ed-newline |
Ctrl-Q | ed-tty-start-output |
Ctrl-S | ed-tty-stop-output |
Ctrl-U | vi-kill-line-prev |
Ctrl-V | ed-quoted-insert |
Ctrl-W | ed-delete-prev-word |
Ctrl-[, ESC | vi-command-mode |
Ctrl-\, QUIT | ed-tty-sigquit |
Ctrl-?, DEL | vi-delete-prev-char |
All other input characters except the NUL character (Ctrl-@) are
bound to ed-insert
.
In vi command mode, input characters are bound to the following editor commands by default:
In emacs mode, input characters are bound to the following editor commands by default:
The remaining ascii(7)
characters in the range 0x20 to 0x7e are bound to
ed-insert
.
If standard output is not connected to a terminal device or
el_set(3) was used to set
EL_EDITMODE
to 0, all input character bindings are
disabled and all characters typed are appended to the edit buffer. In that
case, the edit buffer is returned to the program after a newline or carriage
return character is typed, or after the first character typed if
el_set(3) was used to set
EL_UNBUFFERED
to non-zero.
Most editor commands accept an optional argument. The argument is
entered by prefixing the editor command with one or more of the editor
commands ed-argument-digit
,
ed-digit
,
em-universal-argument
, or
vi-zero
. When an argument is not provided, it
defaults to 1. For most editor commands, the effect of an argument is to
repeatedly execute the command that number of times.
When talking about a character string from a left character to a right character, the left character is included in the string, while the right character is not included.
If an editor command causes an error, the input character is discarded, no action occurs, and the terminal bell is rung. In case of a non-fatal error, the terminal bell is also rung, but the editor command takes effect anyway.
In the following list, the default key bindings are listed after each editor command.
ed-argument-digit
(vi command: 1 to 9; emacs: Meta-0 to Meta-9)ed-clear-screen
(vi command: Ctrl-L; emacs: Ctrl-L, Ctrl-Meta-L)ed-command
(vi command: ‘:’; emacs: Meta-X, Meta-x)ed-delete-next-char
(vi command: x)ed-delete-prev-char
(vi command: X, Ctrl-H, BS, Ctrl-?, DEL)ed-delete-prev-word
(vi: Ctrl-W; emacs: Ctrl-Meta-H, Ctrl-Meta-?)ed-digit
(emacs: 0 to 9)ed-insert
. It is an error if
the input character is not a digit or if the existing argument is already
greater than a million.ed-end-of-file
(not bound by default)ed-ignore
(various)ed-insert
(vi input: almost all; emacs: printable characters)ed-kill-line
(vi command: D, Ctrl-K; emacs: Ctrl-K, Ctrl-U)ed-move-to-beg
(vi command: ^, Ctrl-A; emacs: Ctrl-A)vi_change_meta
,
vi_delete_meta
, or
vi_yank
.ed-move-to-end
(vi command: $, Ctrl-E; emacs: Ctrl-E)vi_change_meta
,
vi_delete_meta
, or
vi_yank
.ed-newline
(all modes: Ctrl-J, LF, Ctrl-M, CR)ed-next-char
(vi command: Space, l; emacs: Ctrl-F)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if the cursor is already
at the end of the edit buffer.ed-next-history
(vi command: j, +, Ctrl-N; emacs: Ctrl-N)ed-next-line
(not bound by default)ed-prev-char
(vi command: h; emacs: Ctrl-B)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if the cursor is already
at the beginning of the edit buffer.ed-prev-history
(vi command: k, -, Ctrl-P; emacs: Ctrl-P)ed-prev-line
(not bound by default)ed-prev-word
(emacs: Meta-B, Meta-b)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if the cursor is already
at the beginning of the edit buffer.ed-quoted-insert
(vi insert, emacs: Ctrl-V)ed-insert
on it. If trying
to read the character returns end of file or an error, call
ed-end-of-file
instead.ed-redisplay
(vi command, emacs: Ctrl-R)ed-search-next-history
(vi command: J; emacs: Meta-N, Meta-n)ed-search-prev-history
(vi command: K; emacs: Meta-P, Meta-p)ed-sequence-lead-in
(vi cmd: O, [; emacs: Ctrl-X; both: Meta-O, Meta-[)ed-start-over
(not bound by default)ed-transpose-chars
(emacs: Ctrl-T)ed-unassigned
(all characters not listed)em-capitol-case
(emacs: Meta-C, Meta-c)em-copy-prev-word
(emacs: Ctrl-Meta-_)em-copy-region
(emacs: Meta-W, Meta-w)em-delete-next-word
(emacs: Meta-D, Meta-d)em-delete-or-list
(emacs: Ctrl-D, EOF)em-delete-prev-char
(emacs: Ctrl-H, BS, Ctrl-?, DEL)em-exchange-mark
(not bound by default)em-gosmacs-transpose
(not bound by default)em-inc-search-next
(not bound by default)em-inc-search-prev
(not bound by default)em-kill-line
(not bound by default)em-kill-region
(emacs: Ctrl-W)em-lower-case
(emacs: Meta-L, Meta-l)em-meta-next
(vi command, emacs: Ctrl-[, ESC)em-next-word
(Meta-F, Meta-f)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if the cursor is already
at the end of the edit buffer.em-set-mark
(emacs: Ctrl-Q, NUL)em-toggle-overwrite
(not bound by default)em-universal-argument
(not bound by default)em-upper-case
(emacs: Meta-U, Meta-u)em-yank
(emacs: Ctrl-Y)vi-add
(vi command: a)vi-add-at-eol
(vi command: A)vi-alias
(vi command: @)EL_ALIAS_TEXT
, read one character from the
terminal bypassing the normal line editing functionality, call the alias
function passing the argument that was specified with
EL_ALIAS_TEXT
as the first argument and the
character read, with an underscore prepended, as the second argument, and
pass the string returned from the alias function to
el_wpush(3). It is an error if no
alias function is defined or if trying to read the character results in
end of file or an error.vi-change-case
(vi command: ~)vi-change-meta
(vi command: c)vi-change-to-eol
(vi command: C)vi-command-mode
(vi insert: Ctrl-[, ESC)vi-comment-out
(vi command: #)vi-delete-meta
(vi command: d)vi-delete-prev-char
(vi insert: Ctrl-H, BS, Ctrl-?, DEL)vi-end-big-word
(vi command: E)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if the cursor is already
at the end of the edit buffer.vi-end-word
(vi command: e)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if the cursor is already
at the end of the edit buffer.vi-history-word
(vi command: _)vi-insert
(vi command: i)vi-insert-at-bol
(vi command: I)vi-kill-line-prev
(vi: Ctrl-U)vi-list-or-eof
(vi insert: Ctrl-D, EOF)vi-match
(vi command: %)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if there is no delimiter
at the cursor or in the string to the right of the cursor, or if the first
such delimiter has no matching delimiter.vi-next-big-word
(vi command: W)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if the cursor is already
at the end of the edit buffer or on its last character.vi-next-char
(vi command: f)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. If trying to read the character results
in end of file or an error, call ed-end-of-file
instead. It is an error if the character is not found searching to the
right in the edit buffer.vi-next-word
(vi command: w)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if the cursor is already
at the end of the edit buffer or on its last character.vi-paste-next
(vi command: p)vi-paste-prev
(vi command: P)vi-prev-big-word
(vi command: B)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if the cursor is already
at the beginning of the edit buffer.vi-prev-char
(vi command: F)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. If trying to read the character results
in end of file or an error, call ed-end-of-file
instead. It is an error if the character is not found searching to the
left in the edit buffer.vi-prev-word
(vi command: b)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. It is an error if the cursor is already
at the beginning of the edit buffer.vi-redo
(vi command: ‘.’)vi-repeat-next-char
(vi command: ‘;’)vi_change_meta
,
vi_delete_meta
, or
vi_yank
.vi-repeat-prev-char
(vi command: ‘,’)vi_change_meta
,
vi_delete_meta
, or
vi_yank
.vi-repeat-search-next
(vi command: n)vi-repeat-search-prev
(vi command: N)vi-replace-char
(vi command: r)ed-insert
for a description of replace mode. It is an error if the cursor is at the
end of the edit buffer.vi-replace-mode
(vi command: R)ed-insert
for the difference.vi-search-next
(vi command: ?)vi-search-prev
(vi command: /)vi-substitute-char
(vi command: s)vi-substitute-line
(vi command: S)vi-to-column
(vi command: |)vi_change_meta
,
vi_delete_meta
, or
vi_yank
.vi-to-history-line
(vi command: G)vi-to-next-char
(vi command: t)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. If trying to read the character results
in end of file or an error, call ed-end-of-file
instead. It is an error if the character is not found searching to the
right in the edit buffer.vi-to-prev-char
(vi command: T)vi_change_meta
,
vi_delete_meta
, or
vi_yank
. If trying to read the character results
in end of file or an error, call ed-end-of-file
instead. It is an error if the character is not found searching to the
left in the edit buffer.vi-undo
(vi command: u)vi-undo-line
(vi command: U)vi-yank
(vi command: y)vi-yank-end
(vi command: Y)vi-zero
(vi command: 0)vi_change_meta
,
vi_delete_meta
, or
vi_yank
.If an input character is bound to the editor command
ed-sequence-lead-in
,
editline
attempts to call a macro. If the input
character by itself forms the name of a macro, that macro is executed.
Otherwise, additional input characters are read until the string read forms
the name of a macro, in which case that macro is executed, or until the
string read matches the beginning of none of the existing macro names, in
which case the string including the final, mismatching character is
discarded and the terminal bell is rung.
There are two kinds of macros. Command macros execute a single editor command. Keyboard macros return a string of characters that is appended as a new line to the Input Queue.
The following command macros are defined by default in vi command mode and in emacs mode:
Esc [ A, Esc O A | ed-prev-history |
Esc [ B, Esc O B | ed-next-history |
Esc [ C, Esc O C | ed-next-char |
Esc [ D, Esc O D | ed-prev-char |
Esc [ F, Esc O F | ed-move-to-end |
Esc [ H, Esc O H | ed-move-to-beg |
In vi command mode, they are also defined by default without the initial escape character.
In addition, the editline
library tries to
bind the strings generated by the arrow keys as reported by the
terminfo(5) database to these editor
commands, unless that would clobber user settings.
In emacs mode, the two-character string “Ctrl-X
Ctrl-X” is bound to the em-exchange-mark
editor command.
The editline
library maintains an input
queue operated in FIFO mode. Whenever it needs an input character, it takes
the first character from the first line of the input queue. When the queue
is empty, it reads from the terminal.
A line can be appended to the end of the input queue in several ways:
vi-redo
.vi-alias
.This manual page first appeared in OpenBSD 6.0.
This manual page was written by Ingo Schwarze <schwarze@openbsd.org>.
May 10, 2016 | OpenBSD-current |