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