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