contrib/libedit/editline.7

   1 .\"     $NetBSD: editline.7,v 1.5 2016/05/09 21:27:55 christos Exp $
   2 .\"     $OpenBSD: editline.7,v 1.1 2016/04/20 01:11:45 schwarze Exp $
   3 .\"
   4 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd May 7, 2016
  19 .Dt EDITLINE 7
  20 .Os
  21 .Sh NAME
  22 .Nm editline
  23 .Nd line editing user interface
  24 .Sh DESCRIPTION
  25 When a program using the
  26 .Xr editline 3
  27 library prompts for an input string using the function
  28 .Xr el_wgets 3 ,
  29 it reads characters from the terminal.
  30 Invalid input bytes that do not form characters are silently
  31 discarded.
  32 For each character read, one editor command is executed.
  33 The mapping of input characters to editor commands depends on the
  34 editing mode.
  35 There are three editing modes: vi insert mode, vi command mode,
  36 and emacs mode.
  37 The default is vi insert mode.
  38 The program can switch the default to emacs mode by using the
  39 .Xr el_set 3
  40 or
  41 .Xr el_parse 3
  42 functions, and the user can switch to emacs mode either in the
  43 .Xr editrc 5
  44 configuration file or interactively with the
  45 .Ic ed-command
  46 editor command, in all three cases executing the
  47 .Ic bind Fl e
  48 builtin command.
  49 .Pp
  50 If trying to read from the terminal results in end of file or an
  51 error, the library signals end of file to the program and does not
  52 return a string.
  53 .Ss Input character bindings
  54 All default bindings described below can be overridden by individual
  55 programs and can be changed with the
  56 .Xr editrc 5
  57 .Ic bind
  58 builtin command.
  59 .Pp
  60 In the following tables,
  61 .Sq Ctrl-
  62 indicates a character with the bit 0x40 flipped, and
  63 .Sq Meta-
  64 indicates a character with the bit 0x80 set.
  65 In vi insert mode and in emacs mode, all Meta-characters considered
  66 printable by the current
  67 .Xr locale 1
  68 are bound to
  69 .Ic ed-insert
  70 instead of to the editor command listed below.
  71 Consequently, in UTF-8 mode, most of the Meta-characters are not
  72 directly accessible because their code points are occupied by
  73 printable Unicode characters, and Meta-characters are usually input
  74 using the
  75 .Ic em-meta-next
  76 editor command.
  77 For example, to enter
  78 .Sq Meta-B
  79 in order to call the
  80 .Ic ed-prev-word
  81 editor command in emacs mode, call
  82 .Ic em-meta-next
  83 by pressing and releasing the escape key (or equivalently, Ctrl-[),
  84 then press and release the
  85 .Sq B
  86 key.
  87 If you have configured a Meta-key on your keyboard, for example
  88 with
  89 .Ql setxkbmap -option altwin:left_meta_win ,
  90 the Ctrl-Meta-characters are directly accessible.
  91 For example, to enter
  92 .Sq Ctrl-Meta-H
  93 in order to call the
  94 .Ic ed-delete-prev-word
  95 editor command in emacs mode, hold down the keys
  96 .Sq Ctrl ,
  97 .Sq Meta ,
  98 and
  99 .Sq H
 100 at the same time.
 101 Alternatively, press and release the escape key, then press and
 102 release
 103 .Sq Ctrl-H .
 104 .Pp
 105 In vi input mode, input characters are bound to the following editor
 106 commands by default:
 107 .Bl -column -offset indent "Ctrl-Z, TSTP" "ed-search-next-history"
 108 .It Ctrl-D, EOF Ta Ic vi-list-or-eof
 109 .It Ctrl-H, BS Ta Ic vi-delete-prev-char
 110 .It Ctrl-J, LF Ta Ic ed-newline
 111 .It Ctrl-M, CR Ta Ic ed-newline
 112 .It Ctrl-Q Ta Ic ed-tty-start-output
 113 .It Ctrl-S Ta Ic ed-tty-stop-output
 114 .It Ctrl-U Ta Ic vi-kill-line-prev
 115 .It Ctrl-V Ta Ic ed-quoted-insert
 116 .It Ctrl-W Ta Ic ed-delete-prev-word
 117 .It Ctrl-[, ESC Ta Ic vi-command-mode
 118 .It Ctrl-\e, QUIT Ta Ic ed-tty-sigquit
 119 .It Ctrl-?, DEL Ta Ic vi-delete-prev-char
 120 .El
 121 .Pp
 122 All other input characters except the NUL character (Ctrl-@) are
 123 bound to
 124 .Ic ed-insert .
 125 .Pp
 126 In vi command mode, input characters are bound to the following
 127 editor commands by default:
 128 .Bl -column -offset indent "Ctrl-Z, TSTP" "ed-search-next-history"
 129 .It Ctrl-A Ta Ic ed-move-to-beg
 130 .It Ctrl-C, INT Ta Ic ed-tty-sigint
 131 .It Ctrl-E Ta Ic ed-move-to-end
 132 .It Ctrl-H, BS Ta Ic ed-delete-prev-char
 133 .It Ctrl-J, LF Ta Ic ed-newline
 134 .It Ctrl-K Ta Ic ed-kill-line
 135 .It Ctrl-L, FF Ta Ic ed-clear-screen
 136 .It Ctrl-M, CR Ta Ic ed-newline
 137 .It Ctrl-N Ta Ic ed-next-history
 138 .It Ctrl-O Ta Ic ed-tty-flush-output
 139 .It Ctrl-P Ta Ic ed-prev-history
 140 .It Ctrl-Q Ta Ic ed-tty-start-output
 141 .It Ctrl-R Ta Ic ed-redisplay
 142 .It Ctrl-S Ta Ic ed-tty-stop-output
 143 .It Ctrl-U Ta Ic vi-kill-line-prev
 144 .It Ctrl-W Ta Ic ed-delete-prev-word
 145 .It Ctrl-[, ESC Ta Ic em-meta-next
 146 .It Ctrl-\e, QUIT Ta Ic ed-tty-sigquit
 147 .It Space Ta Ic ed-next-char
 148 .It # Ta Ic vi-comment-out
 149 .It $ Ta Ic ed-move-to-end
 150 .It % Ta Ic vi-match
 151 .It + Ta Ic ed-next-history
 152 .It \&, Ta Ic vi-repeat-prev-char
 153 .It - Ta Ic ed-prev-history
 154 .It \&. Ta Ic vi-redo
 155 .It / Ta Ic vi-search-prev
 156 .It 0 Ta Ic vi-zero
 157 .It 1 to 9 Ta Ic ed-argument-digit
 158 .It \&: Ta Ic ed-command
 159 .It \&; Ta Ic vi-repeat-next-char
 160 .It \&? Ta Ic vi-search-next
 161 .It @ Ta Ic vi-alias
 162 .It A Ta Ic vi-add-at-eol
 163 .It B Ta Ic vi-prev-big-word
 164 .It C Ta Ic vi-change-to-eol
 165 .It D Ta Ic ed-kill-line
 166 .It E Ta Ic vi-end-big-word
 167 .It F Ta Ic vi-prev-char
 168 .It G Ta Ic vi-to-history-line
 169 .It I Ta Ic vi-insert-at-bol
 170 .It J Ta Ic ed-search-next-history
 171 .It K Ta Ic ed-search-prev-history
 172 .It N Ta Ic vi-repeat-search-prev
 173 .It O Ta Ic ed-sequence-lead-in
 174 .It P Ta Ic vi-paste-prev
 175 .It R Ta Ic vi-replace-mode
 176 .It S Ta Ic vi-substitute-line
 177 .It T Ta Ic vi-to-prev-char
 178 .It U Ta Ic vi-undo-line
 179 .It W Ta Ic vi-next-big-word
 180 .It X Ta Ic ed-delete-prev-char
 181 .It Y Ta Ic vi-yank-end
 182 .It \&[ Ta Ic ed-sequence-lead-in
 183 .It ^ Ta Ic ed-move-to-beg
 184 .It _ Ta Ic vi-history-word
 185 .It a Ta Ic vi-add
 186 .It b Ta Ic vi-prev-word
 187 .It c Ta Ic vi-change-meta
 188 .It d Ta Ic vi-delete-meta
 189 .It e Ta Ic vi-end-word
 190 .It f Ta Ic vi-next-char
 191 .It h Ta Ic ed-prev-char
 192 .It i Ta Ic vi-insert
 193 .It j Ta Ic ed-next-history
 194 .It k Ta Ic ed-prev-history
 195 .It l Ta Ic ed-next-char
 196 .It n Ta Ic vi-repeat-search-next
 197 .It p Ta Ic vi-paste-next
 198 .It r Ta Ic vi-replace-char
 199 .It s Ta Ic vi-substitute-char
 200 .It t Ta Ic vi-to-next-char
 201 .It u Ta Ic vi-undo
 202 .It v Ta Ic vi-histedit
 203 .It w Ta Ic vi-next-word
 204 .It x Ta Ic ed-delete-next-char
 205 .It y Ta Ic vi-yank
 206 .It \&| Ta Ic vi-to-column
 207 .It ~ Ta Ic vi-change-case
 208 .It Ctrl-?, DEL Ta Ic ed-delete-prev-char
 209 .It Meta-O Ta Ic ed-sequence-lead-in
 210 .It Meta-[ Ta Ic ed-sequence-lead-in
 211 .El
 212 .Pp
 213 In emacs mode, input characters are bound to the following editor
 214 commands by default:
 215 .Bl -column -offset indent "Ctrl-Z, TSTP" "ed-search-next-history"
 216 .It 0 to 9 Ta Ic ed-digit
 217 .It Ctrl-@, NUL Ta Ic em-set-mark
 218 .It Ctrl-A Ta Ic ed-move-to-beg
 219 .It Ctrl-B Ta Ic ed-prev-char
 220 .It Ctrl-C, INT Ta Ic ed-tty-sigint
 221 .It Ctrl-D, EOF Ta Ic em-delete-or-list
 222 .It Ctrl-E Ta Ic ed-move-to-end
 223 .It Ctrl-F Ta Ic ed-next-char
 224 .It Ctrl-H, BS Ta Ic em-delete-prev-char
 225 .It Ctrl-J, LF Ta Ic ed-newline
 226 .It Ctrl-K Ta Ic ed-kill-line
 227 .It Ctrl-L, FF Ta Ic ed-clear-screen
 228 .It Ctrl-M, CR Ta Ic ed-newline
 229 .It Ctrl-N Ta Ic ed-next-history
 230 .It Ctrl-O Ta Ic ed-tty-flush-output
 231 .It Ctrl-P Ta Ic ed-prev-history
 232 .It Ctrl-Q Ta Ic ed-tty-start-output
 233 .It Ctrl-R Ta Ic ed-redisplay
 234 .It Ctrl-S Ta Ic ed-tty-stop-output
 235 .It Ctrl-T Ta Ic ed-transpose-chars
 236 .It Ctrl-U Ta Ic ed-kill-line
 237 .It Ctrl-V Ta Ic ed-quoted-insert
 238 .It Ctrl-W Ta Ic em-kill-region
 239 .It Ctrl-X Ta Ic ed-sequence-lead-in
 240 .It Ctrl-Y Ta Ic em-yank
 241 .It Ctrl-Z, TSTP Ta Ic ed-tty-sigtstp
 242 .It Ctrl-[, ESC Ta Ic em-meta-next
 243 .It Ctrl-\e, QUIT Ta Ic ed-tty-sigquit
 244 .It Ctrl-] Ta Ic ed-tty-dsusp
 245 .It Ctrl-?, DEL Ta Ic em-delete-prev-char
 246 .It Ctrl-Meta-H Ta Ic ed-delete-prev-word
 247 .It Ctrl-Meta-L Ta Ic ed-clear-screen
 248 .It Ctrl-Meta-_ Ta Ic em-copy-prev-word
 249 .It Meta-0 to 9 Ta Ic ed-argument-digit
 250 .It Meta-B Ta Ic ed-prev-word
 251 .It Meta-C Ta Ic em-capitol-case
 252 .It Meta-D Ta Ic em-delete-next-word
 253 .It Meta-F Ta Ic em-next-word
 254 .It Meta-L Ta Ic em-lower-case
 255 .It Meta-N Ta Ic ed-search-next-history
 256 .It Meta-O Ta Ic ed-sequence-lead-in
 257 .It Meta-P Ta Ic ed-search-prev-history
 258 .It Meta-U Ta Ic em-upper-case
 259 .It Meta-W Ta Ic em-copy-region
 260 .It Meta-X Ta Ic ed-command
 261 .It Meta-[ Ta Ic ed-sequence-lead-in
 262 .It Meta-b Ta Ic ed-prev-word
 263 .It Meta-c Ta Ic em-capitol-case
 264 .It Meta-d Ta Ic em-delete-next-word
 265 .It Meta-f Ta Ic em-next-word
 266 .It Meta-l Ta Ic em-lower-case
 267 .It Meta-n Ta Ic ed-search-next-history
 268 .It Meta-p Ta Ic ed-search-prev-history
 269 .It Meta-u Ta Ic em-upper-case
 270 .It Meta-w Ta Ic em-copy-region
 271 .It Meta-x Ta Ic ed-command
 272 .It Ctrl-Meta-? Ta Ic ed-delete-prev-word
 273 .El
 274 .Pp
 275 The remaining
 276 .Xr ascii 7
 277 characters in the range 0x20 to 0x7e are bound to
 278 .Ic ed-insert .
 279 .Pp
 280 If standard output is not connected to a terminal device
 281 or
 282 .Xr el_set 3
 283 was used to set
 284 .Dv EL_EDITMODE
 285 to 0, all input character bindings are disabled and all characters
 286 typed are appended to the edit buffer.
 287 In that case, the edit buffer is returned to the program after a
 288 newline or carriage return character is typed, or after the first
 289 character typed if
 290 .Xr el_set 3
 291 was used to set
 292 .Dv EL_UNBUFFERED
 293 to non-zero.
 294 .Ss Editor commands
 295 Most editor commands accept an optional argument.
 296 The argument is entered by prefixing the editor command with one
 297 or more of the editor commands
 298 .Ic ed-argument-digit ,
 299 .Ic ed-digit ,
 300 .Ic em-universal-argument ,
 301 or
 302 .Ic vi-zero .
 303 When an argument is not provided, it defaults to 1.
 304 For most editor commands, the effect of an argument is to repeatedly
 305 execute the command that number of times.
 306 .Pp
 307 When talking about a character string from a left character to a
 308 right character, the left character is included in the string, while
 309 the right character is not included.
 310 .Pp
 311 If an editor command causes an error, the input character is discarded,
 312 no action occurs, and the terminal bell is rung.
 313 In case of a non-fatal error, the terminal bell is also rung,
 314 but the editor command takes effect anyway.
 315 .Pp
 316 In the following list, the default key bindings are listed after
 317 each editor command.
 318 .Bl -tag -width 4n
 319 .It Ic ed-argument-digit Pq vi command: 1 to 9; emacs: Meta-0 to Meta-9
 320 If in argument input mode, append the input digit to the argument
 321 being read.
 322 Otherwise, switch to argument input mode and use the input digit
 323 as the most significant digit of the argument.
 324 It is an error if the input character is not a digit or if the
 325 existing argument is already greater than a million.
 326 .It Ic ed-clear-screen Pq vi command: Ctrl-L; emacs: Ctrl-L, Ctrl-Meta-L
 327 Clear the screen and display the edit buffer at the top.
 328 Ignore any argument.
 329 .It Ic ed-command Pq vi command: So \&: Sc ; emacs: Meta-X, Meta-x
 330 Read a line from the terminal bypassing the normal line editing
 331 functionality and execute that line as an
 332 .Xr editrc 5
 333 builtin command.
 334 If in vi command mode, also switch back to vi insert mode.
 335 Ignore any argument.
 336 .It Ic ed-delete-next-char Pq vi command: x
 337 Delete the character at the cursor position.
 338 With an argument, delete that number of characters.
 339 In emacs mode, it is an error if the cursor is at the end of the
 340 edit buffer.
 341 In vi mode, the last character in the edit buffer is deleted in
 342 that case, and it is an error if the buffer is empty.
 343 .It Ic ed-delete-prev-char Pq vi command: X, Ctrl-H, BS, Ctrl-?, DEL
 344 Delete the character to the left of the cursor position.
 345 With an argument, delete that number of characters.
 346 It is an error if the cursor is at the beginning of the edit buffer.
 347 .It Ic ed-delete-prev-word Pq vi: Ctrl-W; emacs: Ctrl-Meta-H, Ctrl-Meta-?
 348 Move to the left to the closest beginning of a word, delete the
 349 string from that position to the cursor, and save it to the cut
 350 buffer.
 351 With an argument, delete that number of words.
 352 It is an error if the cursor is at the beginning of the edit buffer.
 353 .It Ic ed-digit Pq emacs: 0 to 9
 354 If in argument input mode, append the input digit to the argument
 355 being read.
 356 Otherwise, call
 357 .Ic ed-insert .
 358 It is an error if the input character is not a digit or if the
 359 existing argument is already greater than a million.
 360 .It Ic ed-end-of-file Pq not bound by default
 361 Discard the edit buffer and indicate end of file to the program.
 362 Ignore any argument.
 363 .It Ic ed-ignore Pq various
 364 Discard the input character and do nothing.
 365 .It Ic ed-insert Pq vi input: almost all; emacs: printable characters
 366 In insert mode, insert the input character left of the cursor
 367 position.
 368 In replace mode, overwrite the character at the cursor and move the
 369 cursor to the right by one character position.
 370 Accept an argument to do this repeatedly.
 371 It is an error if the input character is the NUL character (Ctrl-@).
 372 Failure to enlarge the edit buffer also results in an error.
 373 .It Ic ed-kill-line Pq vi command: D, Ctrl-K; emacs: Ctrl-K, Ctrl-U
 374 Delete the string from the cursor position to the end of the line
 375 and save it to the cut buffer.
 376 Ignore any argument.
 377 .It Ic ed-move-to-beg Pq vi command: ^, Ctrl-A; emacs: Ctrl-A
 378 In vi mode, move the cursor to the first non-space character in the
 379 edit buffer.
 380 In emacs mode, move the cursor to the beginning of the edit buffer.
 381 Ignore any argument.
 382 Can be used as a movement command after
 383 .Ic vi_change_meta ,
 384 .Ic vi_delete_meta ,
 385 or
 386 .Ic vi_yank .
 387 .It Ic ed-move-to-end Pq vi command: $, Ctrl-E; emacs: Ctrl-E
 388 Move the cursor to the end of the edit buffer.
 389 Ignore any argument.
 390 Can be used as a movement command after
 391 .Ic vi_change_meta ,
 392 .Ic vi_delete_meta ,
 393 or
 394 .Ic vi_yank .
 395 .It Ic ed-newline Pq all modes: Ctrl-J, LF, Ctrl-M, CR
 396 Append a newline character to the edit buffer and return the edit
 397 buffer to the program.
 398 Ignore any argument.
 399 .It Ic ed-next-char Pq vi command: Space, l; emacs: Ctrl-F
 400 Move the cursor one character position to the right.
 401 With an argument, move by that number of characters.
 402 Can be used as a movement command after
 403 .Ic vi_change_meta ,
 404 .Ic vi_delete_meta ,
 405 or
 406 .Ic vi_yank .
 407 It is an error if the cursor is already at the end of the edit
 408 buffer.
 409 .It Ic ed-next-history Pq vi command: j, +, Ctrl-N; emacs: Ctrl-N
 410 Replace the edit buffer with the next history line.
 411 That line is older than the current line.
 412 With an argument, go forward by that number of history lines.
 413 It is a non-fatal error to advance by more lines than are available.
 414 .It Ic ed-next-line Pq not bound by default
 415 Move the cursor down one line.
 416 With an argument, move down by that number of lines.
 417 It is an error if the edit buffer does not contain enough newline
 418 characters to the right of the cursor position.
 419 .It Ic ed-prev-char Pq vi command: h; emacs: Ctrl-B
 420 Move the cursor one character position to the left.
 421 With an argument, move by that number of characters.
 422 Can be used as a movement command after
 423 .Ic vi_change_meta ,
 424 .Ic vi_delete_meta ,
 425 or
 426 .Ic vi_yank .
 427 It is an error if the cursor is already at the beginning of the
 428 edit buffer.
 429 .It Ic ed-prev-history Pq vi command: k, -, Ctrl-P; emacs: Ctrl-P
 430 Replace the edit buffer with the previous history line.
 431 That line is newer than the current line.
 432 With an argument, go back by that number of lines.
 433 It is a non-fatal error to back up by more lines than are available.
 434 .It Ic ed-prev-line Pq not bound by default
 435 Move the cursor up one line.
 436 With an argument, move up by that number of lines.
 437 It is an error if the edit buffer does not contain enough newline
 438 characters to the left of the cursor position.
 439 .It Ic ed-prev-word Pq emacs: Meta-B, Meta-b
 440 Move the cursor to the left to the closest beginning of a word.
 441 With an argument, repeat that number of times.
 442 Can be used as a movement command after
 443 .Ic vi_change_meta ,
 444 .Ic vi_delete_meta ,
 445 or
 446 .Ic vi_yank .
 447 It is an error if the cursor is already at the beginning of the
 448 edit buffer.
 449 .It Ic ed-quoted-insert Pq vi insert, emacs: Ctrl-V
 450 Read one character from the terminal bypassing the normal line
 451 editing functionality and call
 452 .Ic ed-insert
 453 on it.
 454 If trying to read the character returns end of file or an error,
 455 call
 456 .Ic ed-end-of-file
 457 instead.
 458 .It Ic ed-redisplay Pq vi command, emacs: Ctrl-R
 459 Redisplay everything.
 460 Ignore any argument.
 461 .It Ic ed-search-next-history Pq vi command: J; emacs: Meta-N, Meta-n
 462 Replace the edit buffer with the next matching history entry.
 463 .It Ic ed-search-prev-history Pq vi command: K; emacs: Meta-P, Meta-p
 464 Replace the edit buffer with the previous matching history entry.
 465 .It Ic ed-sequence-lead-in Pq vi cmd: O, \&[; emacs: Ctrl-X;\
 466  both: Meta-O, Meta-[
 467 Call a macro.
 468 See the section about
 469 .Sx Macros
 470 below for details.
 471 .It Ic ed-start-over Pq not bound by default
 472 Discard the contents of the edit buffer and start from scratch.
 473 Ignore any argument.
 474 .It Ic ed-transpose-chars Pq emacs: Ctrl-T
 475 Exchange the character at the cursor position with the one to the
 476 left of it and move the cursor to the character to the right of the
 477 two exchanged characters.
 478 Ignore any argument.
 479 It is an error if the cursor is at the beginning of the edit buffer
 480 or if the edit buffer contains less than two characters.
 481 .It Ic ed-unassigned Pq all characters not listed
 482 This editor command always results in an error.
 483 .It Ic em-capitol-case Pq emacs: Meta-C, Meta-c
 484 Capitalize the string from the cursor to the end of the current
 485 word.
 486 That is, if it contains at least one alphabetic character, convert
 487 the first alphabetic character to upper case, and convert all
 488 characters to the right of it to lower case.
 489 In any case, move the cursor to the next character after the end
 490 of the current word.
 491 .It Ic em-copy-prev-word Pq emacs: Ctrl-Meta-_
 492 Copy the string from the beginning of the current word to the cursor
 493 and insert it to the left of the cursor.
 494 Move the cursor to the character after the inserted string.
 495 It is an error if the cursor is at the beginning of the edit buffer.
 496 .It Ic em-copy-region Pq emacs: Meta-W, Meta-w
 497 Copy the string from the cursor to the mark to the cut buffer.
 498 It is an error if the mark is not set.
 499 .It Ic em-delete-next-word Pq emacs: Meta-D, Meta-d
 500 Delete the string from the cursor to the end of the current word
 501 and save it to the cut buffer.
 502 It is an error if the cursor is at the end of the edit buffer.
 503 .It Ic em-delete-or-list Pq emacs: Ctrl-D, EOF
 504 If the cursor is not at the end of the line, delete the character
 505 at the cursor.
 506 If the edit buffer is empty, indicate end of file to the program.
 507 It is an error if the cursor is at the end of the edit buffer and
 508 the edit buffer is not empty.
 509 .It Ic em-delete-prev-char Pq emacs: Ctrl-H, BS, Ctrl-?, DEL
 510 Delete the character to the left of the cursor.
 511 It is an error if the cursor is at the beginning of the edit buffer.
 512 .It Ic em-exchange-mark Pq not bound by default
 513 Exchange the cursor and the mark.
 514 .It Ic em-gosmacs-transpose Pq not bound by default
 515 Exchange the two characters to the left of the cursor.
 516 It is an error if the cursor is on the first or second character
 517 of the edit buffer.
 518 .It Ic em-inc-search-next Pq not bound by default
 519 Emacs incremental next search.
 520 .It Ic em-inc-search-prev Pq not bound by default
 521 Emacs incremental reverse search.
 522 .It Ic em-kill-line Pq not bound by default
 523 Delete the entire contents of the edit buffer and save it to the
 524 cut buffer.
 525 .It Ic em-kill-region Pq emacs: Ctrl-W
 526 Delete the string from the cursor to the mark and save it to the
 527 cut buffer.
 528 It is an error if the mark is not set.
 529 .It Ic em-lower-case Pq emacs: Meta-L, Meta-l
 530 Convert the characters from the cursor to the end of the current
 531 word to lower case.
 532 .It Ic em-meta-next Pq vi command, emacs: Ctrl-[, ESC
 533 Set the bit 0x80 on the next character typed.
 534 Unless the resulting code point is printable, holding down the
 535 .Sq Meta-
 536 key while typing that character is a simpler way to achieve the
 537 same effect.
 538 .It Ic em-next-word Pq Meta-F, Meta-f
 539 Move the cursor to the end of the current word.
 540 Can be used as a movement command after
 541 .Ic vi_change_meta ,
 542 .Ic vi_delete_meta ,
 543 or
 544 .Ic vi_yank .
 545 It is an error if the cursor is already at the end of the edit
 546 buffer.
 547 .It Ic em-set-mark Pq emacs: Ctrl-Q, NUL
 548 Set the mark at the current cursor position.
 549 .It Ic em-toggle-overwrite Pq not bound by default
 550 Switch from insert to overwrite mode or vice versa.
 551 .It Ic em-universal-argument Pq not bound by default
 552 If in argument input mode, multiply the argument by 4.
 553 Otherwise, switch to argument input mode and set the argument to 4.
 554 It is an error if the existing argument is already greater than a
 555 million.
 556 .It Ic em-upper-case Pq emacs: Meta-U, Meta-u
 557 Convert the characters from the cursor to the end of the current
 558 word to upper case.
 559 .It Ic em-yank Pq emacs: Ctrl-Y
 560 Paste the cut buffer to the left of the cursor.
 561 .It Ic vi-add Pq vi command: a
 562 Switch to vi insert mode.
 563 Unless the cursor is already at the end of the edit buffer, move
 564 it one character position to the right.
 565 .It Ic vi-add-at-eol Pq vi command: A
 566 Switch to vi insert mode and move the cursor to the end of the edit
 567 buffer.
 568 .It Ic vi-alias Pq vi command: @
 569 If an alias function was defined by calling the
 570 .Xr el_set 3
 571 or
 572 .Xr el_wset 3
 573 function with the argument
 574 .Dv EL_ALIAS_TEXT ,
 575 read one character from the terminal bypassing the normal line
 576 editing functionality, call the alias function passing the argument that was specified with
 577 .Dv EL_ALIAS_TEXT
 578 as the first argument and the character read, with an underscore
 579 prepended, as the second argument, and pass the string returned
 580 from the alias function to
 581 .Xr el_wpush 3 .
 582 It is an error if no alias function is defined or if trying to read
 583 the character results in end of file or an error.
 584 .It Ic vi-change-case Pq vi command: ~
 585 Change the case of the character at the cursor and move the cursor
 586 one character position to the right.
 587 It is an error if the cursor is already at the end of the edit
 588 buffer.
 589 .It Ic vi-change-meta Pq vi command: c
 590 Delete the string from the cursor to the position specified by the
 591 following movement command and save a copy of it to the cut buffer.
 592 When given twice in a row, instead delete the whole contents of the
 593 edit buffer and save a copy of it to the cut buffer.
 594 In either case, switch to vi insert mode after that.
 595 .It Ic vi-change-to-eol Pq vi command: C
 596 Delete the string from the cursor position to the end of the line
 597 and save it to the cut buffer, then switch to vi insert mode.
 598 .It Ic vi-command-mode Pq vi insert: Ctrl-[, ESC
 599 Discard pending actions and arguments and switch to vi command mode.
 600 Unless the cursor is already at the beginning of the edit buffer,
 601 move it to the left by one character position.
 602 .It Ic vi-comment-out Pq vi command: #
 603 Insert a
 604 .Sq #
 605 character at the beginning of the edit buffer and return the edit
 606 buffer to the program.
 607 .It Ic vi-delete-meta Pq vi command: d
 608 Delete the string from the cursor to the position specified by the
 609 following movement command and save a copy of it to the cut buffer.
 610 When given twice in a row, instead delete the whole contents of the
 611 edit buffer and save a copy of it to the cut buffer.
 612 .It Ic vi-delete-prev-char Pq vi insert: Ctrl-H, BS, Ctrl-?, DEL
 613 Delete the character to the left of the cursor.
 614 It is an error if the cursor is already at the beginning of the
 615 edit buffer.
 616 .It Ic vi-end-big-word Pq vi command: E
 617 Move the cursor to the end of the current space delimited word.
 618 Can be used as a movement command after
 619 .Ic vi_change_meta ,
 620 .Ic vi_delete_meta ,
 621 or
 622 .Ic vi_yank .
 623 It is an error if the cursor is already at the end of the edit
 624 buffer.
 625 .It Ic vi-end-word Pq vi command: e
 626 Move the cursor to the end of the current word.
 627 Can be used as a movement command after
 628 .Ic vi_change_meta ,
 629 .Ic vi_delete_meta ,
 630 or
 631 .Ic vi_yank .
 632 It is an error if the cursor is already at the end of the edit
 633 buffer.
 634 .It Ic vi-history-word Pq vi command: _
 635 Insert the first word from the most recent history entry after the
 636 cursor, move the cursor after to the character after the inserted
 637 word, and switch to vi insert mode.
 638 It is an error if there is no history entry or the most recent
 639 history entry is empty.
 640 .It Ic vi-insert Pq vi command: i
 641 Enter insert mode.
 642 .It Ic vi-insert-at-bol Pq vi command: I
 643 Move the cursor to the beginning of the edit buffer and switch to
 644 vi insert mode.
 645 .It Ic vi-kill-line-prev Pq vi: Ctrl-U
 646 Delete the string from the beginning of the edit buffer to the
 647 cursor and save it to the cut buffer.
 648 .It Ic vi-list-or-eof Pq vi insert: Ctrl-D, EOF
 649 If the edit buffer is empty, indicate end of file to the program.
 650 It is an error if the edit buffer is not empty.
 651 .It Ic vi-match Pq vi command: %
 652 Consider opening and closing parentheses, braces, and brackets as
 653 delimiters.
 654 If the cursor is not at a delimiter, move it to the right until it
 655 gets to one, then move it to the matching delimiter.
 656 Can be used as a movement command after
 657 .Ic vi_change_meta ,
 658 .Ic vi_delete_meta ,
 659 or
 660 .Ic vi_yank .
 661 It is an error if there is no delimiter at the cursor or in the
 662 string to the right of the cursor, or if the first such delimiter
 663 has no matching delimiter.
 664 .It Ic vi-next-big-word Pq vi command: W
 665 Move the cursor to the right to the beginning of the next space
 666 delimited word.
 667 Can be used as a movement command after
 668 .Ic vi_change_meta ,
 669 .Ic vi_delete_meta ,
 670 or
 671 .Ic vi_yank .
 672 It is an error if the cursor is already at the end of the edit
 673 buffer or on its last character.
 674 .It Ic vi-next-char Pq vi command: f
 675 Read one character from the terminal bypassing the normal line
 676 editing functionality and move the cursor to the right to the next
 677 instance of that character in the edit buffer.
 678 Can be used as a movement command after
 679 .Ic vi_change_meta ,
 680 .Ic vi_delete_meta ,
 681 or
 682 .Ic vi_yank .
 683 If trying to read the character results in end of file or an error,
 684 call
 685 .Ic ed-end-of-file
 686 instead.
 687 It is an error if the character is not found searching to the right
 688 in the edit buffer.
 689 .It Ic vi-next-word Pq vi command: w
 690 Move the cursor to the right to the beginning of the next word.
 691 Can be used as a movement command after
 692 .Ic vi_change_meta ,
 693 .Ic vi_delete_meta ,
 694 or
 695 .Ic vi_yank .
 696 It is an error if the cursor is already at the end of the edit
 697 buffer or on its last character.
 698 .It Ic vi-paste-next Pq vi command: p
 699 Insert a copy of the cut buffer to the right of the cursor.
 700 It is an error if the cut buffer is empty.
 701 .It Ic vi-paste-prev Pq vi command: P
 702 Insert a copy of the cut buffer to the left of the cursor.
 703 It is an error if the cut buffer is empty.
 704 .It Ic vi-prev-big-word Pq vi command: B
 705 Move the cursor to the left to the next beginning of a space delimited
 706 word.
 707 Can be used as a movement command after
 708 .Ic vi_change_meta ,
 709 .Ic vi_delete_meta ,
 710 or
 711 .Ic vi_yank .
 712 It is an error if the cursor is already at the beginning of the
 713 edit buffer.
 714 .It Ic vi-prev-char Pq vi command: F
 715 Read one character from the terminal bypassing the normal line
 716 editing functionality and move the cursor to the left to the next
 717 instance of that character in the edit buffer.
 718 Can be used as a movement command after
 719 .Ic vi_change_meta ,
 720 .Ic vi_delete_meta ,
 721 or
 722 .Ic vi_yank .
 723 If trying to read the character results in end of file or an error,
 724 call
 725 .Ic ed-end-of-file
 726 instead.
 727 It is an error if the character is not found searching to the left
 728 in the edit buffer.
 729 .It Ic vi-prev-word Pq vi command: b
 730 Move the cursor to the left to the next beginning of a word.
 731 Can be used as a movement command after
 732 .Ic vi_change_meta ,
 733 .Ic vi_delete_meta ,
 734 or
 735 .Ic vi_yank .
 736 It is an error if the cursor is already at the beginning of the
 737 edit buffer.
 738 .It Ic vi-redo Pq vi command: Sq \&.
 739 Redo the last non-motion command.
 740 .It Ic vi-repeat-next-char Pq vi command: Sq \&;
 741 Repeat the most recent character search in the same search direction.
 742 Can be used as a movement command after
 743 .Ic vi_change_meta ,
 744 .Ic vi_delete_meta ,
 745 or
 746 .Ic vi_yank .
 747 .It Ic vi-repeat-prev-char Pq vi command: Sq \&,
 748 Repeat the most recent character search in the opposite search
 749 direction.
 750 Can be used as a movement command after
 751 .Ic vi_change_meta ,
 752 .Ic vi_delete_meta ,
 753 or
 754 .Ic vi_yank .
 755 .It Ic vi-repeat-search-next Pq vi command: n
 756 Repeat the most recent history search in the same search direction.
 757 .It Ic vi-repeat-search-prev Pq vi command: N
 758 Repeat the most recent history search in the opposite search
 759 direction.
 760 .It Ic vi-replace-char Pq vi command: r
 761 Switch to vi replace mode, and automatically switch back to vi
 762 command mode after the next character typed.
 763 See
 764 .Ic ed-insert
 765 for a description of replace mode.
 766 It is an error if the cursor is at the end of the edit buffer.
 767 .It Ic vi-replace-mode Pq vi command: R
 768 Switch to vi replace mode.
 769 This is a variant of vi insert mode; see
 770 .Ic ed-insert
 771 for the difference.
 772 .It Ic vi-search-next Pq vi command: \&?
 773 Replace the edit buffer with the next matching history entry.
 774 .It Ic vi-search-prev Pq vi command: /
 775 Replace the edit buffer with the previous matching history entry.
 776 .It Ic vi-substitute-char Pq vi command: s
 777 Delete the character at the cursor and switch to vi insert mode.
 778 .It Ic vi-substitute-line Pq vi command: S
 779 Delete the entire contents of the edit buffer, save a copy of it
 780 in the cut buffer, and enter vi insert mode.
 781 .It Ic vi-to-column Pq vi command: \&|
 782 Move the cursor to the column specified as the argument.
 783 Can be used as a movement command after
 784 .Ic vi_change_meta ,
 785 .Ic vi_delete_meta ,
 786 or
 787 .Ic vi_yank .
 788 .It Ic vi-to-history-line Pq vi command: G
 789 Replace the edit buffer with the specified history entry.
 790 .It Ic vi-to-next-char Pq vi command: t
 791 Read one character from the terminal bypassing the normal line
 792 editing functionality and move the cursor to the right to the
 793 character before the next instance of that character in the edit
 794 buffer.
 795 Can be used as a movement command after
 796 .Ic vi_change_meta ,
 797 .Ic vi_delete_meta ,
 798 or
 799 .Ic vi_yank .
 800 If trying to read the character results in end of file or an error,
 801 call
 802 .Ic ed-end-of-file
 803 instead.
 804 It is an error if the character is not found searching to the right
 805 in the edit buffer.
 806 .It Ic vi-to-prev-char Pq vi command: T
 807 Read one character from the terminal bypassing the normal line
 808 editing functionality and move the cursor to the left to the character
 809 after the next instance of that character in the edit buffer.
 810 Can be used as a movement command after
 811 .Ic vi_change_meta ,
 812 .Ic vi_delete_meta ,
 813 or
 814 .Ic vi_yank .
 815 If trying to read the character results in end of file or an error,
 816 call
 817 .Ic ed-end-of-file
 818 instead.
 819 It is an error if the character is not found searching to the left
 820 in the edit buffer.
 821 .It Ic vi-undo Pq vi command: u
 822 Undo the last change.
 823 .It Ic vi-undo-line Pq vi command: U
 824 Undo all changes to the edit buffer.
 825 .It Ic vi-yank Pq vi command: y
 826 Copy the string from the cursor to the position specified by the
 827 following movement command to the cut buffer.
 828 When given twice in a row, instead copy the whole contents of the
 829 edit buffer to the cut buffer.
 830 .It Ic vi-yank-end Pq vi command: Y
 831 Copy the string from the cursor to the end of the edit buffer to
 832 the cut buffer.
 833 .It Ic vi-zero Pq vi command: 0
 834 If in argument input mode, multiply the argument by ten.
 835 Otherwise, move the cursor to the beginning of the edit buffer.
 836 Can be used as a movement command after
 837 .Ic vi_change_meta ,
 838 .Ic vi_delete_meta ,
 839 or
 840 .Ic vi_yank .
 841 .El
 842 .Ss Macros
 843 If an input character is bound to the editor command
 844 .Ic ed-sequence-lead-in ,
 845 .Nm
 846 attempts to call a macro.
 847 If the input character by itself forms the name of a macro, that
 848 macro is executed.
 849 Otherwise, additional input characters are read until the string
 850 read forms the name of a macro, in which case that macro is executed,
 851 or until the string read matches the beginning of none of the existing
 852 macro names, in which case the string including the final, mismatching
 853 character is discarded and the terminal bell is rung.
 854 .Pp
 855 There are two kinds of macros.
 856 Command macros execute a single editor command.
 857 Keyboard macros return a string of characters that is appended
 858 as a new line to the
 859 .Sx Input Queue .
 860 .Pp
 861 The following command macros are defined by default in vi command
 862 mode and in emacs mode:
 863 .Bl -column -offset indent "Esc O A, Esc O A" "em-exchange-mark"
 864 .It Esc \&[ A, Esc O A Ta Ic ed-prev-history
 865 .It Esc \&[ B, Esc O B Ta Ic ed-next-history
 866 .It Esc \&[ C, Esc O C Ta Ic ed-next-char
 867 .It Esc \&[ D, Esc O D Ta Ic ed-prev-char
 868 .It Esc \&[ F, Esc O F Ta Ic ed-move-to-end
 869 .It Esc \&[ H, Esc O H Ta Ic ed-move-to-beg
 870 .El
 871 .Pp
 872 In vi command mode, they are also defined by default without the
 873 initial escape character.
 874 .Pp
 875 In addition, the
 876 .Nm
 877 library tries to bind the strings generated by the arrow keys
 878 as reported by the
 879 .Xr terminfo 5
 880 database to these editor commands, unless that would clobber
 881 user settings.
 882 .Pp
 883 In emacs mode, the two-character string
 884 .Dq Ctrl-X Ctrl-X
 885 is bound to the
 886 .Ic em-exchange-mark
 887 editor command.
 888 .Ss Input Queue
 889 The
 890 .Nm
 891 library maintains an input queue operated in FIFO mode.
 892 Whenever it needs an input character, it takes the first character
 893 from the first line of the input queue.
 894 When the queue is empty, it reads from the terminal.
 895 .Pp
 896 A line can be appended to the end of the input queue in several ways:
 897 .Bl -dash -offset indent
 898 .It
 899 By calling one of the keyboard
 900 .Sx Macros .
 901 .It
 902 By calling the editor command
 903 .Ic vi-redo .
 904 .It
 905 By calling the editor command
 906 .Ic vi-alias .
 907 .It
 908 By pressing a key in emacs incremental search mode that doesn't
 909 have a special meaning in that mode but returns to normal emacs
 910 mode.
 911 .It
 912 If an application program directly calls the functions
 913 .Xr el_push 3
 914 or
 915 .Xr el_wpush 3 ,
 916 it can provide additional, program-specific ways
 917 of appending to the input queue.
 918 .El
 919 .Sh SEE ALSO
 920 .Xr mg 1 ,
 921 .Xr vi 1 ,
 922 .Xr editline 3 ,
 923 .Xr el_wgets 3 ,
 924 .Xr el_wpush 3 ,
 925 .Xr el_wset 3 ,
 926 .Xr editrc 5
 927 .Sh HISTORY
 928 This manual page first appeared in
 929 .Ox 6.0
 930 and
 931 .Nx 8 .
 932 .Sh AUTHORS
 933 .An -nosplit
 934 This manual page was written by
 935 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .