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