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