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