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