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