Commit | Line | Data |
---|---|---|
681fa9a8 RP |
1 | @ignore |
2 | ||
3 | This file documents the end user interface to the GNU command line | |
4 | editing feautres. It is to be an appendix to manuals for programs which | |
5 | use these features. There is a document entitled "readline.texinfo" | |
6 | which contains both end-user and programmer documentation for the GNU | |
7 | Readline Library. | |
8 | ||
9 | Copyright (C) 1988, 1991 Free Software Foundation, Inc. | |
10 | ||
11 | Written by Brian Fox. | |
12 | ||
13 | Permission is granted to process this file through Tex and print the | |
14 | results, provided the printed document carries copying permission notice | |
15 | identical to this one except for the removal of this paragraph (this | |
16 | paragraph not being relevant to the printed manual). | |
17 | ||
18 | Permission is granted to make and distribute verbatim copies of this manual | |
19 | provided the copyright notice and this permission notice are preserved on | |
20 | all copies. | |
21 | ||
22 | Permission is granted to copy and distribute modified versions of this | |
23 | manual under the conditions for verbatim copying, provided also that the | |
24 | GNU Copyright statement is available to the distributee, and provided that | |
25 | the entire resulting derived work is distributed under the terms of a | |
26 | permission notice identical to this one. | |
27 | ||
28 | Permission is granted to copy and distribute translations of this manual | |
29 | into another language, under the above conditions for modified versions. | |
30 | @end ignore | |
31 | ||
32 | @node Command Line Editing, , , Top | |
33 | @appendix Command Line Editing | |
34 | ||
35 | This appendix describes GNU's command line editing interface. | |
36 | Often during an interactive session you will type in a long line of | |
37 | text, only to notice that the first word on the line is misspelled. The | |
38 | Readline library gives you a set of commands for manipulating the text | |
39 | as you type it in, allowing you to just fix your typo, and not forcing | |
40 | you to retype the majority of the line. Using these editing commands, | |
41 | you move the cursor to the place that needs correction, and delete or | |
42 | insert the text of the corrections. Then, when you are satisfied with | |
43 | the line, you simply press @key{RETURN}. You do not have to be at the | |
44 | end of the line to press @key{RETURN}; the entire line will be accepted | |
45 | in any case. | |
46 | ||
47 | @menu | |
48 | * Conventions:: Notation used in this appendix. | |
9dd0e793 RP |
49 | * Readline Interaction:: How to use Readline |
50 | * Readline Init File:: Customizing Readline for your own use | |
681fa9a8 RP |
51 | @end menu |
52 | ||
9dd0e793 | 53 | @node Conventions, Readline Interaction, Command Line Editing, Command Line Editing |
681fa9a8 RP |
54 | @appendixsec Conventions on Notation |
55 | ||
56 | In this Appendix, the following notation is used to describe | |
57 | keystrokes. | |
58 | ||
59 | The text @kbd{C-k} is read as `Control-K' and describes the character | |
60 | produced when the Control key is depressed and the @key{k} key is struck. | |
61 | ||
62 | The text @kbd{M-k} is read as `Meta-K' and describes the character | |
63 | produced when the meta key (if you have one) is depressed, and the | |
64 | @key{k} key is struck. If you do not have a meta key, it is equivalent | |
65 | to type @key{ESC} @i{first}, and then type @key{k}. Either process is | |
66 | known as @dfn{metafying} the @key{k} key. | |
67 | ||
68 | The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the | |
69 | character produced by @dfn{metafying} @kbd{C-k}. | |
70 | ||
71 | In addition, several keys have their own names. Specifically, | |
72 | @key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all | |
73 | stand for themselves when seen in this text, or in an init file | |
74 | (@pxref{Readline Init File}, for more info). | |
75 | ||
9dd0e793 | 76 | @node Readline Interaction, Readline Init File, Conventions, Command Line Editing |
681fa9a8 RP |
77 | @appendixsec Readline Interaction |
78 | @cindex interaction, readline | |
79 | ||
80 | @menu | |
81 | * Readline Bare Essentials:: The least you need to know about Readline. | |
82 | * Readline Movement Commands:: Moving about the input line. | |
83 | * Readline Killing Commands:: How to delete text, and how to get it back! | |
84 | * Readline Arguments:: Giving numeric arguments to commands. | |
85 | @end menu | |
86 | ||
87 | @node Readline Bare Essentials, Readline Movement Commands, Readline Interaction, Readline Interaction | |
88 | @appendixsubsec Bare Essentials | |
89 | ||
90 | In order to enter characters into the line, simply type them. The typed | |
91 | character appears where the cursor was, and then the cursor moves one | |
92 | space to the right. If you mistype a character, you can use @key{DEL} to | |
93 | back up, and delete the mistyped character. | |
94 | ||
95 | Sometimes you may miss typing a character that you wanted to type, and | |
96 | not notice your error until you have typed several other characters. In | |
97 | that case, you can type @kbd{C-b} to move the cursor to the left, and then | |
98 | correct your mistake. Aftwerwards, you can move the cursor to the right | |
99 | with @kbd{C-f}. | |
100 | ||
101 | When you add text in the middle of a line, you will notice that characters | |
102 | to the right of the cursor get `pushed over' to make room for the text | |
103 | that you have inserted. Likewise, when you delete text behind the cursor, | |
104 | characters to the right of the cursor get `pulled back' to fill in the | |
105 | blank space created by the removal of the text. A list of the basic bare | |
106 | essentials for editing the text of an input line follows. | |
107 | ||
108 | @table @asis | |
109 | @item @kbd{C-b} | |
110 | Move back one character. | |
111 | @item @kbd{C-f} | |
112 | Move forward one character. | |
113 | @item @key{DEL} | |
114 | Delete the character to the left of the cursor. | |
115 | @item @kbd{C-d} | |
116 | Delete the character underneath the cursor. | |
117 | @item @var{c} | |
118 | Insert an ordinary printing character @var{c} into the line at the cursor. | |
119 | @item @kbd{C-_} | |
120 | Undo the last thing that you did. You can undo all the way back to an | |
121 | empty line. | |
122 | @end table | |
123 | ||
124 | @node Readline Movement Commands, Readline Killing Commands, Readline Bare Essentials, Readline Interaction | |
125 | @appendixsubsec Movement Commands | |
126 | ||
127 | ||
128 | The above table describes the most basic possible keystrokes that you need | |
129 | in order to do editing of the input line. For your convenience, many | |
130 | other commands have been added in addition to @kbd{C-b}, @kbd{C-f}, | |
131 | @kbd{C-d}, and @key{DEL}. Here are some commands for moving more rapidly | |
132 | about the line. | |
133 | ||
134 | @table @kbd | |
135 | @item C-a | |
136 | Move to the start of the line. | |
137 | @item C-e | |
138 | Move to the end of the line. | |
139 | @item M-f | |
140 | Move forward a word. | |
141 | @item M-b | |
142 | Move backward a word. | |
143 | @item C-l | |
144 | Clear the screen, reprinting the current line at the top. | |
145 | @end table | |
146 | ||
147 | Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves | |
148 | forward a word. It is a loose convention that control keystrokes | |
149 | operate on characters while meta keystrokes operate on words. | |
150 | ||
151 | @node Readline Killing Commands, Readline Arguments, Readline Movement Commands, Readline Interaction | |
152 | @appendixsubsec Killing Commands | |
153 | ||
154 | @dfn{Killing} text means to delete the text from the line, but to save | |
155 | it away for later use, usually by @dfn{yanking} it back into the line. | |
156 | If the description for a command says that it `kills' text, then you can | |
157 | be sure that you can get the text back in a different (or the same) | |
158 | place later. | |
159 | ||
160 | Here is the list of commands for killing text. | |
161 | ||
162 | @table @kbd | |
163 | @item C-k | |
164 | Kill the text from the current cursor position to the end of the line. | |
165 | ||
166 | @item M-d | |
167 | Kill from the cursor to the end of the current word, or if between | |
168 | words, to the end of the next word. | |
169 | ||
170 | @item M-@key{DEL} | |
171 | Kill from the cursor the start ofthe previous word, or if between words, to the start of the previous word. | |
172 | ||
173 | @item C-w | |
174 | Kill from the cursor to the previous whitespace. This is different than | |
175 | @kbd{M-@key{DEL}} because the word boundaries differ. | |
176 | ||
177 | @end table | |
178 | ||
179 | And, here is how to @dfn{yank} the text back into the line. Yanking | |
180 | is | |
181 | ||
182 | @table @kbd | |
183 | @item C-y | |
184 | Yank the most recently killed text back into the buffer at the cursor. | |
185 | ||
186 | @item M-y | |
187 | Rotate the kill-ring, and yank the new top. You can only do this if | |
188 | the prior command is @kbd{C-y} or @kbd{M-y}. | |
189 | @end table | |
190 | ||
191 | When you use a kill command, the text is saved in a @dfn{kill-ring}. | |
192 | Any number of consecutive kills save all of the killed text together, so | |
193 | that when you yank it back, you get it in one clean sweep. The kill | |
194 | ring is not line specific; the text that you killed on a previously | |
195 | typed line is available to be yanked back later, when you are typing | |
196 | another line. | |
197 | ||
198 | @node Readline Arguments, , Readline Killing Commands, Readline Interaction | |
199 | @appendixsubsec Arguments | |
200 | ||
201 | You can pass numeric arguments to Readline commands. Sometimes the | |
202 | argument acts as a repeat count, other times it is the @i{sign} of the | |
203 | argument that is significant. If you pass a negative argument to a | |
204 | command which normally acts in a forward direction, that command will | |
205 | act in a backward direction. For example, to kill text back to the | |
206 | start of the line, you might type @kbd{M--} @kbd{C-k}. | |
207 | ||
208 | The general way to pass numeric arguments to a command is to type meta | |
209 | digits before the command. If the first `digit' you type is a minus | |
210 | sign (@kbd{-}), then the sign of the argument will be negative. Once | |
211 | you have typed one meta digit to get the argument started, you can type | |
212 | the remainder of the digits, and then the command. For example, to give | |
213 | the @kbd{C-d} command an argument of 10, you could type @kbd{M-1 0 C-d}. | |
214 | ||
215 | ||
9dd0e793 | 216 | @node Readline Init File, , Readline Interaction, Command Line Editing |
681fa9a8 RP |
217 | @appendixsec Readline Init File |
218 | ||
219 | Although the Readline library comes with a set of Emacs-like | |
220 | keybindings, it is possible that you would like to use a different set | |
221 | of keybindings. You can customize programs that use Readline by putting | |
222 | commands in an @dfn{init} file in your home directory. The name of this | |
223 | file is @file{~/.inputrc}. | |
224 | ||
225 | When a program which uses the Readline library starts up, it reads the file | |
226 | @file{~/.inputrc}, and sets the keybindings. | |
227 | ||
228 | @menu | |
229 | * Readline Init Syntax:: Syntax for the commands in @file{~/.inputrc}. | |
230 | * Readline Vi Mode:: Switching to @code{vi} mode in Readline. | |
231 | @end menu | |
232 | ||
233 | @node Readline Init Syntax, Readline Vi Mode, Readline Init File, Readline Init File | |
234 | @appendixsubsec Readline Init Syntax | |
235 | ||
236 | You can start up with a vi-like editing mode by placing | |
237 | ||
238 | @example | |
239 | @code{set editing-mode vi} | |
240 | @end example | |
241 | ||
242 | @noindent | |
243 | in your @file{~/.inputrc} file. | |
244 | ||
245 | You can have Readline use a single line for display, scrolling the input | |
246 | between the two edges of the screen by placing | |
247 | ||
248 | @example | |
249 | @code{set horizontal-scroll-mode On} | |
250 | @end example | |
251 | ||
252 | @noindent | |
253 | in your @file{~/.inputrc} file. | |
254 | ||
255 | The syntax for controlling keybindings in the @file{~/.inputrc} file is | |
256 | simple. First you have to know the @i{name} of the command that you | |
257 | want to change. The following pages contain tables of the command name, the | |
258 | default keybinding, and a short description of what the command does. | |
259 | ||
260 | Once you know the name of the command, simply place the name of the key | |
261 | you wish to bind the command to, a colon, and then the name of the | |
262 | command on a line in the @file{~/.inputrc} file. Here is an example: | |
263 | ||
264 | @example | |
265 | # This is a comment line. | |
266 | Meta-Rubout: backward-kill-word | |
267 | Control-u: universal-argument | |
268 | @end example | |
269 | ||
270 | @menu | |
271 | * Commands For Moving:: Moving about the line. | |
272 | * Commands For History:: Getting at previous lines. | |
273 | * Commands For Text:: Commands for changing text. | |
274 | * Commands For Killing:: Commands for killing and yanking. | |
275 | * Numeric Arguments:: Specifying numeric arguments, repeat counts. | |
276 | * Commands For Completion:: Getting Readline to do the typing for you. | |
277 | * Miscellaneous Commands:: Other miscillaneous commands. | |
278 | @end menu | |
279 | ||
280 | @node Commands For Moving, Commands For History, Readline Init Syntax, Readline Init Syntax | |
281 | @appendixsubsubsec Moving | |
282 | @table @code | |
283 | @item beginning-of-line (C-a) | |
284 | Move to the start of the current line. | |
285 | ||
286 | @item end-of-line (C-e) | |
287 | Move to the end of the line. | |
288 | ||
289 | @item forward-char (C-f) | |
290 | Move forward a character. | |
291 | ||
292 | @item backward-char (C-b) | |
293 | Move back a character. | |
294 | ||
295 | @item forward-word (M-f) | |
296 | Move forward to the end of the next word. | |
297 | ||
298 | @item backward-word (M-b) | |
299 | Move back to the start of this, or the previous, word. | |
300 | ||
301 | @item clear-screen (C-l) | |
302 | Clear the screen leaving the current line at the top of the screen. | |
303 | ||
304 | @end table | |
305 | ||
306 | @node Commands For History, Commands For Text, Commands For Moving, Readline Init Syntax | |
307 | @appendixsubsubsec Using the History | |
308 | ||
309 | @table @code | |
310 | @item accept-line (Newline, Return) | |
311 | Accept the line regardless of where the cursor is. If this line is | |
312 | non-empty, add it to the history list. If this line was a history | |
313 | line, then restore the history line to its original state. | |
314 | ||
315 | @item previous-history (C-p) | |
316 | Move `up' through the history list. | |
317 | ||
318 | @item next-history (C-n) | |
319 | Move `down' through the history list. | |
320 | ||
321 | @item beginning-of-history (M-<) | |
322 | Move to the first line in the history. | |
323 | ||
324 | @item end-of-history (M->) | |
325 | Move to the end of the input history, i.e., the line you are entering! | |
326 | ||
327 | @item reverse-search-history (C-r) | |
328 | Search backward starting at the current line and moving `up' through | |
329 | the history as necessary. This is an incremental search. | |
330 | ||
331 | @item forward-search-history (C-s) | |
332 | Search forward starting at the current line and moving `down' through | |
333 | the the history as neccessary. | |
334 | ||
335 | @end table | |
336 | ||
337 | @node Commands For Text, Commands For Killing, Commands For History, Readline Init Syntax | |
338 | @appendixsubsubsec Changing Text | |
339 | ||
340 | @table @code | |
341 | @item delete-char (C-d) | |
342 | Delete the character under the cursor. If the cursor is at the | |
343 | beginning of the line, and there are no characters in the line, and | |
344 | the last character typed was not C-d, then return EOF. | |
345 | ||
346 | @item backward-delete-char (Rubout) | |
347 | Delete the character behind the cursor. A numeric arg says to kill | |
348 | the characters instead of deleting them. | |
349 | ||
350 | @item quoted-insert (C-q, C-v) | |
351 | Add the next character that you type to the line verbatim. This is | |
352 | how to insert things like C-q for example. | |
353 | ||
354 | @item tab-insert (M-TAB) | |
355 | Insert a tab character. | |
356 | ||
357 | @item self-insert (a, b, A, 1, !, ...) | |
358 | Insert an ordinary printing character into the line. | |
359 | ||
360 | @item transpose-chars (C-t) | |
361 | Drag the character before point forward over the character at point. | |
362 | Point moves forward as well. If point is at the end of the line, then | |
363 | transpose the two characters before point. Negative args don't work. | |
364 | ||
365 | @item transpose-words (M-t) | |
366 | Drag the word behind the cursor past the word in front of the cursor | |
367 | moving the cursor over that word as well. | |
368 | ||
369 | @item upcase-word (M-u) | |
370 | Uppercase the current (or following) word. With a negative argument, | |
371 | do the previous word, but do not move point. | |
372 | ||
373 | @item downcase-word (M-l) | |
374 | Lowercase the current (or following) word. With a negative argument, | |
375 | do the previous word, but do not move point. | |
376 | ||
377 | @item capitalize-word (M-c) | |
378 | Uppercase the current (or following) word. With a negative argument, | |
379 | do the previous word, but do not move point. | |
380 | ||
381 | @end table | |
382 | ||
383 | @node Commands For Killing, Numeric Arguments, Commands For Text, Readline Init Syntax | |
384 | @appendixsubsubsec Killing And Yanking | |
385 | ||
386 | @table @code | |
387 | ||
388 | @item kill-line (C-k) | |
389 | Kill the text from the current cursor position to the end of the line. | |
390 | ||
391 | @item backward-kill-line () | |
392 | Kill backward to the beginning of the line. This is normally unbound. | |
393 | ||
394 | @item kill-word (M-d) | |
395 | Kill from the cursor to the end of the current word, or if between | |
396 | words, to the end of the next word. | |
397 | ||
398 | @item backward-kill-word (M-DEL) | |
399 | Kill the word behind the cursor. | |
400 | ||
401 | @item unix-line-discard (C-u) | |
402 | Kill the entire line. This is similar to the use of the Unix kill | |
403 | character (often also @key{C-u}), save that here the killed text can be | |
404 | retrieved later (since it goes on the kill-ring). | |
405 | ||
406 | @item unix-word-rubout (C-w) | |
407 | Kill the current word, like the Unix word erase character. The killed | |
408 | text goes on the kill-ring. This is different than | |
409 | @code{backward-kill-word} because the word boundaries differ. | |
410 | ||
411 | @item yank (C-y) | |
412 | Yank the top of the kill ring into the buffer at point. | |
413 | ||
414 | @item yank-pop (M-y) | |
415 | Rotate the kill-ring, and yank the new top. You can only do this if | |
416 | the prior command is @code{yank} or @code{yank-pop}. | |
417 | @end table | |
418 | ||
419 | @node Numeric Arguments, Commands For Completion, Commands For Killing, Readline Init Syntax | |
420 | @appendixsubsubsec Numeric Arguments | |
421 | @table @code | |
422 | ||
423 | @item digit-argument (M-0, M-1, ... M--) | |
424 | Add this digit to the argument already accumulating, or start a new | |
425 | argument. @kbd{M--} starts a negative argument. | |
426 | ||
427 | @item universal-argument () | |
428 | Do what @key{C-u} does in emacs. By default, this is not bound to any keys. | |
429 | @end table | |
430 | ||
431 | ||
432 | @node Commands For Completion, Miscellaneous Commands, Numeric Arguments, Readline Init Syntax | |
433 | @appendixsubsubsec Letting Readline Type | |
434 | ||
435 | @table @code | |
436 | @item complete (TAB) | |
437 | Attempt to do completion on the text before point. This is | |
438 | implementation defined. Generally, if you are typing a filename | |
439 | argument, you can do filename completion; if you are typing a command, | |
440 | you can do command completion, if you are typing in a symbol to GDB, you | |
441 | can do symbol name completion, if you are typing in a variable to Bash, | |
442 | you can do variable name completion... | |
443 | ||
444 | @item possible-completions (M-?) | |
445 | List the possible completions of the text before point. | |
446 | @end table | |
447 | ||
448 | @node Miscellaneous Commands, , Commands For Completion, Readline Init Syntax | |
449 | @appendixsubsubsec Other Commands | |
450 | @table @code | |
451 | ||
452 | @item abort (@kbd{C-g}) | |
453 | The line editing commands @code{reverse-search-history} (@kbd{C-r}) and | |
454 | @code{forward-search-history} (@kbd{C-s} go into a separate input mode; | |
455 | you can abort the search, and return to normal input mode, by using the | |
456 | @code{abort} (@kbd{C-g}) command. | |
457 | ||
9dd0e793 | 458 | @item do-uppercase-version (@kbd{M-a}, @kbd{M-b}, @dots{}) |
681fa9a8 RP |
459 | Run the command that is bound to your uppercase brother. |
460 | ||
461 | @item prefix-meta (@key{ESC}) | |
462 | Make the next character that you type be metafied. This is for | |
463 | people without a meta key. @kbd{@key{ESC}-f} is equivalent to @kbd{M-f}. | |
464 | ||
465 | @item undo (@kbd{C-_}) | |
466 | Incremental undo, separately remembered for each line. | |
467 | ||
468 | @item revert-line (@kbd{M-r}) | |
469 | Undo all changes made to this line. This is like typing the `undo' | |
470 | command enough times to get back to the beginning. | |
471 | @end table | |
472 | ||
473 | @node Readline vi Mode, , Readline Init Syntax, Readline Init File | |
474 | @appendixsubsec Readline @code{vi} Mode | |
475 | ||
476 | While the Readline library does not have a full set of @code{vi} editing | |
477 | functions, it does contain enough to allow simple editing of the line. | |
478 | ||
479 | In order to switch interactively between Emacs and @code{vi} editing modes, use | |
480 | the command @kbd{M-C-j} (@code{toggle-editing-mode}). | |
481 | ||
482 | When you enter a line in @code{vi} mode, you are already in | |
483 | ``insertion'' mode, as if you had typed an @kbd{i}. Pressing @key{ESC} | |
484 | switches you into ``edit'' mode, where you can edit the text of the line | |
485 | with the standard @code{vi} movement keys, move to previous history | |
486 | lines with @kbd{k}, to following lines with @kbd{j}, and so forth. | |
487 | ||
488 | ||
489 | ||
490 |