1@comment %**start of header (This is for running Texinfo on a region.) 2@setfilename rluser.info 3@comment %**end of header (This is for running Texinfo on a region.) 4 5@ignore 6This file documents the end user interface to the GNU command line 7editing features. It is to be an appendix to manuals for programs which 8use these features. There is a document entitled "readline.texinfo" 9which contains both end-user and programmer documentation for the 10GNU Readline Library. 11 12Copyright (C) 1988--2011 Free Software Foundation, Inc. 13 14Authored by Brian Fox and Chet Ramey. 15 16Permission is granted to process this file through Tex and print the 17results, provided the printed document carries copying permission notice 18identical to this one except for the removal of this paragraph (this 19paragraph not being relevant to the printed manual). 20 21Permission is granted to make and distribute verbatim copies of this manual 22provided the copyright notice and this permission notice are preserved on 23all copies. 24 25Permission is granted to copy and distribute modified versions of this 26manual under the conditions for verbatim copying, provided also that the 27GNU Copyright statement is available to the distributee, and provided that 28the entire resulting derived work is distributed under the terms of a 29permission notice identical to this one. 30 31Permission is granted to copy and distribute translations of this manual 32into another language, under the above conditions for modified versions. 33@end ignore 34 35@comment If you are including this manual as an appendix, then set the 36@comment variable readline-appendix. 37 38@ifclear BashFeatures 39@defcodeindex bt 40@end ifclear 41 42@node Command Line Editing 43@chapter Command Line Editing 44 45This chapter describes the basic features of the @sc{gnu} 46command line editing interface. 47@ifset BashFeatures 48Command line editing is provided by the Readline library, which is 49used by several different programs, including Bash. 50Command line editing is enabled by default when using an interactive shell, 51unless the @option{--noediting} option is supplied at shell invocation. 52Line editing is also used when using the @option{-e} option to the 53@code{read} builtin command (@pxref{Bash Builtins}). 54By default, the line editing commands are similar to those of Emacs. 55A vi-style line editing interface is also available. 56Line editing can be enabled at any time using the @option{-o emacs} or 57@option{-o vi} options to the @code{set} builtin command 58(@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or 59@option{+o vi} options to @code{set}. 60@end ifset 61 62@menu 63* Introduction and Notation:: Notation used in this text. 64* Readline Interaction:: The minimum set of commands for editing a line. 65* Readline Init File:: Customizing Readline from a user's view. 66* Bindable Readline Commands:: A description of most of the Readline commands 67 available for binding 68* Readline vi Mode:: A short description of how to make Readline 69 behave like the vi editor. 70@ifset BashFeatures 71* Programmable Completion:: How to specify the possible completions for 72 a specific command. 73* Programmable Completion Builtins:: Builtin commands to specify how to 74 complete arguments for a particular command. 75@end ifset 76@end menu 77 78@node Introduction and Notation 79@section Introduction to Line Editing 80 81The following paragraphs describe the notation used to represent 82keystrokes. 83 84The text @kbd{C-k} is read as `Control-K' and describes the character 85produced when the @key{k} key is pressed while the Control key 86is depressed. 87 88The text @kbd{M-k} is read as `Meta-K' and describes the character 89produced when the Meta key (if you have one) is depressed, and the @key{k} 90key is pressed. 91The Meta key is labeled @key{ALT} on many keyboards. 92On keyboards with two keys labeled @key{ALT} (usually to either side of 93the space bar), the @key{ALT} on the left side is generally set to 94work as a Meta key. 95The @key{ALT} key on the right may also be configured to work as a 96Meta key or may be configured as some other modifier, such as a 97Compose key for typing accented characters. 98 99If you do not have a Meta or @key{ALT} key, or another key working as 100a Meta key, the identical keystroke can be generated by typing @key{ESC} 101@emph{first}, and then typing @key{k}. 102Either process is known as @dfn{metafying} the @key{k} key. 103 104The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the 105character produced by @dfn{metafying} @kbd{C-k}. 106 107In addition, several keys have their own names. Specifically, 108@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all 109stand for themselves when seen in this text, or in an init file 110(@pxref{Readline Init File}). 111If your keyboard lacks a @key{LFD} key, typing @key{C-j} will 112produce the desired character. 113The @key{RET} key may be labeled @key{Return} or @key{Enter} on 114some keyboards. 115 116@node Readline Interaction 117@section Readline Interaction 118@cindex interaction, readline 119 120Often during an interactive session you type in a long line of text, 121only to notice that the first word on the line is misspelled. The 122Readline library gives you a set of commands for manipulating the text 123as you type it in, allowing you to just fix your typo, and not forcing 124you to retype the majority of the line. Using these editing commands, 125you move the cursor to the place that needs correction, and delete or 126insert the text of the corrections. Then, when you are satisfied with 127the line, you simply press @key{RET}. You do not have to be at the 128end of the line to press @key{RET}; the entire line is accepted 129regardless of the location of the cursor within the line. 130 131@menu 132* Readline Bare Essentials:: The least you need to know about Readline. 133* Readline Movement Commands:: Moving about the input line. 134* Readline Killing Commands:: How to delete text, and how to get it back! 135* Readline Arguments:: Giving numeric arguments to commands. 136* Searching:: Searching through previous lines. 137@end menu 138 139@node Readline Bare Essentials 140@subsection Readline Bare Essentials 141@cindex notation, readline 142@cindex command editing 143@cindex editing command lines 144 145In order to enter characters into the line, simply type them. The typed 146character appears where the cursor was, and then the cursor moves one 147space to the right. If you mistype a character, you can use your 148erase character to back up and delete the mistyped character. 149 150Sometimes you may mistype a character, and 151not notice the error until you have typed several other characters. In 152that case, you can type @kbd{C-b} to move the cursor to the left, and then 153correct your mistake. Afterwards, you can move the cursor to the right 154with @kbd{C-f}. 155 156When you add text in the middle of a line, you will notice that characters 157to the right of the cursor are `pushed over' to make room for the text 158that you have inserted. Likewise, when you delete text behind the cursor, 159characters to the right of the cursor are `pulled back' to fill in the 160blank space created by the removal of the text. A list of the bare 161essentials for editing the text of an input line follows. 162 163@table @asis 164@item @kbd{C-b} 165Move back one character. 166@item @kbd{C-f} 167Move forward one character. 168@item @key{DEL} or @key{Backspace} 169Delete the character to the left of the cursor. 170@item @kbd{C-d} 171Delete the character underneath the cursor. 172@item @w{Printing characters} 173Insert the character into the line at the cursor. 174@item @kbd{C-_} or @kbd{C-x C-u} 175Undo the last editing command. You can undo all the way back to an 176empty line. 177@end table 178 179@noindent 180(Depending on your configuration, the @key{Backspace} key be set to 181delete the character to the left of the cursor and the @key{DEL} key set 182to delete the character underneath the cursor, like @kbd{C-d}, rather 183than the character to the left of the cursor.) 184 185@node Readline Movement Commands 186@subsection Readline Movement Commands 187 188 189The above table describes the most basic keystrokes that you need 190in order to do editing of the input line. For your convenience, many 191other commands have been added in addition to @kbd{C-b}, @kbd{C-f}, 192@kbd{C-d}, and @key{DEL}. Here are some commands for moving more rapidly 193about the line. 194 195@table @kbd 196@item C-a 197Move to the start of the line. 198@item C-e 199Move to the end of the line. 200@item M-f 201Move forward a word, where a word is composed of letters and digits. 202@item M-b 203Move backward a word. 204@item C-l 205Clear the screen, reprinting the current line at the top. 206@end table 207 208Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves 209forward a word. It is a loose convention that control keystrokes 210operate on characters while meta keystrokes operate on words. 211 212@node Readline Killing Commands 213@subsection Readline Killing Commands 214 215@cindex killing text 216@cindex yanking text 217 218@dfn{Killing} text means to delete the text from the line, but to save 219it away for later use, usually by @dfn{yanking} (re-inserting) 220it back into the line. 221(`Cut' and `paste' are more recent jargon for `kill' and `yank'.) 222 223If the description for a command says that it `kills' text, then you can 224be sure that you can get the text back in a different (or the same) 225place later. 226 227When you use a kill command, the text is saved in a @dfn{kill-ring}. 228Any number of consecutive kills save all of the killed text together, so 229that when you yank it back, you get it all. The kill 230ring is not line specific; the text that you killed on a previously 231typed line is available to be yanked back later, when you are typing 232another line. 233@cindex kill ring 234 235Here is the list of commands for killing text. 236 237@table @kbd 238@item C-k 239Kill the text from the current cursor position to the end of the line. 240 241@item M-d 242Kill from the cursor to the end of the current word, or, if between 243words, to the end of the next word. 244Word boundaries are the same as those used by @kbd{M-f}. 245 246@item M-@key{DEL} 247Kill from the cursor the start of the current word, or, if between 248words, to the start of the previous word. 249Word boundaries are the same as those used by @kbd{M-b}. 250 251@item C-w 252Kill from the cursor to the previous whitespace. This is different than 253@kbd{M-@key{DEL}} because the word boundaries differ. 254 255@end table 256 257Here is how to @dfn{yank} the text back into the line. Yanking 258means to copy the most-recently-killed text from the kill buffer. 259 260@table @kbd 261@item C-y 262Yank the most recently killed text back into the buffer at the cursor. 263 264@item M-y 265Rotate the kill-ring, and yank the new top. You can only do this if 266the prior command is @kbd{C-y} or @kbd{M-y}. 267@end table 268 269@node Readline Arguments 270@subsection Readline Arguments 271 272You can pass numeric arguments to Readline commands. Sometimes the 273argument acts as a repeat count, other times it is the @i{sign} of the 274argument that is significant. If you pass a negative argument to a 275command which normally acts in a forward direction, that command will 276act in a backward direction. For example, to kill text back to the 277start of the line, you might type @samp{M-- C-k}. 278 279The general way to pass numeric arguments to a command is to type meta 280digits before the command. If the first `digit' typed is a minus 281sign (@samp{-}), then the sign of the argument will be negative. Once 282you have typed one meta digit to get the argument started, you can type 283the remainder of the digits, and then the command. For example, to give 284the @kbd{C-d} command an argument of 10, you could type @samp{M-1 0 C-d}, 285which will delete the next ten characters on the input line. 286 287@node Searching 288@subsection Searching for Commands in the History 289 290Readline provides commands for searching through the command history 291@ifset BashFeatures 292(@pxref{Bash History Facilities}) 293@end ifset 294for lines containing a specified string. 295There are two search modes: @dfn{incremental} and @dfn{non-incremental}. 296 297Incremental searches begin before the user has finished typing the 298search string. 299As each character of the search string is typed, Readline displays 300the next entry from the history matching the string typed so far. 301An incremental search requires only as many characters as needed to 302find the desired history entry. 303To search backward in the history for a particular string, type 304@kbd{C-r}. Typing @kbd{C-s} searches forward through the history. 305The characters present in the value of the @code{isearch-terminators} variable 306are used to terminate an incremental search. 307If that variable has not been assigned a value, the @key{ESC} and 308@kbd{C-J} characters will terminate an incremental search. 309@kbd{C-g} will abort an incremental search and restore the original line. 310When the search is terminated, the history entry containing the 311search string becomes the current line. 312 313To find other matching entries in the history list, type @kbd{C-r} or 314@kbd{C-s} as appropriate. 315This will search backward or forward in the history for the next 316entry matching the search string typed so far. 317Any other key sequence bound to a Readline command will terminate 318the search and execute that command. 319For instance, a @key{RET} will terminate the search and accept 320the line, thereby executing the command from the history list. 321A movement command will terminate the search, make the last line found 322the current line, and begin editing. 323 324Readline remembers the last incremental search string. If two 325@kbd{C-r}s are typed without any intervening characters defining a new 326search string, any remembered search string is used. 327 328Non-incremental searches read the entire search string before starting 329to search for matching history lines. The search string may be 330typed by the user or be part of the contents of the current line. 331 332@node Readline Init File 333@section Readline Init File 334@cindex initialization file, readline 335 336Although the Readline library comes with a set of Emacs-like 337keybindings installed by default, it is possible to use a different set 338of keybindings. 339Any user can customize programs that use Readline by putting 340commands in an @dfn{inputrc} file, conventionally in his home directory. 341The name of this 342@ifset BashFeatures 343file is taken from the value of the shell variable @env{INPUTRC}. If 344@end ifset 345@ifclear BashFeatures 346file is taken from the value of the environment variable @env{INPUTRC}. If 347@end ifclear 348that variable is unset, the default is @file{~/.inputrc}. If that 349file does not exist or cannot be read, the ultimate default is 350@file{/etc/inputrc}. 351 352When a program which uses the Readline library starts up, the 353init file is read, and the key bindings are set. 354 355In addition, the @code{C-x C-r} command re-reads this init file, thus 356incorporating any changes that you might have made to it. 357 358@menu 359* Readline Init File Syntax:: Syntax for the commands in the inputrc file. 360 361* Conditional Init Constructs:: Conditional key bindings in the inputrc file. 362 363* Sample Init File:: An example inputrc file. 364@end menu 365 366@node Readline Init File Syntax 367@subsection Readline Init File Syntax 368 369There are only a few basic constructs allowed in the 370Readline init file. Blank lines are ignored. 371Lines beginning with a @samp{#} are comments. 372Lines beginning with a @samp{$} indicate conditional 373constructs (@pxref{Conditional Init Constructs}). Other lines 374denote variable settings and key bindings. 375 376@table @asis 377@item Variable Settings 378You can modify the run-time behavior of Readline by 379altering the values of variables in Readline 380using the @code{set} command within the init file. 381The syntax is simple: 382 383@example 384set @var{variable} @var{value} 385@end example 386 387@noindent 388Here, for example, is how to 389change from the default Emacs-like key binding to use 390@code{vi} line editing commands: 391 392@example 393set editing-mode vi 394@end example 395 396Variable names and values, where appropriate, are recognized without regard 397to case. Unrecognized variable names are ignored. 398 399Boolean variables (those that can be set to on or off) are set to on if 400the value is null or empty, @var{on} (case-insensitive), or 1. Any other 401value results in the variable being set to off. 402 403@ifset BashFeatures 404The @w{@code{bind -V}} command lists the current Readline variable names 405and values. @xref{Bash Builtins}. 406@end ifset 407 408A great deal of run-time behavior is changeable with the following 409variables. 410 411@cindex variables, readline 412@table @code 413 414@item bell-style 415@vindex bell-style 416Controls what happens when Readline wants to ring the terminal bell. 417If set to @samp{none}, Readline never rings the bell. If set to 418@samp{visible}, Readline uses a visible bell if one is available. 419If set to @samp{audible} (the default), Readline attempts to ring 420the terminal's bell. 421 422@item bind-tty-special-chars 423@vindex bind-tty-special-chars 424If set to @samp{on}, Readline attempts to bind the control characters 425treated specially by the kernel's terminal driver to their Readline 426equivalents. 427 428@item comment-begin 429@vindex comment-begin 430The string to insert at the beginning of the line when the 431@code{insert-comment} command is executed. The default value 432is @code{"#"}. 433 434@item completion-display-width 435@vindex completion-display-width 436The number of screen columns used to display possible matches 437when performing completion. 438The value is ignored if it is less than 0 or greater than the terminal 439screen width. 440A value of 0 will cause matches to be displayed one per line. 441The default value is -1. 442 443@item completion-ignore-case 444@vindex completion-ignore-case 445If set to @samp{on}, Readline performs filename matching and completion 446in a case-insensitive fashion. 447The default value is @samp{off}. 448 449@item completion-map-case 450@vindex completion-map-case 451If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline 452treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when 453performing case-insensitive filename matching and completion. 454 455@item completion-prefix-display-length 456@vindex completion-prefix-display-length 457The length in characters of the common prefix of a list of possible 458completions that is displayed without modification. When set to a 459value greater than zero, common prefixes longer than this value are 460replaced with an ellipsis when displaying possible completions. 461 462@item completion-query-items 463@vindex completion-query-items 464The number of possible completions that determines when the user is 465asked whether the list of possibilities should be displayed. 466If the number of possible completions is greater than this value, 467Readline will ask the user whether or not he wishes to view 468them; otherwise, they are simply listed. 469This variable must be set to an integer value greater than or equal to 0. 470A negative value means Readline should never ask. 471The default limit is @code{100}. 472 473@item convert-meta 474@vindex convert-meta 475If set to @samp{on}, Readline will convert characters with the 476eighth bit set to an @sc{ascii} key sequence by stripping the eighth 477bit and prefixing an @key{ESC} character, converting them to a 478meta-prefixed key sequence. The default value is @samp{on}. 479 480@item disable-completion 481@vindex disable-completion 482If set to @samp{On}, Readline will inhibit word completion. 483Completion characters will be inserted into the line as if they had 484been mapped to @code{self-insert}. The default is @samp{off}. 485 486@item editing-mode 487@vindex editing-mode 488The @code{editing-mode} variable controls which default set of 489key bindings is used. By default, Readline starts up in Emacs editing 490mode, where the keystrokes are most similar to Emacs. This variable can be 491set to either @samp{emacs} or @samp{vi}. 492 493@item echo-control-characters 494When set to @samp{on}, on operating systems that indicate they support it, 495readline echoes a character corresponding to a signal generated from the 496keyboard. The default is @samp{on}. 497 498@item enable-keypad 499@vindex enable-keypad 500When set to @samp{on}, Readline will try to enable the application 501keypad when it is called. Some systems need this to enable the 502arrow keys. The default is @samp{off}. 503 504@item enable-meta-key 505When set to @samp{on}, Readline will try to enable any meta modifier 506key the terminal claims to support when it is called. On many terminals, 507the meta key is used to send eight-bit characters. 508The default is @samp{on}. 509 510@item expand-tilde 511@vindex expand-tilde 512If set to @samp{on}, tilde expansion is performed when Readline 513attempts word completion. The default is @samp{off}. 514 515@item history-preserve-point 516@vindex history-preserve-point 517If set to @samp{on}, the history code attempts to place the point (the 518current cursor position) at the 519same location on each history line retrieved with @code{previous-history} 520or @code{next-history}. The default is @samp{off}. 521 522@item history-size 523@vindex history-size 524Set the maximum number of history entries saved in the history list. If 525set to zero, the number of entries in the history list is not limited. 526 527@item horizontal-scroll-mode 528@vindex horizontal-scroll-mode 529This variable can be set to either @samp{on} or @samp{off}. Setting it 530to @samp{on} means that the text of the lines being edited will scroll 531horizontally on a single screen line when they are longer than the width 532of the screen, instead of wrapping onto a new screen line. By default, 533this variable is set to @samp{off}. 534 535@item input-meta 536@vindex input-meta 537@vindex meta-flag 538If set to @samp{on}, Readline will enable eight-bit input (it 539will not clear the eighth bit in the characters it reads), 540regardless of what the terminal claims it can support. The 541default value is @samp{off}. The name @code{meta-flag} is a 542synonym for this variable. 543 544@item isearch-terminators 545@vindex isearch-terminators 546The string of characters that should terminate an incremental search without 547subsequently executing the character as a command (@pxref{Searching}). 548If this variable has not been given a value, the characters @key{ESC} and 549@kbd{C-J} will terminate an incremental search. 550 551@item keymap 552@vindex keymap 553Sets Readline's idea of the current keymap for key binding commands. 554Acceptable @code{keymap} names are 555@code{emacs}, 556@code{emacs-standard}, 557@code{emacs-meta}, 558@code{emacs-ctlx}, 559@code{vi}, 560@code{vi-move}, 561@code{vi-command}, and 562@code{vi-insert}. 563@code{vi} is equivalent to @code{vi-command}; @code{emacs} is 564equivalent to @code{emacs-standard}. The default value is @code{emacs}. 565The value of the @code{editing-mode} variable also affects the 566default keymap. 567 568@item mark-directories 569If set to @samp{on}, completed directory names have a slash 570appended. The default is @samp{on}. 571 572@item mark-modified-lines 573@vindex mark-modified-lines 574This variable, when set to @samp{on}, causes Readline to display an 575asterisk (@samp{*}) at the start of history lines which have been modified. 576This variable is @samp{off} by default. 577 578@item mark-symlinked-directories 579@vindex mark-symlinked-directories 580If set to @samp{on}, completed names which are symbolic links 581to directories have a slash appended (subject to the value of 582@code{mark-directories}). 583The default is @samp{off}. 584 585@item match-hidden-files 586@vindex match-hidden-files 587This variable, when set to @samp{on}, causes Readline to match files whose 588names begin with a @samp{.} (hidden files) when performing filename 589completion. 590If set to @samp{off}, the leading @samp{.} must be 591supplied by the user in the filename to be completed. 592This variable is @samp{on} by default. 593 594@item menu-complete-display-prefix 595@vindex menu-complete-display-prefix 596If set to @samp{on}, menu completion displays the common prefix of the 597list of possible completions (which may be empty) before cycling through 598the list. The default is @samp{off}. 599 600@item output-meta 601@vindex output-meta 602If set to @samp{on}, Readline will display characters with the 603eighth bit set directly rather than as a meta-prefixed escape 604sequence. The default is @samp{off}. 605 606@item page-completions 607@vindex page-completions 608If set to @samp{on}, Readline uses an internal @code{more}-like pager 609to display a screenful of possible completions at a time. 610This variable is @samp{on} by default. 611 612@item print-completions-horizontally 613If set to @samp{on}, Readline will display completions with matches 614sorted horizontally in alphabetical order, rather than down the screen. 615The default is @samp{off}. 616 617@item revert-all-at-newline 618@vindex revert-all-at-newline 619If set to @samp{on}, Readline will undo all changes to history lines 620before returning when @code{accept-line} is executed. By default, 621history lines may be modified and retain individual undo lists across 622calls to @code{readline}. The default is @samp{off}. 623 624@item show-all-if-ambiguous 625@vindex show-all-if-ambiguous 626This alters the default behavior of the completion functions. If 627set to @samp{on}, 628words which have more than one possible completion cause the 629matches to be listed immediately instead of ringing the bell. 630The default value is @samp{off}. 631 632@item show-all-if-unmodified 633@vindex show-all-if-unmodified 634This alters the default behavior of the completion functions in 635a fashion similar to @var{show-all-if-ambiguous}. 636If set to @samp{on}, 637words which have more than one possible completion without any 638possible partial completion (the possible completions don't share 639a common prefix) cause the matches to be listed immediately instead 640of ringing the bell. 641The default value is @samp{off}. 642 643@item skip-completed-text 644@vindex skip-completed-text 645If set to @samp{on}, this alters the default completion behavior when 646inserting a single match into the line. It's only active when 647performing completion in the middle of a word. If enabled, readline 648does not insert characters from the completion that match characters 649after point in the word being completed, so portions of the word 650following the cursor are not duplicated. 651For instance, if this is enabled, attempting completion when the cursor 652is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile} 653rather than @samp{Makefilefile}, assuming there is a single possible 654completion. 655The default value is @samp{off}. 656 657@item visible-stats 658@vindex visible-stats 659If set to @samp{on}, a character denoting a file's type 660is appended to the filename when listing possible 661completions. The default is @samp{off}. 662 663@end table 664 665@item Key Bindings 666The syntax for controlling key bindings in the init file is 667simple. First you need to find the name of the command that you 668want to change. The following sections contain tables of the command 669name, the default keybinding, if any, and a short description of what 670the command does. 671 672Once you know the name of the command, simply place on a line 673in the init file the name of the key 674you wish to bind the command to, a colon, and then the name of the 675command. 676There can be no space between the key name and the colon -- that will be 677interpreted as part of the key name. 678The name of the key can be expressed in different ways, depending on 679what you find most comfortable. 680 681In addition to command names, readline allows keys to be bound 682to a string that is inserted when the key is pressed (a @var{macro}). 683 684@ifset BashFeatures 685The @w{@code{bind -p}} command displays Readline function names and 686bindings in a format that can put directly into an initialization file. 687@xref{Bash Builtins}. 688@end ifset 689 690@table @asis 691@item @w{@var{keyname}: @var{function-name} or @var{macro}} 692@var{keyname} is the name of a key spelled out in English. For example: 693@example 694Control-u: universal-argument 695Meta-Rubout: backward-kill-word 696Control-o: "> output" 697@end example 698 699In the above example, @kbd{C-u} is bound to the function 700@code{universal-argument}, 701@kbd{M-DEL} is bound to the function @code{backward-kill-word}, and 702@kbd{C-o} is bound to run the macro 703expressed on the right hand side (that is, to insert the text 704@samp{> output} into the line). 705 706A number of symbolic character names are recognized while 707processing this key binding syntax: 708@var{DEL}, 709@var{ESC}, 710@var{ESCAPE}, 711@var{LFD}, 712@var{NEWLINE}, 713@var{RET}, 714@var{RETURN}, 715@var{RUBOUT}, 716@var{SPACE}, 717@var{SPC}, 718and 719@var{TAB}. 720 721@item @w{"@var{keyseq}": @var{function-name} or @var{macro}} 722@var{keyseq} differs from @var{keyname} above in that strings 723denoting an entire key sequence can be specified, by placing 724the key sequence in double quotes. Some @sc{gnu} Emacs style key 725escapes can be used, as in the following example, but the 726special character names are not recognized. 727 728@example 729"\C-u": universal-argument 730"\C-x\C-r": re-read-init-file 731"\e[11~": "Function Key 1" 732@end example 733 734In the above example, @kbd{C-u} is again bound to the function 735@code{universal-argument} (just as it was in the first example), 736@samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file}, 737and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert 738the text @samp{Function Key 1}. 739 740@end table 741 742The following @sc{gnu} Emacs style escape sequences are available when 743specifying key sequences: 744 745@table @code 746@item @kbd{\C-} 747control prefix 748@item @kbd{\M-} 749meta prefix 750@item @kbd{\e} 751an escape character 752@item @kbd{\\} 753backslash 754@item @kbd{\"} 755@key{"}, a double quotation mark 756@item @kbd{\'} 757@key{'}, a single quote or apostrophe 758@end table 759 760In addition to the @sc{gnu} Emacs style escape sequences, a second 761set of backslash escapes is available: 762 763@table @code 764@item \a 765alert (bell) 766@item \b 767backspace 768@item \d 769delete 770@item \f 771form feed 772@item \n 773newline 774@item \r 775carriage return 776@item \t 777horizontal tab 778@item \v 779vertical tab 780@item \@var{nnn} 781the eight-bit character whose value is the octal value @var{nnn} 782(one to three digits) 783@item \x@var{HH} 784the eight-bit character whose value is the hexadecimal value @var{HH} 785(one or two hex digits) 786@end table 787 788When entering the text of a macro, single or double quotes must 789be used to indicate a macro definition. 790Unquoted text is assumed to be a function name. 791In the macro body, the backslash escapes described above are expanded. 792Backslash will quote any other character in the macro text, 793including @samp{"} and @samp{'}. 794For example, the following binding will make @samp{@kbd{C-x} \} 795insert a single @samp{\} into the line: 796@example 797"\C-x\\": "\\" 798@end example 799 800@end table 801 802@node Conditional Init Constructs 803@subsection Conditional Init Constructs 804 805Readline implements a facility similar in spirit to the conditional 806compilation features of the C preprocessor which allows key 807bindings and variable settings to be performed as the result 808of tests. There are four parser directives used. 809 810@table @code 811@item $if 812The @code{$if} construct allows bindings to be made based on the 813editing mode, the terminal being used, or the application using 814Readline. The text of the test extends to the end of the line; 815no characters are required to isolate it. 816 817@table @code 818@item mode 819The @code{mode=} form of the @code{$if} directive is used to test 820whether Readline is in @code{emacs} or @code{vi} mode. 821This may be used in conjunction 822with the @samp{set keymap} command, for instance, to set bindings in 823the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if 824Readline is starting out in @code{emacs} mode. 825 826@item term 827The @code{term=} form may be used to include terminal-specific 828key bindings, perhaps to bind the key sequences output by the 829terminal's function keys. The word on the right side of the 830@samp{=} is tested against both the full name of the terminal and 831the portion of the terminal name before the first @samp{-}. This 832allows @code{sun} to match both @code{sun} and @code{sun-cmd}, 833for instance. 834 835@item application 836The @var{application} construct is used to include 837application-specific settings. Each program using the Readline 838library sets the @var{application name}, and you can test for 839a particular value. 840This could be used to bind key sequences to functions useful for 841a specific program. For instance, the following command adds a 842key sequence that quotes the current or previous word in Bash: 843@example 844$if Bash 845# Quote the current or previous word 846"\C-xq": "\eb\"\ef\"" 847$endif 848@end example 849@end table 850 851@item $endif 852This command, as seen in the previous example, terminates an 853@code{$if} command. 854 855@item $else 856Commands in this branch of the @code{$if} directive are executed if 857the test fails. 858 859@item $include 860This directive takes a single filename as an argument and reads commands 861and bindings from that file. 862For example, the following directive reads from @file{/etc/inputrc}: 863@example 864$include /etc/inputrc 865@end example 866@end table 867 868@node Sample Init File 869@subsection Sample Init File 870 871Here is an example of an @var{inputrc} file. This illustrates key 872binding, variable assignment, and conditional syntax. 873 874@example 875@page 876# This file controls the behaviour of line input editing for 877# programs that use the GNU Readline library. Existing 878# programs include FTP, Bash, and GDB. 879# 880# You can re-read the inputrc file with C-x C-r. 881# Lines beginning with '#' are comments. 882# 883# First, include any systemwide bindings and variable 884# assignments from /etc/Inputrc 885$include /etc/Inputrc 886 887# 888# Set various bindings for emacs mode. 889 890set editing-mode emacs 891 892$if mode=emacs 893 894Meta-Control-h: backward-kill-word Text after the function name is ignored 895 896# 897# Arrow keys in keypad mode 898# 899#"\M-OD": backward-char 900#"\M-OC": forward-char 901#"\M-OA": previous-history 902#"\M-OB": next-history 903# 904# Arrow keys in ANSI mode 905# 906"\M-[D": backward-char 907"\M-[C": forward-char 908"\M-[A": previous-history 909"\M-[B": next-history 910# 911# Arrow keys in 8 bit keypad mode 912# 913#"\M-\C-OD": backward-char 914#"\M-\C-OC": forward-char 915#"\M-\C-OA": previous-history 916#"\M-\C-OB": next-history 917# 918# Arrow keys in 8 bit ANSI mode 919# 920#"\M-\C-[D": backward-char 921#"\M-\C-[C": forward-char 922#"\M-\C-[A": previous-history 923#"\M-\C-[B": next-history 924 925C-q: quoted-insert 926 927$endif 928 929# An old-style binding. This happens to be the default. 930TAB: complete 931 932# Macros that are convenient for shell interaction 933$if Bash 934# edit the path 935"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f" 936# prepare to type a quoted word -- 937# insert open and close double quotes 938# and move to just after the open quote 939"\C-x\"": "\"\"\C-b" 940# insert a backslash (testing backslash escapes 941# in sequences and macros) 942"\C-x\\": "\\" 943# Quote the current or previous word 944"\C-xq": "\eb\"\ef\"" 945# Add a binding to refresh the line, which is unbound 946"\C-xr": redraw-current-line 947# Edit variable on current line. 948"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" 949$endif 950 951# use a visible bell if one is available 952set bell-style visible 953 954# don't strip characters to 7 bits when reading 955set input-meta on 956 957# allow iso-latin1 characters to be inserted rather 958# than converted to prefix-meta sequences 959set convert-meta off 960 961# display characters with the eighth bit set directly 962# rather than as meta-prefixed characters 963set output-meta on 964 965# if there are more than 150 possible completions for 966# a word, ask the user if he wants to see all of them 967set completion-query-items 150 968 969# For FTP 970$if Ftp 971"\C-xg": "get \M-?" 972"\C-xt": "put \M-?" 973"\M-.": yank-last-arg 974$endif 975@end example 976 977@node Bindable Readline Commands 978@section Bindable Readline Commands 979 980@menu 981* Commands For Moving:: Moving about the line. 982* Commands For History:: Getting at previous lines. 983* Commands For Text:: Commands for changing text. 984* Commands For Killing:: Commands for killing and yanking. 985* Numeric Arguments:: Specifying numeric arguments, repeat counts. 986* Commands For Completion:: Getting Readline to do the typing for you. 987* Keyboard Macros:: Saving and re-executing typed characters 988* Miscellaneous Commands:: Other miscellaneous commands. 989@end menu 990 991This section describes Readline commands that may be bound to key 992sequences. 993@ifset BashFeatures 994You can list your key bindings by executing 995@w{@code{bind -P}} or, for a more terse format, suitable for an 996@var{inputrc} file, @w{@code{bind -p}}. (@xref{Bash Builtins}.) 997@end ifset 998Command names without an accompanying key sequence are unbound by default. 999 1000In the following descriptions, @dfn{point} refers to the current cursor 1001position, and @dfn{mark} refers to a cursor position saved by the 1002@code{set-mark} command. 1003The text between the point and mark is referred to as the @dfn{region}. 1004 1005@node Commands For Moving 1006@subsection Commands For Moving 1007@ftable @code 1008@item beginning-of-line (C-a) 1009Move to the start of the current line. 1010 1011@item end-of-line (C-e) 1012Move to the end of the line. 1013 1014@item forward-char (C-f) 1015Move forward a character. 1016 1017@item backward-char (C-b) 1018Move back a character. 1019 1020@item forward-word (M-f) 1021Move forward to the end of the next word. 1022Words are composed of letters and digits. 1023 1024@item backward-word (M-b) 1025Move back to the start of the current or previous word. 1026Words are composed of letters and digits. 1027 1028@ifset BashFeatures 1029@item shell-forward-word () 1030Move forward to the end of the next word. 1031Words are delimited by non-quoted shell metacharacters. 1032 1033@item shell-backward-word () 1034Move back to the start of the current or previous word. 1035Words are delimited by non-quoted shell metacharacters. 1036@end ifset 1037 1038@item clear-screen (C-l) 1039Clear the screen and redraw the current line, 1040leaving the current line at the top of the screen. 1041 1042@item redraw-current-line () 1043Refresh the current line. By default, this is unbound. 1044 1045@end ftable 1046 1047@node Commands For History 1048@subsection Commands For Manipulating The History 1049 1050@ftable @code 1051@item accept-line (Newline or Return) 1052@ifset BashFeatures 1053Accept the line regardless of where the cursor is. 1054If this line is 1055non-empty, add it to the history list according to the setting of 1056the @env{HISTCONTROL} and @env{HISTIGNORE} variables. 1057If this line is a modified history line, then restore the history line 1058to its original state. 1059@end ifset 1060@ifclear BashFeatures 1061Accept the line regardless of where the cursor is. 1062If this line is 1063non-empty, it may be added to the history list for future recall with 1064@code{add_history()}. 1065If this line is a modified history line, the history line is restored 1066to its original state. 1067@end ifclear 1068 1069@item previous-history (C-p) 1070Move `back' through the history list, fetching the previous command. 1071 1072@item next-history (C-n) 1073Move `forward' through the history list, fetching the next command. 1074 1075@item beginning-of-history (M-<) 1076Move to the first line in the history. 1077 1078@item end-of-history (M->) 1079Move to the end of the input history, i.e., the line currently 1080being entered. 1081 1082@item reverse-search-history (C-r) 1083Search backward starting at the current line and moving `up' through 1084the history as necessary. This is an incremental search. 1085 1086@item forward-search-history (C-s) 1087Search forward starting at the current line and moving `down' through 1088the the history as necessary. This is an incremental search. 1089 1090@item non-incremental-reverse-search-history (M-p) 1091Search backward starting at the current line and moving `up' 1092through the history as necessary using a non-incremental search 1093for a string supplied by the user. 1094 1095@item non-incremental-forward-search-history (M-n) 1096Search forward starting at the current line and moving `down' 1097through the the history as necessary using a non-incremental search 1098for a string supplied by the user. 1099 1100@item history-search-forward () 1101Search forward through the history for the string of characters 1102between the start of the current line and the point. 1103This is a non-incremental search. 1104By default, this command is unbound. 1105 1106@item history-search-backward () 1107Search backward through the history for the string of characters 1108between the start of the current line and the point. This 1109is a non-incremental search. By default, this command is unbound. 1110 1111@item yank-nth-arg (M-C-y) 1112Insert the first argument to the previous command (usually 1113the second word on the previous line) at point. 1114With an argument @var{n}, 1115insert the @var{n}th word from the previous command (the words 1116in the previous command begin with word 0). A negative argument 1117inserts the @var{n}th word from the end of the previous command. 1118Once the argument @var{n} is computed, the argument is extracted 1119as if the @samp{!@var{n}} history expansion had been specified. 1120 1121@item yank-last-arg (M-. or M-_) 1122Insert last argument to the previous command (the last word of the 1123previous history entry). 1124With a numeric argument, behave exactly like @code{yank-nth-arg}. 1125Successive calls to @code{yank-last-arg} move back through the history 1126list, inserting the last word (or the word specified by the argument to 1127the first call) of each line in turn. 1128Any numeric argument supplied to these successive calls determines 1129the direction to move through the history. A negative argument switches 1130the direction through the history (back or forward). 1131The history expansion facilities are used to extract the last argument, 1132as if the @samp{!$} history expansion had been specified. 1133 1134@end ftable 1135 1136@node Commands For Text 1137@subsection Commands For Changing Text 1138 1139@ftable @code 1140@item delete-char (C-d) 1141Delete the character at point. If point is at the 1142beginning of the line, there are no characters in the line, and 1143the last character typed was not bound to @code{delete-char}, then 1144return @sc{eof}. 1145 1146@item backward-delete-char (Rubout) 1147Delete the character behind the cursor. A numeric argument means 1148to kill the characters instead of deleting them. 1149 1150@item forward-backward-delete-char () 1151Delete the character under the cursor, unless the cursor is at the 1152end of the line, in which case the character behind the cursor is 1153deleted. By default, this is not bound to a key. 1154 1155@item quoted-insert (C-q or C-v) 1156Add the next character typed to the line verbatim. This is 1157how to insert key sequences like @kbd{C-q}, for example. 1158 1159@ifclear BashFeatures 1160@item tab-insert (M-@key{TAB}) 1161Insert a tab character. 1162@end ifclear 1163 1164@item self-insert (a, b, A, 1, !, @dots{}) 1165Insert yourself. 1166 1167@item transpose-chars (C-t) 1168Drag the character before the cursor forward over 1169the character at the cursor, moving the 1170cursor forward as well. If the insertion point 1171is at the end of the line, then this 1172transposes the last two characters of the line. 1173Negative arguments have no effect. 1174 1175@item transpose-words (M-t) 1176Drag the word before point past the word after point, 1177moving point past that word as well. 1178If the insertion point is at the end of the line, this transposes 1179the last two words on the line. 1180 1181@item upcase-word (M-u) 1182Uppercase the current (or following) word. With a negative argument, 1183uppercase the previous word, but do not move the cursor. 1184 1185@item downcase-word (M-l) 1186Lowercase the current (or following) word. With a negative argument, 1187lowercase the previous word, but do not move the cursor. 1188 1189@item capitalize-word (M-c) 1190Capitalize the current (or following) word. With a negative argument, 1191capitalize the previous word, but do not move the cursor. 1192 1193@item overwrite-mode () 1194Toggle overwrite mode. With an explicit positive numeric argument, 1195switches to overwrite mode. With an explicit non-positive numeric 1196argument, switches to insert mode. This command affects only 1197@code{emacs} mode; @code{vi} mode does overwrite differently. 1198Each call to @code{readline()} starts in insert mode. 1199 1200In overwrite mode, characters bound to @code{self-insert} replace 1201the text at point rather than pushing the text to the right. 1202Characters bound to @code{backward-delete-char} replace the character 1203before point with a space. 1204 1205By default, this command is unbound. 1206 1207@end ftable 1208 1209@node Commands For Killing 1210@subsection Killing And Yanking 1211 1212@ftable @code 1213 1214@item kill-line (C-k) 1215Kill the text from point to the end of the line. 1216 1217@item backward-kill-line (C-x Rubout) 1218Kill backward to the beginning of the line. 1219 1220@item unix-line-discard (C-u) 1221Kill backward from the cursor to the beginning of the current line. 1222 1223@item kill-whole-line () 1224Kill all characters on the current line, no matter where point is. 1225By default, this is unbound. 1226 1227@item kill-word (M-d) 1228Kill from point to the end of the current word, or if between 1229words, to the end of the next word. 1230Word boundaries are the same as @code{forward-word}. 1231 1232@item backward-kill-word (M-@key{DEL}) 1233Kill the word behind point. 1234Word boundaries are the same as @code{backward-word}. 1235 1236@ifset BashFeatures 1237@item shell-kill-word () 1238Kill from point to the end of the current word, or if between 1239words, to the end of the next word. 1240Word boundaries are the same as @code{shell-forward-word}. 1241 1242@item shell-backward-kill-word () 1243Kill the word behind point. 1244Word boundaries are the same as @code{shell-backward-word}. 1245@end ifset 1246 1247@item unix-word-rubout (C-w) 1248Kill the word behind point, using white space as a word boundary. 1249The killed text is saved on the kill-ring. 1250 1251@item unix-filename-rubout () 1252Kill the word behind point, using white space and the slash character 1253as the word boundaries. 1254The killed text is saved on the kill-ring. 1255 1256@item delete-horizontal-space () 1257Delete all spaces and tabs around point. By default, this is unbound. 1258 1259@item kill-region () 1260Kill the text in the current region. 1261By default, this command is unbound. 1262 1263@item copy-region-as-kill () 1264Copy the text in the region to the kill buffer, so it can be yanked 1265right away. By default, this command is unbound. 1266 1267@item copy-backward-word () 1268Copy the word before point to the kill buffer. 1269The word boundaries are the same as @code{backward-word}. 1270By default, this command is unbound. 1271 1272@item copy-forward-word () 1273Copy the word following point to the kill buffer. 1274The word boundaries are the same as @code{forward-word}. 1275By default, this command is unbound. 1276 1277@item yank (C-y) 1278Yank the top of the kill ring into the buffer at point. 1279 1280@item yank-pop (M-y) 1281Rotate the kill-ring, and yank the new top. You can only do this if 1282the prior command is @code{yank} or @code{yank-pop}. 1283@end ftable 1284 1285@node Numeric Arguments 1286@subsection Specifying Numeric Arguments 1287@ftable @code 1288 1289@item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--}) 1290Add this digit to the argument already accumulating, or start a new 1291argument. @kbd{M--} starts a negative argument. 1292 1293@item universal-argument () 1294This is another way to specify an argument. 1295If this command is followed by one or more digits, optionally with a 1296leading minus sign, those digits define the argument. 1297If the command is followed by digits, executing @code{universal-argument} 1298again ends the numeric argument, but is otherwise ignored. 1299As a special case, if this command is immediately followed by a 1300character that is neither a digit or minus sign, the argument count 1301for the next command is multiplied by four. 1302The argument count is initially one, so executing this function the 1303first time makes the argument count four, a second time makes the 1304argument count sixteen, and so on. 1305By default, this is not bound to a key. 1306@end ftable 1307 1308@node Commands For Completion 1309@subsection Letting Readline Type For You 1310 1311@ftable @code 1312@item complete (@key{TAB}) 1313Attempt to perform completion on the text before point. 1314The actual completion performed is application-specific. 1315@ifset BashFeatures 1316Bash attempts completion treating the text as a variable (if the 1317text begins with @samp{$}), username (if the text begins with 1318@samp{~}), hostname (if the text begins with @samp{@@}), or 1319command (including aliases and functions) in turn. If none 1320of these produces a match, filename completion is attempted. 1321@end ifset 1322@ifclear BashFeatures 1323The default is filename completion. 1324@end ifclear 1325 1326@item possible-completions (M-?) 1327List the possible completions of the text before point. 1328When displaying completions, Readline sets the number of columns used 1329for display to the value of @code{completion-display-width}, the value of 1330the environment variable @env{COLUMNS}, or the screen width, in that order. 1331 1332@item insert-completions (M-*) 1333Insert all completions of the text before point that would have 1334been generated by @code{possible-completions}. 1335 1336@item menu-complete () 1337Similar to @code{complete}, but replaces the word to be completed 1338with a single match from the list of possible completions. 1339Repeated execution of @code{menu-complete} steps through the list 1340of possible completions, inserting each match in turn. 1341At the end of the list of completions, the bell is rung 1342(subject to the setting of @code{bell-style}) 1343and the original text is restored. 1344An argument of @var{n} moves @var{n} positions forward in the list 1345of matches; a negative argument may be used to move backward 1346through the list. 1347This command is intended to be bound to @key{TAB}, but is unbound 1348by default. 1349 1350@item menu-complete-backward () 1351Identical to @code{menu-complete}, but moves backward through the list 1352of possible completions, as if @code{menu-complete} had been given a 1353negative argument. 1354 1355@item delete-char-or-list () 1356Deletes the character under the cursor if not at the beginning or 1357end of the line (like @code{delete-char}). 1358If at the end of the line, behaves identically to 1359@code{possible-completions}. 1360This command is unbound by default. 1361 1362@ifset BashFeatures 1363@item complete-filename (M-/) 1364Attempt filename completion on the text before point. 1365 1366@item possible-filename-completions (C-x /) 1367List the possible completions of the text before point, 1368treating it as a filename. 1369 1370@item complete-username (M-~) 1371Attempt completion on the text before point, treating 1372it as a username. 1373 1374@item possible-username-completions (C-x ~) 1375List the possible completions of the text before point, 1376treating it as a username. 1377 1378@item complete-variable (M-$) 1379Attempt completion on the text before point, treating 1380it as a shell variable. 1381 1382@item possible-variable-completions (C-x $) 1383List the possible completions of the text before point, 1384treating it as a shell variable. 1385 1386@item complete-hostname (M-@@) 1387Attempt completion on the text before point, treating 1388it as a hostname. 1389 1390@item possible-hostname-completions (C-x @@) 1391List the possible completions of the text before point, 1392treating it as a hostname. 1393 1394@item complete-command (M-!) 1395Attempt completion on the text before point, treating 1396it as a command name. Command completion attempts to 1397match the text against aliases, reserved words, shell 1398functions, shell builtins, and finally executable filenames, 1399in that order. 1400 1401@item possible-command-completions (C-x !) 1402List the possible completions of the text before point, 1403treating it as a command name. 1404 1405@item dynamic-complete-history (M-@key{TAB}) 1406Attempt completion on the text before point, comparing 1407the text against lines from the history list for possible 1408completion matches. 1409 1410@item dabbrev-expand () 1411Attempt menu completion on the text before point, comparing 1412the text against lines from the history list for possible 1413completion matches. 1414 1415@item complete-into-braces (M-@{) 1416Perform filename completion and insert the list of possible completions 1417enclosed within braces so the list is available to the shell 1418(@pxref{Brace Expansion}). 1419 1420@end ifset 1421@end ftable 1422 1423@node Keyboard Macros 1424@subsection Keyboard Macros 1425@ftable @code 1426 1427@item start-kbd-macro (C-x () 1428Begin saving the characters typed into the current keyboard macro. 1429 1430@item end-kbd-macro (C-x )) 1431Stop saving the characters typed into the current keyboard macro 1432and save the definition. 1433 1434@item call-last-kbd-macro (C-x e) 1435Re-execute the last keyboard macro defined, by making the characters 1436in the macro appear as if typed at the keyboard. 1437 1438@end ftable 1439 1440@node Miscellaneous Commands 1441@subsection Some Miscellaneous Commands 1442@ftable @code 1443 1444@item re-read-init-file (C-x C-r) 1445Read in the contents of the @var{inputrc} file, and incorporate 1446any bindings or variable assignments found there. 1447 1448@item abort (C-g) 1449Abort the current editing command and 1450ring the terminal's bell (subject to the setting of 1451@code{bell-style}). 1452 1453@item do-uppercase-version (M-a, M-b, M-@var{x}, @dots{}) 1454If the metafied character @var{x} is lowercase, run the command 1455that is bound to the corresponding uppercase character. 1456 1457@item prefix-meta (@key{ESC}) 1458Metafy the next character typed. This is for keyboards 1459without a meta key. Typing @samp{@key{ESC} f} is equivalent to typing 1460@kbd{M-f}. 1461 1462@item undo (C-_ or C-x C-u) 1463Incremental undo, separately remembered for each line. 1464 1465@item revert-line (M-r) 1466Undo all changes made to this line. This is like executing the @code{undo} 1467command enough times to get back to the beginning. 1468 1469@ifset BashFeatures 1470@item tilde-expand (M-&) 1471@end ifset 1472@ifclear BashFeatures 1473@item tilde-expand (M-~) 1474@end ifclear 1475Perform tilde expansion on the current word. 1476 1477@item set-mark (C-@@) 1478Set the mark to the point. If a 1479numeric argument is supplied, the mark is set to that position. 1480 1481@item exchange-point-and-mark (C-x C-x) 1482Swap the point with the mark. The current cursor position is set to 1483the saved position, and the old cursor position is saved as the mark. 1484 1485@item character-search (C-]) 1486A character is read and point is moved to the next occurrence of that 1487character. A negative count searches for previous occurrences. 1488 1489@item character-search-backward (M-C-]) 1490A character is read and point is moved to the previous occurrence 1491of that character. A negative count searches for subsequent 1492occurrences. 1493 1494@item skip-csi-sequence () 1495Read enough characters to consume a multi-key sequence such as those 1496defined for keys like Home and End. Such sequences begin with a 1497Control Sequence Indicator (CSI), usually ESC-[. If this sequence is 1498bound to "\e[", keys producing such sequences will have no effect 1499unless explicitly bound to a readline command, instead of inserting 1500stray characters into the editing buffer. This is unbound by default, 1501but usually bound to ESC-[. 1502 1503@item insert-comment (M-#) 1504Without a numeric argument, the value of the @code{comment-begin} 1505variable is inserted at the beginning of the current line. 1506If a numeric argument is supplied, this command acts as a toggle: if 1507the characters at the beginning of the line do not match the value 1508of @code{comment-begin}, the value is inserted, otherwise 1509the characters in @code{comment-begin} are deleted from the beginning of 1510the line. 1511In either case, the line is accepted as if a newline had been typed. 1512@ifset BashFeatures 1513The default value of @code{comment-begin} causes this command 1514to make the current line a shell comment. 1515If a numeric argument causes the comment character to be removed, the line 1516will be executed by the shell. 1517@end ifset 1518 1519@item dump-functions () 1520Print all of the functions and their key bindings to the 1521Readline output stream. If a numeric argument is supplied, 1522the output is formatted in such a way that it can be made part 1523of an @var{inputrc} file. This command is unbound by default. 1524 1525@item dump-variables () 1526Print all of the settable variables and their values to the 1527Readline output stream. If a numeric argument is supplied, 1528the output is formatted in such a way that it can be made part 1529of an @var{inputrc} file. This command is unbound by default. 1530 1531@item dump-macros () 1532Print all of the Readline key sequences bound to macros and the 1533strings they output. If a numeric argument is supplied, 1534the output is formatted in such a way that it can be made part 1535of an @var{inputrc} file. This command is unbound by default. 1536 1537@ifset BashFeatures 1538@item glob-complete-word (M-g) 1539The word before point is treated as a pattern for pathname expansion, 1540with an asterisk implicitly appended. This pattern is used to 1541generate a list of matching file names for possible completions. 1542 1543@item glob-expand-word (C-x *) 1544The word before point is treated as a pattern for pathname expansion, 1545and the list of matching file names is inserted, replacing the word. 1546If a numeric argument is supplied, a @samp{*} is appended before 1547pathname expansion. 1548 1549@item glob-list-expansions (C-x g) 1550The list of expansions that would have been generated by 1551@code{glob-expand-word} is displayed, and the line is redrawn. 1552If a numeric argument is supplied, a @samp{*} is appended before 1553pathname expansion. 1554 1555@item display-shell-version (C-x C-v) 1556Display version information about the current instance of Bash. 1557 1558@item shell-expand-line (M-C-e) 1559Expand the line as the shell does. 1560This performs alias and history expansion as well as all of the shell 1561word expansions (@pxref{Shell Expansions}). 1562 1563@item history-expand-line (M-^) 1564Perform history expansion on the current line. 1565 1566@item magic-space () 1567Perform history expansion on the current line and insert a space 1568(@pxref{History Interaction}). 1569 1570@item alias-expand-line () 1571Perform alias expansion on the current line (@pxref{Aliases}). 1572 1573@item history-and-alias-expand-line () 1574Perform history and alias expansion on the current line. 1575 1576@item insert-last-argument (M-. or M-_) 1577A synonym for @code{yank-last-arg}. 1578 1579@item operate-and-get-next (C-o) 1580Accept the current line for execution and fetch the next line 1581relative to the current line from the history for editing. Any 1582argument is ignored. 1583 1584@item edit-and-execute-command (C-xC-e) 1585Invoke an editor on the current command line, and execute the result as shell 1586commands. 1587Bash attempts to invoke 1588@code{$VISUAL}, @code{$EDITOR}, and @code{emacs} 1589as the editor, in that order. 1590 1591@end ifset 1592 1593@ifclear BashFeatures 1594@item emacs-editing-mode (C-e) 1595When in @code{vi} command mode, this causes a switch to @code{emacs} 1596editing mode. 1597 1598@item vi-editing-mode (M-C-j) 1599When in @code{emacs} editing mode, this causes a switch to @code{vi} 1600editing mode. 1601 1602@end ifclear 1603 1604@end ftable 1605 1606@node Readline vi Mode 1607@section Readline vi Mode 1608 1609While the Readline library does not have a full set of @code{vi} 1610editing functions, it does contain enough to allow simple editing 1611of the line. The Readline @code{vi} mode behaves as specified in 1612the @sc{posix} standard. 1613 1614@ifset BashFeatures 1615In order to switch interactively between @code{emacs} and @code{vi} 1616editing modes, use the @samp{set -o emacs} and @samp{set -o vi} 1617commands (@pxref{The Set Builtin}). 1618@end ifset 1619@ifclear BashFeatures 1620In order to switch interactively between @code{emacs} and @code{vi} 1621editing modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode 1622when in @code{vi} mode and to vi-editing-mode in @code{emacs} mode). 1623@end ifclear 1624The Readline default is @code{emacs} mode. 1625 1626When you enter a line in @code{vi} mode, you are already placed in 1627`insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC} 1628switches you into `command' mode, where you can edit the text of the 1629line with the standard @code{vi} movement keys, move to previous 1630history lines with @samp{k} and subsequent lines with @samp{j}, and 1631so forth. 1632 1633@ifset BashFeatures 1634@node Programmable Completion 1635@section Programmable Completion 1636@cindex programmable completion 1637 1638When word completion is attempted for an argument to a command for 1639which a completion specification (a @var{compspec}) has been defined 1640using the @code{complete} builtin (@pxref{Programmable Completion Builtins}), 1641the programmable completion facilities are invoked. 1642 1643First, the command name is identified. 1644If a compspec has been defined for that command, the 1645compspec is used to generate the list of possible completions for the word. 1646If the command word is the empty string (completion attempted at the 1647beginning of an empty line), any compspec defined with 1648the @option{-E} option to @code{complete} is used. 1649If the command word is a full pathname, a compspec for the full 1650pathname is searched for first. 1651If no compspec is found for the full pathname, an attempt is made to 1652find a compspec for the portion following the final slash. 1653If those searches do not result in a compspec, any compspec defined with 1654the @option{-D} option to @code{complete} is used as the default. 1655 1656Once a compspec has been found, it is used to generate the list of 1657matching words. 1658If a compspec is not found, the default Bash completion 1659described above (@pxref{Commands For Completion}) is performed. 1660 1661First, the actions specified by the compspec are used. 1662Only matches which are prefixed by the word being completed are 1663returned. 1664When the @option{-f} or @option{-d} option is used for filename or 1665directory name completion, the shell variable @env{FIGNORE} is 1666used to filter the matches. 1667@xref{Bash Variables}, for a description of @env{FIGNORE}. 1668 1669Any completions specified by a filename expansion pattern to the 1670@option{-G} option are generated next. 1671The words generated by the pattern need not match the word being completed. 1672The @env{GLOBIGNORE} shell variable is not used to filter the matches, 1673but the @env{FIGNORE} shell variable is used. 1674 1675Next, the string specified as the argument to the @option{-W} option 1676is considered. 1677The string is first split using the characters in the @env{IFS} 1678special variable as delimiters. 1679Shell quoting is honored. 1680Each word is then expanded using 1681brace expansion, tilde expansion, parameter and variable expansion, 1682command substitution, and arithmetic expansion, 1683as described above (@pxref{Shell Expansions}). 1684The results are split using the rules described above 1685(@pxref{Word Splitting}). 1686The results of the expansion are prefix-matched against the word being 1687completed, and the matching words become the possible completions. 1688 1689After these matches have been generated, any shell function or command 1690specified with the @option{-F} and @option{-C} options is invoked. 1691When the command or function is invoked, the @env{COMP_LINE}, 1692@env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are 1693assigned values as described above (@pxref{Bash Variables}). 1694If a shell function is being invoked, the @env{COMP_WORDS} and 1695@env{COMP_CWORD} variables are also set. 1696When the function or command is invoked, the first argument is the 1697name of the command whose arguments are being completed, the 1698second argument is the word being completed, and the third argument 1699is the word preceding the word being completed on the current command line. 1700No filtering of the generated completions against the word being completed 1701is performed; the function or command has complete freedom in generating 1702the matches. 1703 1704Any function specified with @option{-F} is invoked first. 1705The function may use any of the shell facilities, including the 1706@code{compgen} and @code{compopt} builtins described below 1707(@pxref{Programmable Completion Builtins}), to generate the matches. 1708It must put the possible completions in the @env{COMPREPLY} array 1709variable. 1710 1711Next, any command specified with the @option{-C} option is invoked 1712in an environment equivalent to command substitution. 1713It should print a list of completions, one per line, to 1714the standard output. 1715Backslash may be used to escape a newline, if necessary. 1716 1717After all of the possible completions are generated, any filter 1718specified with the @option{-X} option is applied to the list. 1719The filter is a pattern as used for pathname expansion; a @samp{&} 1720in the pattern is replaced with the text of the word being completed. 1721A literal @samp{&} may be escaped with a backslash; the backslash 1722is removed before attempting a match. 1723Any completion that matches the pattern will be removed from the list. 1724A leading @samp{!} negates the pattern; in this case any completion 1725not matching the pattern will be removed. 1726 1727Finally, any prefix and suffix specified with the @option{-P} and @option{-S} 1728options are added to each member of the completion list, and the result is 1729returned to the Readline completion code as the list of possible 1730completions. 1731 1732If the previously-applied actions do not generate any matches, and the 1733@option{-o dirnames} option was supplied to @code{complete} when the 1734compspec was defined, directory name completion is attempted. 1735 1736If the @option{-o plusdirs} option was supplied to @code{complete} when 1737the compspec was defined, directory name completion is attempted and any 1738matches are added to the results of the other actions. 1739 1740By default, if a compspec is found, whatever it generates is returned to 1741the completion code as the full set of possible completions. 1742The default Bash completions are not attempted, and the Readline default 1743of filename completion is disabled. 1744If the @option{-o bashdefault} option was supplied to @code{complete} when 1745the compspec was defined, the default Bash completions are attempted 1746if the compspec generates no matches. 1747If the @option{-o default} option was supplied to @code{complete} when the 1748compspec was defined, Readline's default completion will be performed 1749if the compspec (and, if attempted, the default Bash completions) 1750generate no matches. 1751 1752When a compspec indicates that directory name completion is desired, 1753the programmable completion functions force Readline to append a slash 1754to completed names which are symbolic links to directories, subject to 1755the value of the @var{mark-directories} Readline variable, regardless 1756of the setting of the @var{mark-symlinked-directories} Readline variable. 1757 1758There is some support for dynamically modifying completions. This is 1759most useful when used in combination with a default completion specified 1760with @option{-D}. It's possible for shell functions executed as completion 1761handlers to indicate that completion should be retried by returning an 1762exit status of 124. If a shell function returns 124, and changes 1763the compspec associated with the command on which completion is being 1764attempted (supplied as the first argument when the function is executed), 1765programmable completion restarts from the beginning, with an 1766attempt to find a new compspec for that command. This allows a set of 1767completions to be built dynamically as completion is attempted, rather than 1768being loaded all at once. 1769 1770For instance, assuming that there is a library of compspecs, each kept in a 1771file corresponding to the name of the command, the following default 1772completion function would load completions dynamically: 1773 1774@example 1775_completion_loader() 1776@{ 1777 . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 1778@} 1779complete -D -F _completion_loader 1780@end example 1781 1782@node Programmable Completion Builtins 1783@section Programmable Completion Builtins 1784@cindex completion builtins 1785 1786Two builtin commands are available to manipulate the programmable completion 1787facilities. 1788 1789@table @code 1790@item compgen 1791@btindex compgen 1792@example 1793@code{compgen [@var{option}] [@var{word}]} 1794@end example 1795 1796Generate possible completion matches for @var{word} according to 1797the @var{option}s, which may be any option accepted by the 1798@code{complete} 1799builtin with the exception of @option{-p} and @option{-r}, and write 1800the matches to the standard output. 1801When using the @option{-F} or @option{-C} options, the various shell variables 1802set by the programmable completion facilities, while available, will not 1803have useful values. 1804 1805The matches will be generated in the same way as if the programmable 1806completion code had generated them directly from a completion specification 1807with the same flags. 1808If @var{word} is specified, only those completions matching @var{word} 1809will be displayed. 1810 1811The return value is true unless an invalid option is supplied, or no 1812matches were generated. 1813 1814@item complete 1815@btindex complete 1816@example 1817@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DE] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}] 1818[-F @var{function}] [-C @var{command}] [-X @var{filterpat}] 1819[-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]} 1820@code{complete -pr [-DE] [@var{name} @dots{}]} 1821@end example 1822 1823Specify how arguments to each @var{name} should be completed. 1824If the @option{-p} option is supplied, or if no options are supplied, existing 1825completion specifications are printed in a way that allows them to be 1826reused as input. 1827The @option{-r} option removes a completion specification for 1828each @var{name}, or, if no @var{name}s are supplied, all 1829completion specifications. 1830The @option{-D} option indicates that the remaining options and actions should 1831apply to the ``default'' command completion; that is, completion attempted 1832on a command for which no completion has previously been defined. 1833The @option{-E} option indicates that the remaining options and actions should 1834apply to ``empty'' command completion; that is, completion attempted on a 1835blank line. 1836 1837The process of applying these completion specifications when word completion 1838is attempted is described above (@pxref{Programmable Completion}). The 1839@option{-D} option takes precedence over @option{-E}. 1840 1841Other options, if specified, have the following meanings. 1842The arguments to the @option{-G}, @option{-W}, and @option{-X} options 1843(and, if necessary, the @option{-P} and @option{-S} options) 1844should be quoted to protect them from expansion before the 1845@code{complete} builtin is invoked. 1846 1847 1848@table @code 1849@item -o @var{comp-option} 1850The @var{comp-option} controls several aspects of the compspec's behavior 1851beyond the simple generation of completions. 1852@var{comp-option} may be one of: 1853 1854@table @code 1855 1856@item bashdefault 1857Perform the rest of the default Bash completions if the compspec 1858generates no matches. 1859 1860@item default 1861Use Readline's default filename completion if the compspec generates 1862no matches. 1863 1864@item dirnames 1865Perform directory name completion if the compspec generates no matches. 1866 1867@item filenames 1868Tell Readline that the compspec generates filenames, so it can perform any 1869filename-specific processing (like adding a slash to directory names 1870quoting special characters, or suppressing trailing spaces). 1871This option is intended to be used with shell functions specified 1872with @option{-F}. 1873 1874@item nospace 1875Tell Readline not to append a space (the default) to words completed at 1876the end of the line. 1877 1878@item plusdirs 1879After any matches defined by the compspec are generated, 1880directory name completion is attempted and any 1881matches are added to the results of the other actions. 1882 1883@end table 1884 1885@item -A @var{action} 1886The @var{action} may be one of the following to generate a list of possible 1887completions: 1888 1889@table @code 1890@item alias 1891Alias names. May also be specified as @option{-a}. 1892 1893@item arrayvar 1894Array variable names. 1895 1896@item binding 1897Readline key binding names (@pxref{Bindable Readline Commands}). 1898 1899@item builtin 1900Names of shell builtin commands. May also be specified as @option{-b}. 1901 1902@item command 1903Command names. May also be specified as @option{-c}. 1904 1905@item directory 1906Directory names. May also be specified as @option{-d}. 1907 1908@item disabled 1909Names of disabled shell builtins. 1910 1911@item enabled 1912Names of enabled shell builtins. 1913 1914@item export 1915Names of exported shell variables. May also be specified as @option{-e}. 1916 1917@item file 1918File names. May also be specified as @option{-f}. 1919 1920@item function 1921Names of shell functions. 1922 1923@item group 1924Group names. May also be specified as @option{-g}. 1925 1926@item helptopic 1927Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}). 1928 1929@item hostname 1930Hostnames, as taken from the file specified by the 1931@env{HOSTFILE} shell variable (@pxref{Bash Variables}). 1932 1933@item job 1934Job names, if job control is active. May also be specified as @option{-j}. 1935 1936@item keyword 1937Shell reserved words. May also be specified as @option{-k}. 1938 1939@item running 1940Names of running jobs, if job control is active. 1941 1942@item service 1943Service names. May also be specified as @option{-s}. 1944 1945@item setopt 1946Valid arguments for the @option{-o} option to the @code{set} builtin 1947(@pxref{The Set Builtin}). 1948 1949@item shopt 1950Shell option names as accepted by the @code{shopt} builtin 1951(@pxref{Bash Builtins}). 1952 1953@item signal 1954Signal names. 1955 1956@item stopped 1957Names of stopped jobs, if job control is active. 1958 1959@item user 1960User names. May also be specified as @option{-u}. 1961 1962@item variable 1963Names of all shell variables. May also be specified as @option{-v}. 1964@end table 1965 1966@item -C @var{command} 1967@var{command} is executed in a subshell environment, and its output is 1968used as the possible completions. 1969 1970@item -F @var{function} 1971The shell function @var{function} is executed in the current shell 1972environment. 1973When it finishes, the possible completions are retrieved from the value 1974of the @env{COMPREPLY} array variable. 1975 1976@item -G @var{globpat} 1977The filename expansion pattern @var{globpat} is expanded to generate 1978the possible completions. 1979 1980@item -P @var{prefix} 1981@var{prefix} is added at the beginning of each possible completion 1982after all other options have been applied. 1983 1984@item -S @var{suffix} 1985@var{suffix} is appended to each possible completion 1986after all other options have been applied. 1987 1988@item -W @var{wordlist} 1989The @var{wordlist} is split using the characters in the 1990@env{IFS} special variable as delimiters, and each resultant word 1991is expanded. 1992The possible completions are the members of the resultant list which 1993match the word being completed. 1994 1995@item -X @var{filterpat} 1996@var{filterpat} is a pattern as used for filename expansion. 1997It is applied to the list of possible completions generated by the 1998preceding options and arguments, and each completion matching 1999@var{filterpat} is removed from the list. 2000A leading @samp{!} in @var{filterpat} negates the pattern; in this 2001case, any completion not matching @var{filterpat} is removed. 2002@end table 2003 2004The return value is true unless an invalid option is supplied, an option 2005other than @option{-p} or @option{-r} is supplied without a @var{name} 2006argument, an attempt is made to remove a completion specification for 2007a @var{name} for which no specification exists, or 2008an error occurs adding a completion specification. 2009 2010@item compopt 2011@btindex compopt 2012@example 2013@code{compopt} [-o @var{option}] [-DE] [+o @var{option}] [@var{name}] 2014@end example 2015Modify completion options for each @var{name} according to the 2016@var{option}s, or for the currently-executing completion if no @var{name}s 2017are supplied. 2018If no @var{option}s are given, display the completion options for each 2019@var{name} or the current completion. 2020The possible values of @var{option} are those valid for the @code{complete} 2021builtin described above. 2022The @option{-D} option indicates that the remaining options should 2023apply to the ``default'' command completion; that is, completion attempted 2024on a command for which no completion has previously been defined. 2025The @option{-E} option indicates that the remaining options should 2026apply to ``empty'' command completion; that is, completion attempted on a 2027blank line. 2028 2029The @option{-D} option takes precedence over @option{-E}. 2030 2031The return value is true unless an invalid option is supplied, an attempt 2032is made to modify the options for a @var{name} for which no completion 2033specification exists, or an output error occurs. 2034 2035@end table 2036 2037@end ifset 2038