Commit | Line | Data |
---|---|---|
be9485d5 SG |
1 | Info file readline.info, produced by Makeinfo, -*- Text -*- from input |
2 | file rlman.texinfo. | |
3 | ||
4 | This document describes the GNU Readline Library, a utility which | |
5 | aids in the consistency of user interface across discrete programs | |
6 | that need to provide a command line interface. | |
7 | ||
8 | Copyright (C) 1988, 1991 Free Software Foundation, Inc. | |
9 | ||
10 | Permission is granted to make and distribute verbatim copies of | |
11 | this manual provided the copyright notice and this permission notice | |
12 | pare preserved on all copies. | |
13 | ||
14 | Permission is granted to copy and distribute modified versions of | |
15 | this manual under the conditions for verbatim copying, provided that | |
16 | the entire resulting derived work is distributed under the terms of a | |
17 | permission notice identical to this one. | |
18 | ||
19 | Permission is granted to copy and distribute translations of this | |
20 | manual into another language, under the above conditions for modified | |
21 | versions, except that this permission notice may be stated in a | |
22 | translation approved by the Foundation. | |
23 | ||
24 | \1f | |
25 | File: readline.info, Node: Top, Next: Command Line Editing, Prev: (DIR), Up: (DIR) | |
26 | ||
27 | GNU Readline Library | |
28 | ******************** | |
29 | ||
30 | This document describes the GNU Readline Library, a utility which | |
31 | aids in the consistency of user interface across discrete programs | |
32 | that need to provide a command line interface. | |
33 | ||
34 | * Menu: | |
35 | ||
36 | * Command Line Editing:: GNU Readline User's Manual. | |
37 | * Programming with GNU Readline:: GNU Readline Programmer's Manual. | |
38 | * Concept Index:: Index of concepts described in this manual. | |
39 | * Function and Variable Index:: Index of externally visible functions | |
40 | and variables. | |
41 | ||
42 | \1f | |
43 | File: readline.info, Node: Command Line Editing, Next: Programming with GNU Readline, Prev: Top, Up: Top | |
44 | ||
45 | Command Line Editing | |
46 | ******************** | |
47 | ||
48 | This text describes GNU's command line editing interface. | |
49 | ||
50 | * Menu: | |
51 | ||
52 | * Introduction and Notation:: Notation used in this text. | |
53 | * Readline Interaction:: The minimum set of commands for editing a line. | |
54 | * Readline Init File:: Customizing Readline from a user's view. | |
55 | ||
56 | \1f | |
57 | File: readline.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing | |
58 | ||
59 | Introduction to Line Editing | |
60 | ============================ | |
61 | ||
62 | The following paragraphs describe the notation we use to represent | |
63 | keystrokes. | |
64 | ||
65 | The text C-k is read as `Control-K' and describes the character | |
66 | produced when the Control key is depressed and the k key is struck. | |
67 | ||
68 | The text M-k is read as `Meta-K' and describes the character | |
69 | produced when the meta key (if you have one) is depressed, and the k | |
70 | key is struck. If you do not have a meta key, the identical keystroke | |
71 | can be generated by typing ESC first, and then typing k. Either | |
72 | process is known as "metafying" the k key. | |
73 | ||
74 | The text M-C-k is read as `Meta-Control-k' and describes the | |
75 | character produced by "metafying" C-k. | |
76 | ||
77 | In addition, several keys have their own names. Specifically, DEL, | |
78 | ESC, LFD, SPC, RET, and TAB all stand for themselves when seen in this | |
79 | text, or in an init file (*note Readline Init File::., for more info). | |
80 | ||
81 | \1f | |
82 | File: readline.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing | |
83 | ||
84 | Readline Interaction | |
85 | ==================== | |
86 | ||
87 | Often during an interactive session you type in a long line of text, | |
88 | only to notice that the first word on the line is misspelled. The | |
89 | Readline library gives you a set of commands for manipulating the text | |
90 | as you type it in, allowing you to just fix your typo, and not forcing | |
91 | you to retype the majority of the line. Using these editing commands, | |
92 | you move the cursor to the place that needs correction, and delete or | |
93 | insert the text of the corrections. Then, when you are satisfied with | |
94 | the line, you simply press RETURN. You do not have to be at the end | |
95 | of the line to press RETURN; the entire line is accepted regardless of | |
96 | the location of the cursor within the line. | |
97 | ||
98 | * Menu: | |
99 | ||
100 | * Readline Bare Essentials:: The least you need to know about Readline. | |
101 | * Readline Movement Commands:: Moving about the input line. | |
102 | * Readline Killing Commands:: How to delete text, and how to get it back! | |
103 | * Readline Arguments:: Giving numeric arguments to commands. | |
104 | ||
105 | \1f | |
106 | File: readline.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction | |
107 | ||
108 | Readline Bare Essentials | |
109 | ------------------------ | |
110 | ||
111 | In order to enter characters into the line, simply type them. The | |
112 | typed character appears where the cursor was, and then the cursor | |
113 | moves one space to the right. If you mistype a character, you can use | |
114 | DEL to back up, and delete the mistyped character. | |
115 | ||
116 | Sometimes you may miss typing a character that you wanted to type, | |
117 | and not notice your error until you have typed several other | |
118 | characters. In that case, you can type C-b to move the cursor to the | |
119 | left, and then correct your mistake. Aftwerwards, you can move the | |
120 | cursor to the right with C-f. | |
121 | ||
122 | When you add text in the middle of a line, you will notice that | |
123 | characters to the right of the cursor get `pushed over' to make room | |
124 | for the text that you have inserted. Likewise, when you delete text | |
125 | behind the cursor, characters to the right of the cursor get `pulled | |
126 | back' to fill in the blank space created by the removal of the text. | |
127 | A list of the basic bare essentials for editing the text of an input | |
128 | line follows. | |
129 | ||
130 | C-b | |
131 | Move back one character. | |
132 | ||
133 | C-f | |
134 | Move forward one character. | |
135 | ||
136 | DEL | |
137 | Delete the character to the left of the cursor. | |
138 | ||
139 | C-d | |
140 | Delete the character underneath the cursor. | |
141 | ||
142 | Printing characters | |
143 | Insert itself into the line at the cursor. | |
144 | ||
145 | C-_ | |
146 | Undo the last thing that you did. You can undo all the way back | |
147 | to an empty line. | |
148 | ||
149 | \1f | |
150 | File: readline.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction | |
151 | ||
152 | Readline Movement Commands | |
153 | -------------------------- | |
154 | ||
155 | The above table describes the most basic possible keystrokes that | |
156 | you need in order to do editing of the input line. For your | |
157 | convenience, many other commands have been added in addition to C-b, | |
158 | C-f, C-d, and DEL. Here are some commands for moving more rapidly | |
159 | about the line. | |
160 | ||
161 | C-a | |
162 | Move to the start of the line. | |
163 | ||
164 | C-e | |
165 | Move to the end of the line. | |
166 | ||
167 | M-f | |
168 | Move forward a word. | |
169 | ||
170 | M-b | |
171 | Move backward a word. | |
172 | ||
173 | C-l | |
174 | Clear the screen, reprinting the current line at the top. | |
175 | ||
176 | Notice how C-f moves forward a character, while M-f moves forward a | |
177 | word. It is a loose convention that control keystrokes operate on | |
178 | characters while meta keystrokes operate on words. | |
179 | ||
180 | \1f | |
181 | File: readline.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction | |
182 | ||
183 | Readline Killing Commands | |
184 | ------------------------- | |
185 | ||
186 | The act of "cutting" text means to delete the text from the line, | |
187 | and to save away the deleted text for later use, just as if you had | |
188 | cut the text out of the line with a pair of scissors. There is a | |
189 | ||
190 | "Killing" text means to delete the text from the line, but to save | |
191 | it away for later use, usually by "yanking" it back into the line. If | |
192 | the description for a command says that it `kills' text, then you can | |
193 | be sure that you can get the text back in a different (or the same) | |
194 | place later. | |
195 | ||
196 | Here is the list of commands for killing text. | |
197 | ||
198 | C-k | |
199 | Kill the text from the current cursor position to the end of the | |
200 | line. | |
201 | ||
202 | M-d | |
203 | Kill from the cursor to the end of the current word, or if between | |
204 | words, to the end of the next word. | |
205 | ||
206 | M-DEL | |
207 | Kill fromthe cursor the start of the previous word, or if between | |
208 | words, to the start of the previous word. | |
209 | ||
210 | C-w | |
211 | Kill from the cursor to the previous whitespace. This is | |
212 | different than M-DEL because the word boundaries differ. | |
213 | ||
214 | And, here is how to "yank" the text back into the line. Yanking is | |
215 | ||
216 | C-y | |
217 | Yank the most recently killed text back into the buffer at the | |
218 | cursor. | |
219 | ||
220 | M-y | |
221 | Rotate the kill-ring, and yank the new top. You can only do this | |
222 | if the prior command is C-y or M-y. | |
223 | ||
224 | When you use a kill command, the text is saved in a "kill-ring". | |
225 | Any number of consecutive kills save all of the killed text together, | |
226 | so that when you yank it back, you get it in one clean sweep. The kill | |
227 | ring is not line specific; the text that you killed on a previously | |
228 | typed line is available to be yanked back later, when you are typing | |
229 | another line. | |
230 | ||
231 | \1f | |
232 | File: readline.info, Node: Readline Arguments, Prev: Readline Killing Commands, Up: Readline Interaction | |
233 | ||
234 | Readline Arguments | |
235 | ------------------ | |
236 | ||
237 | You can pass numeric arguments to Readline commands. Sometimes the | |
238 | argument acts as a repeat count, other times it is the sign of the | |
239 | argument that is significant. If you pass a negative argument to a | |
240 | command which normally acts in a forward direction, that command will | |
241 | act in a backward direction. For example, to kill text back to the | |
242 | start of the line, you might type M-- C-k. | |
243 | ||
244 | The general way to pass numeric arguments to a command is to type | |
245 | meta digits before the command. If the first `digit' you type is a | |
246 | minus sign (-), then the sign of the argument will be negative. Once | |
247 | you have typed one meta digit to get the argument started, you can type | |
248 | the remainder of the digits, and then the command. For example, to | |
249 | give the C-d command an argument of 10, you could type M-1 0 C-d. | |
250 | ||
251 | \1f | |
252 | File: readline.info, Node: Readline Init File, Prev: Readline Interaction, Up: Command Line Editing | |
253 | ||
254 | Readline Init File | |
255 | ================== | |
256 | ||
257 | Although the Readline library comes with a set of Emacs-like | |
258 | keybindings, it is possible that you would like to use a different set | |
259 | of keybindings. You can customize programs that use Readline by | |
260 | putting commands in an "init" file in your home directory. The name | |
261 | of this file is `~/.inputrc'. | |
262 | ||
263 | When a program which uses the Readline library starts up, the | |
264 | `~/.inputrc' file is read, and the keybindings are set. | |
265 | ||
266 | In addition, the `C-x C-r' command re-reads this init file, thus | |
267 | incorporating any changes that you might have made to it. | |
268 | ||
269 | * Menu: | |
270 | ||
271 | * Readline Init Syntax:: Syntax for the commands in `~/.inputrc'. | |
272 | * Readline Vi Mode:: Switching to `vi' mode in Readline. | |
273 | ||
274 | \1f | |
275 | File: readline.info, Node: Readline Init Syntax, Next: Readline Vi Mode, Up: Readline Init File | |
276 | ||
277 | Readline Init Syntax | |
278 | -------------------- | |
279 | ||
280 | There are only four constructs allowed in the `~/.inputrc' file: | |
281 | ||
282 | Variable Settings | |
283 | You can change the state of a few variables in Readline. You do | |
284 | this by using the `set' command within the init file. Here is | |
285 | how you would specify that you wish to use Vi line editing | |
286 | commands: | |
287 | ||
288 | set editing-mode vi | |
289 | ||
290 | Right now, there are only a few variables which can be set; so | |
291 | few in fact, that we just iterate them here: | |
292 | ||
293 | `editing-mode' | |
294 | The `editing-mode' variable controls which editing mode you | |
295 | are using. By default, GNU Readline starts up in Emacs | |
296 | editing mode, where the keystrokes are most similar to | |
297 | Emacs. This variable can either be set to `emacs' or `vi'. | |
298 | ||
299 | `horizontal-scroll-mode' | |
300 | This variable can either be set to `On' or `Off'. Setting it | |
301 | to `On' means that the text of the lines that you edit will | |
302 | scroll horizontally on a single screen line when they are | |
303 | larger than the width of the screen, instead of wrapping | |
304 | onto a new screen line. By default, this variable is set to | |
305 | `Off'. | |
306 | ||
307 | `mark-modified-lines' | |
308 | This variable when set to `On', says to display an asterisk | |
309 | (`*') at the starts of history lines which have been | |
310 | modified. This variable is off by default. | |
311 | ||
312 | `prefer-visible-bell' | |
313 | If this variable is set to `On' it means to use a visible | |
314 | bell if one is available, rather than simply ringing the | |
315 | terminal bell. By default, the value is `Off'. | |
316 | ||
317 | Key Bindings | |
318 | The syntax for controlling keybindings in the `~/.inputrc' file is | |
319 | simple. First you have to know the name of the command that you | |
320 | want to change. The following pages contain tables of the | |
321 | command name, the default keybinding, and a short description of | |
322 | what the command does. | |
323 | ||
324 | Once you know the name of the command, simply place the name of | |
325 | the key you wish to bind the command to, a colon, and then the | |
326 | name of the command on a line in the `~/.inputrc' file. The name | |
327 | of the key can be expressed in different ways, depending on which | |
328 | is most comfortable for you. | |
329 | ||
330 | KEYNAME: FUNCTION-NAME or MACRO | |
331 | KEYNAME is the name of a key spelled out in English. For | |
332 | example: | |
333 | ||
334 | Control-u: universal-argument | |
335 | Meta-Rubout: backward-kill-word | |
336 | Control-o: ">&output" | |
337 | ||
338 | In the above example, `C-u' is bound to the function | |
339 | `universal-argument', and `C-o' is bound to run the macro | |
340 | expressed on the right hand side (that is, to insert the text | |
341 | `>&output' into the line). | |
342 | ||
343 | "KEYSEQ": FUNCTION-NAME or MACRO | |
344 | KEYSEQ differs from KEYNAME above in that strings denoting | |
345 | an entire key sequence can be specified. Simply place the | |
346 | key sequence in double quotes. GNU Emacs style key escapes | |
347 | can be used, as in the following example: | |
348 | ||
349 | "\C-u": universal-argument | |
350 | "\C-x\C-r": re-read-init-file | |
351 | "\e[11~": "Function Key 1" | |
352 | ||
353 | In the above example, `C-u' is bound to the function | |
354 | `universal-argument' (just as it was in the first example), | |
355 | `C-x C-r' is bound to the function `re-read-init-file', and | |
356 | `ESC [ 1 1 ~' is bound to insert the text `Function Key 1'. | |
357 | ||
358 | * Menu: | |
359 | ||
360 | * Commands For Moving:: Moving about the line. | |
361 | * Commands For History:: Getting at previous lines. | |
362 | * Commands For Text:: Commands for changing text. | |
363 | * Commands For Killing:: Commands for killing and yanking. | |
364 | * Numeric Arguments:: Specifying numeric arguments, repeat counts. | |
365 | * Commands For Completion:: Getting Readline to do the typing for you. | |
366 | * Miscellaneous Commands:: Other miscillaneous commands. | |
367 | ||
368 | \1f | |
369 | File: readline.info, Node: Commands For Moving, Next: Commands For History, Up: Readline Init Syntax | |
370 | ||
371 | Commands For Moving | |
372 | ................... | |
373 | ||
374 | `beginning-of-line (C-a)' | |
375 | Move to the start of the current line. | |
376 | ||
377 | `end-of-line (C-e)' | |
378 | Move to the end of the line. | |
379 | ||
380 | `forward-char (C-f)' | |
381 | Move forward a character. | |
382 | ||
383 | `backward-char (C-b)' | |
384 | Move back a character. | |
385 | ||
386 | `forward-word (M-f)' | |
387 | Move forward to the end of the next word. | |
388 | ||
389 | `backward-word (M-b)' | |
390 | Move back to the start of this, or the previous, word. | |
391 | ||
392 | `clear-screen (C-l)' | |
393 | Clear the screen leaving the current line at the top of the | |
394 | screen. | |
395 | ||
396 | \1f | |
397 | File: readline.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Readline Init Syntax | |
398 | ||
399 | Commands For Manipulating The History | |
400 | ..................................... | |
401 | ||
402 | `accept-line (Newline, Return)' | |
403 | Accept the line regardless of where the cursor is. If this line | |
404 | is non-empty, add it to the history list. If this line was a | |
405 | history line, then restore the history line to its original state. | |
406 | ||
407 | `previous-history (C-p)' | |
408 | Move `up' through the history list. | |
409 | ||
410 | `next-history (C-n)' | |
411 | Move `down' through the history list. | |
412 | ||
413 | `beginning-of-history (M-<)' | |
414 | Move to the first line in the history. | |
415 | ||
416 | `end-of-history (M->)' | |
417 | Move to the end of the input history, i.e., the line you are | |
418 | entering! | |
419 | ||
420 | `reverse-search-history (C-r)' | |
421 | Search backward starting at the current line and moving `up' | |
422 | through the history as necessary. This is an incremental search. | |
423 | ||
424 | `forward-search-history (C-s)' | |
425 | Search forward starting at the current line and moving `down' | |
426 | through the the history as neccessary. | |
427 | ||
428 | \1f | |
429 | File: readline.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Readline Init Syntax | |
430 | ||
431 | Commands For Changing Text | |
432 | .......................... | |
433 | ||
434 | `delete-char (C-d)' | |
435 | Delete the character under the cursor. If the cursor is at the | |
436 | beginning of the line, and there are no characters in the line, | |
437 | and the last character typed was not C-d, then return EOF. | |
438 | ||
439 | `backward-delete-char (Rubout)' | |
440 | Delete the character behind the cursor. A numeric arg says to | |
441 | kill the characters instead of deleting them. | |
442 | ||
443 | `quoted-insert (C-q, C-v)' | |
444 | Add the next character that you type to the line verbatim. This | |
445 | is how to insert things like C-q for example. | |
446 | ||
447 | `tab-insert (M-TAB)' | |
448 | Insert a tab character. | |
449 | ||
450 | `self-insert (a, b, A, 1, !, ...)' | |
451 | Insert yourself. | |
452 | ||
453 | `transpose-chars (C-t)' | |
454 | Drag the character before point forward over the character at | |
455 | point. Point moves forward as well. If point is at the end of | |
456 | the line, then transpose the two characters before point. | |
457 | Negative args don't work. | |
458 | ||
459 | `transpose-words (M-t)' | |
460 | Drag the word behind the cursor past the word in front of the | |
461 | cursor moving the cursor over that word as well. | |
462 | ||
463 | `upcase-word (M-u)' | |
464 | Uppercase the current (or following) word. With a negative | |
465 | argument, do the previous word, but do not move point. | |
466 | ||
467 | `downcase-word (M-l)' | |
468 | Lowercase the current (or following) word. With a negative | |
469 | argument, do the previous word, but do not move point. | |
470 | ||
471 | `capitalize-word (M-c)' | |
472 | Uppercase the current (or following) word. With a negative | |
473 | argument, do the previous word, but do not move point. | |
474 | ||
475 | \1f | |
476 | File: readline.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Readline Init Syntax | |
477 | ||
478 | Killing And Yanking | |
479 | ................... | |
480 | ||
481 | `kill-line (C-k)' | |
482 | Kill the text from the current cursor position to the end of the | |
483 | line. | |
484 | ||
485 | `backward-kill-line ()' | |
486 | Kill backward to the beginning of the line. This is normally | |
487 | unbound. | |
488 | ||
489 | `kill-word (M-d)' | |
490 | Kill from the cursor to the end of the current word, or if between | |
491 | words, to the end of the next word. | |
492 | ||
493 | `backward-kill-word (M-DEL)' | |
494 | Kill the word behind the cursor. | |
495 | ||
496 | `unix-line-discard (C-u)' | |
497 | Do what C-u used to do in Unix line input. We save the killed | |
498 | text on the kill-ring, though. | |
499 | ||
500 | `unix-word-rubout (C-w)' | |
501 | Do what C-w used to do in Unix line input. The killed text is | |
502 | saved on the kill-ring. This is different than | |
503 | backward-kill-word because the word boundaries differ. | |
504 | ||
505 | `yank (C-y)' | |
506 | Yank the top of the kill ring into the buffer at point. | |
507 | ||
508 | `yank-pop (M-y)' | |
509 | Rotate the kill-ring, and yank the new top. You can only do this | |
510 | if the prior command is yank or yank-pop. | |
511 | ||
512 | \1f | |
513 | File: readline.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Readline Init Syntax | |
514 | ||
515 | Specifying Numeric Arguments | |
516 | ............................ | |
517 | ||
518 | `digit-argument (M-0, M-1, ... M--)' | |
519 | Add this digit to the argument already accumulating, or start a | |
520 | new argument. M-- starts a negative argument. | |
521 | ||
522 | `universal-argument ()' | |
523 | Do what C-u does in emacs. By default, this is not bound. | |
524 | ||
525 | \1f | |
526 | File: readline.info, Node: Commands For Completion, Next: Miscellaneous Commands, Prev: Numeric Arguments, Up: Readline Init Syntax | |
527 | ||
528 | Letting Readline Type For You | |
529 | ............................. | |
530 | ||
531 | `complete (TAB)' | |
532 | Attempt to do completion on the text before point. This is | |
533 | implementation defined. Generally, if you are typing a filename | |
534 | argument, you can do filename completion; if you are typing a | |
535 | command, you can do command completion, if you are typing in a | |
536 | symbol to GDB, you can do symbol name completion, if you are | |
537 | typing in a variable to Bash, you can do variable name | |
538 | completion... | |
539 | ||
540 | `possible-completions (M-?)' | |
541 | List the possible completions of the text before point. | |
542 | ||
543 | \1f | |
544 | File: readline.info, Node: Miscellaneous Commands, Prev: Commands For Completion, Up: Readline Init Syntax | |
545 | ||
546 | Some Miscellaneous Commands | |
547 | ........................... | |
548 | ||
549 | `re-read-init-file (C-x C-r)' | |
550 | Read in the contents of your `~/.inputrc' file, and incorporate | |
551 | any bindings found there. | |
552 | ||
553 | `abort (C-g)' | |
554 | Ding! Stops things. | |
555 | ||
556 | `do-uppercase-version (M-a, M-b, ...)' | |
557 | Run the command that is bound to your uppercase brother. | |
558 | ||
559 | `prefix-meta (ESC)' | |
560 | Make the next character that you type be metafied. This is for | |
561 | people without a meta key. Typing `ESC f' is equivalent to typing | |
562 | `M-f'. | |
563 | ||
564 | `undo (C-_)' | |
565 | Incremental undo, separately remembered for each line. | |
566 | ||
567 | `revert-line (M-r)' | |
568 | Undo all changes made to this line. This is like typing the | |
569 | `undo' command enough times to get back to the beginning. | |
570 | ||
571 | \1f | |
572 | File: readline.info, Node: Readline Vi Mode, Prev: Readline Init Syntax, Up: Readline Init File | |
573 | ||
574 | Readline Vi Mode | |
575 | ---------------- | |
576 | ||
577 | While the Readline library does not have a full set of Vi editing | |
578 | functions, it does contain enough to allow simple editing of the line. | |
579 | ||
580 | In order to switch interactively between Emacs and Vi editing | |
581 | modes, use the command M-C-j (toggle-editing-mode). | |
582 | ||
583 | When you enter a line in Vi mode, you are already placed in | |
584 | `insertion' mode, as if you had typed an `i'. Pressing ESC switches | |
585 | you into `edit' mode, where you can edit the text of the line with the | |
586 | standard Vi movement keys, move to previous history lines with `k', | |
587 | and following lines with `j', and so forth. | |
588 | ||
589 | This document describes the GNU Readline Library, a utility for | |
590 | aiding in the consitency of user interface across discrete programs | |
591 | that need to provide a command line interface. | |
592 | ||
593 | Copyright (C) 1988 Free Software Foundation, Inc. | |
594 | ||
595 | Permission is granted to make and distribute verbatim copies of | |
596 | this manual provided the copyright notice and this permission notice | |
597 | pare preserved on all copies. | |
598 | ||
599 | Permission is granted to copy and distribute modified versions of | |
600 | this manual under the conditions for verbatim copying, provided that | |
601 | the entire resulting derived work is distributed under the terms of a | |
602 | permission notice identical to this one. | |
603 | ||
604 | Permission is granted to copy and distribute translations of this | |
605 | manual into another language, under the above conditions for modified | |
606 | versions, except that this permission notice may be stated in a | |
607 | translation approved by the Foundation. | |
608 | ||
609 | \1f | |
610 | File: readline.info, Node: Programming with GNU Readline, Next: Concept Index, Prev: Command Line Editing, Up: Top | |
611 | ||
612 | Programming with GNU Readline | |
613 | ***************************** | |
614 | ||
615 | This manual describes the interface between the GNU Readline | |
616 | Library and user programs. If you are a programmer, and you wish to | |
617 | include the features found in GNU Readline in your own programs, such | |
618 | as completion, line editing, and interactive history manipulation, | |
619 | this documentation is for you. | |
620 | ||
621 | * Menu: | |
622 | ||
623 | * Default Behaviour:: Using the default behaviour of Readline. | |
624 | * Custom Functions:: Adding your own functions to Readline. | |
625 | * Custom Completers:: Supplanting or supplementing Readline's | |
626 | completion functions. | |
627 | ||
628 | \1f | |
629 | File: readline.info, Node: Default Behaviour, Next: Custom Functions, Up: Programming with GNU Readline | |
630 | ||
631 | Default Behaviour | |
632 | ================= | |
633 | ||
634 | Many programs provide a command line interface, such as `mail', | |
635 | `ftp', and `sh'. For such programs, the default behaviour of Readline | |
636 | is sufficient. This section describes how to use Readline in the | |
637 | simplest way possible, perhaps to replace calls in your code to `gets | |
638 | ()'. | |
639 | ||
640 | The function `readline' prints a prompt and then reads and returns | |
641 | a single line of text from the user. The line which `readline ()' | |
642 | returns is allocated with `malloc ()'; you should `free ()' the line | |
643 | when you are done with it. The declaration for `readline' in ANSI C is | |
644 | ||
645 | `char *readline (char *PROMPT);' | |
646 | ||
647 | So, one might say | |
648 | ||
649 | `char *line = readline ("Enter a line: ");' | |
650 | ||
651 | in order to read a line of text from the user. | |
652 | ||
653 | The line which is returned has the final newline removed, so only | |
654 | the text of the line remains. | |
655 | ||
656 | If readline encounters an `EOF' while reading the line, and the | |
657 | line is empty at that point, then `(char *)NULL' is returned. | |
658 | Otherwise, the line is ended just as if a newline was typed. | |
659 | ||
660 | If you want the user to be able to get at the line later, (with C-p | |
661 | for example), you must call `add_history ()' to save the line away in | |
662 | a "history" list of such lines. | |
663 | ||
664 | `add_history (line)'; | |
665 | ||
666 | For full details on the GNU History Library, see the associated | |
667 | manual. | |
668 | ||
669 | It is polite to avoid saving empty lines on the history list, since | |
670 | it is rare than someone has a burning need to reuse a blank line. | |
671 | Here is a function which usefully replaces the standard `gets ()' | |
672 | library function: | |
673 | ||
674 | /* A static variable for holding the line. */ | |
675 | static char *line_read = (char *)NULL; | |
676 | ||
677 | /* Read a string, and return a pointer to it. Returns NULL on EOF. */ | |
678 | char * | |
679 | do_gets () | |
680 | { | |
681 | /* If the buffer has already been allocated, return the memory | |
682 | to the free pool. */ | |
683 | if (line_read != (char *)NULL) | |
684 | { | |
685 | free (line_read); | |
686 | line_read = (char *)NULL; | |
687 | } | |
688 | ||
689 | /* Get a line from the user. */ | |
690 | line_read = readline (""); | |
691 | ||
692 | /* If the line has any text in it, save it on the history. */ | |
693 | if (line_read && *line_read) | |
694 | add_history (line_read); | |
695 | ||
696 | return (line_read); | |
697 | } | |
698 | ||
699 | The above code gives the user the default behaviour of TAB | |
700 | completion: completion on file names. If you do not want readline to | |
701 | complete on filenames, you can change the binding of the TAB key with | |
702 | `rl_bind_key ()'. | |
703 | ||
704 | `int rl_bind_key (int KEY, (int (*)())FUNCTION);' | |
705 | ||
706 | `rl_bind_key ()' takes 2 arguments; KEY is the character that you | |
707 | want to bind, and FUNCTION is the address of the function to run when | |
708 | KEY is pressed. Binding TAB to `rl_insert ()' makes TAB just insert | |
709 | itself. | |
710 | ||
711 | `rl_bind_key ()' returns non-zero if KEY is not a valid ASCII | |
712 | character code (between 0 and 255). | |
713 | ||
714 | `rl_bind_key ('\t', rl_insert);' | |
715 | ||
716 | This code should be executed once at the start of your program; you | |
717 | might write a function called `initialize_readline ()' which performs | |
718 | this and other desired initializations, such as installing custom | |
719 | completers, etc. | |
720 | ||
721 | \1f | |
722 | File: readline.info, Node: Custom Functions, Next: Custom Completers, Prev: Default Behaviour, Up: Programming with GNU Readline | |
723 | ||
724 | Custom Functions | |
725 | ================ | |
726 | ||
727 | Readline provides a great many functions for manipulating the text | |
728 | of the line. But it isn't possible to anticipate the needs of all | |
729 | programs. This section describes the various functions and variables | |
730 | defined in within the Readline library which allow a user program to | |
731 | add customized functionality to Readline. | |
732 | ||
733 | * Menu: | |
734 | ||
735 | * The Function Type:: C declarations to make code readable. | |
736 | * Function Naming:: How to give a function you write a name. | |
737 | * Keymaps:: Making keymaps. | |
738 | * Binding Keys:: Changing Keymaps. | |
739 | * Function Writing:: Variables and calling conventions. | |
740 | * Allowing Undoing:: How to make your functions undoable. | |
741 | ||
742 | \1f | |
743 | File: readline.info, Node: The Function Type, Next: Function Naming, Up: Custom Functions | |
744 | ||
745 | The Function Type | |
746 | ----------------- | |
747 | ||
748 | For the sake of readabilty, we declare a new type of object, called | |
749 | "Function". A `Function' is a C language function which returns an | |
750 | `int'. The type declaration for `Function' is: | |
751 | ||
752 | `typedef int Function ();' | |
753 | ||
754 | The reason for declaring this new type is to make it easier to write | |
755 | code describing pointers to C functions. Let us say we had a variable | |
756 | called FUNC which was a pointer to a function. Instead of the classic | |
757 | C declaration | |
758 | ||
759 | `int (*)()func;' | |
760 | ||
761 | we have | |
762 | ||
763 | `Function *func;' | |
764 | ||
765 | \1f | |
766 | File: readline.info, Node: Function Naming, Next: Keymaps, Prev: The Function Type, Up: Custom Functions | |
767 | ||
768 | Naming a Function | |
769 | ----------------- | |
770 | ||
771 | The user can dynamically change the bindings of keys while using | |
772 | Readline. This is done by representing the function with a descriptive | |
773 | name. The user is able to type the descriptive name when referring to | |
774 | the function. Thus, in an init file, one might find | |
775 | ||
776 | Meta-Rubout: backward-kill-word | |
777 | ||
778 | This binds the keystroke Meta-Rubout to the function | |
779 | *descriptively* named `backward-kill-word'. You, as the programmer, | |
780 | should bind the functions you write to descriptive names as well. | |
781 | Readline provides a function for doing that: | |
782 | ||
783 | * Function: rl_add_defun (CHAR *NAME, FUNCTION *FUNCTION, INT KEY) | |
784 | Add NAME to the list of named functions. Make FUNCTION be the | |
785 | function that gets called. If KEY is not -1, then bind it to | |
786 | FUNCTION using `rl_bind_key ()'. | |
787 | ||
788 | Using this function alone is sufficient for most applications. It | |
789 | is the recommended way to add a few functions to the default functions | |
790 | that Readline has built in already. If you need to do more or | |
791 | different things than adding a function to Readline, you may need to | |
792 | use the underlying functions described below. | |
793 | ||
794 | \1f | |
795 | File: readline.info, Node: Keymaps, Next: Binding Keys, Prev: Function Naming, Up: Custom Functions | |
796 | ||
797 | Selecting a Keymap | |
798 | ------------------ | |
799 | ||
800 | Key bindings take place on a "keymap". The keymap is the | |
801 | association between the keys that the user types and the functions that | |
802 | get run. You can make your own keymaps, copy existing keymaps, and | |
803 | tell Readline which keymap to use. | |
804 | ||
805 | * Function: Keymap rl_make_bare_keymap () | |
806 | Returns a new, empty keymap. The space for the keymap is | |
807 | allocated with `malloc ()'; you should `free ()' it when you are | |
808 | done. | |
809 | ||
810 | * Function: Keymap rl_copy_keymap (KEYMAP MAP) | |
811 | Return a new keymap which is a copy of MAP. | |
812 | ||
813 | * Function: Keymap rl_make_keymap () | |
814 | Return a new keymap with the printing characters bound to | |
815 | rl_insert, the lowercase Meta characters bound to run their | |
816 | equivalents, and the Meta digits bound to produce numeric | |
817 | arguments. | |
818 | ||
819 | \1f | |
820 | File: readline.info, Node: Binding Keys, Next: Function Writing, Prev: Keymaps, Up: Custom Functions | |
821 | ||
822 | Binding Keys | |
823 | ------------ | |
824 | ||
825 | You associate keys with functions through the keymap. Here are | |
826 | functions for doing that. | |
827 | ||
828 | * Function: int rl_bind_key (INT KEY, FUNCTION *FUNCTION) | |
829 | Binds KEY to FUNCTION in the currently selected keymap. Returns | |
830 | non-zero in the case of an invalid KEY. | |
831 | ||
832 | * Function: int rl_bind_key_in_map (INT KEY, FUNCTION *FUNCTION, | |
833 | KEYMAP MAP) | |
834 | Bind KEY to FUNCTION in MAP. Returns non-zero in the case of an | |
835 | invalid KEY. | |
836 | ||
837 | * Function: int rl_unbind_key (INT KEY) | |
838 | Make KEY do nothing in the currently selected keymap. Returns | |
839 | non-zero in case of error. | |
840 | ||
841 | * Function: int rl_unbind_key_in_map (INT KEY, KEYMAP MAP) | |
842 | Make KEY be bound to the null function in MAP. Returns non-zero | |
843 | in case of error. | |
844 | ||
845 | * Function: rl_generic_bind (INT TYPE, CHAR *KEYSEQ, CHAR *DATA, | |
846 | KEYMAP MAP) | |
847 | Bind the key sequence represented by the string KEYSEQ to the | |
848 | arbitrary pointer DATA. TYPE says what kind of data is pointed | |
849 | to by DATA; right now this can be a function (`ISFUNC'), a macro | |
850 | (`ISMACR'), or a keymap (`ISKMAP'). This makes new keymaps as | |
851 | necessary. The initial place to do bindings is in MAP. | |
852 | ||
853 | \1f | |
854 | File: readline.info, Node: Function Writing, Next: Allowing Undoing, Prev: Binding Keys, Up: Custom Functions | |
855 | ||
856 | Writing a New Function | |
857 | ---------------------- | |
858 | ||
859 | In order to write new functions for Readline, you need to know the | |
860 | calling conventions for keyboard invoked functions, and the names of | |
861 | the variables that describe the current state of the line gathered so | |
862 | far. | |
863 | ||
864 | * Variable: char *rl_line_buffer | |
865 | This is the line gathered so far. You are welcome to modify the | |
866 | contents of this, but see Undoing, below. | |
867 | ||
868 | * Variable: int rl_point | |
869 | The offset of the current cursor position in RL_LINE_BUFFER. | |
870 | ||
871 | * Variable: int rl_end | |
872 | The number of characters present in `rl_line_buffer'. When | |
873 | `rl_point' is at the end of the line, then `rl_point' and | |
874 | `rl_end' are equal. | |
875 | ||
876 | The calling sequence for a command `foo' looks like | |
877 | ||
878 | `foo (int count, int key)' | |
879 | ||
880 | where COUNT is the numeric argument (or 1 if defaulted) and KEY is | |
881 | the key that invoked this function. | |
882 | ||
883 | It is completely up to the function as to what should be done with | |
884 | the numeric argument; some functions use it as a repeat count, other | |
885 | functions as a flag, and some choose to ignore it. In general, if a | |
886 | function uses the numeric argument as a repeat count, it should be able | |
887 | to do something useful with a negative argument as well as a positive | |
888 | argument. At the very least, it should be aware that it can be passed | |
889 | a negative argument. | |
890 | ||
891 | \1f | |
892 | File: readline.info, Node: Allowing Undoing, Prev: Function Writing, Up: Custom Functions | |
893 | ||
894 | Allowing Undoing | |
895 | ---------------- | |
896 | ||
897 | Supporting the undo command is a painless thing to do, and makes | |
898 | your functions much more useful to the end user. It is certainly easy | |
899 | to try something if you know you can undo it. I could use an undo | |
900 | function for the stock market. | |
901 | ||
902 | If your function simply inserts text once, or deletes text once, | |
903 | and it calls `rl_insert_text ()' or `rl_delete_text ()' to do it, then | |
904 | undoing is already done for you automatically, and you can safely skip | |
905 | this section. | |
906 | ||
907 | If you do multiple insertions or multiple deletions, or any | |
908 | combination of these operations, you should group them together into | |
909 | one operation. This can be done with `rl_begin_undo_group ()' and | |
910 | `rl_end_undo_group ()'. | |
911 | ||
912 | * Function: rl_begin_undo_group () | |
913 | Begins saving undo information in a group construct. The undo | |
914 | information usually comes from calls to `rl_insert_text ()' and | |
915 | `rl_delete_text ()', but they could be direct calls to | |
916 | `rl_add_undo ()'. | |
917 | ||
918 | * Function: rl_end_undo_group () | |
919 | Closes the current undo group started with `rl_begin_undo_group | |
920 | ()'. There should be exactly one call to `rl_end_undo_group ()' | |
921 | for every call to `rl_begin_undo_group ()'. | |
922 | ||
923 | Finally, if you neither insert nor delete text, but directly modify | |
924 | the existing text (e.g. change its case), you call `rl_modifying ()' | |
925 | once, just before you modify the text. You must supply the indices of | |
926 | the text range that you are going to modify. | |
927 | ||
928 | * Function: rl_modifying (INT START, INT END) | |
929 | Tell Readline to save the text between START and END as a single | |
930 | undo unit. It is assumed that subsequent to this call you will | |
931 | modify that range of text in some way. | |
932 | ||
933 | An Example | |
934 | ---------- | |
935 | ||
936 | Here is a function which changes lowercase characters to the | |
937 | uppercase equivalents, and uppercase characters to the lowercase | |
938 | equivalents. If this function was bound to `M-c', then typing `M-c' | |
939 | would change the case of the character under point. Typing `10 M-c' | |
940 | would change the case of the following 10 characters, leaving the | |
941 | cursor on the last character changed. | |
942 | ||
943 | /* Invert the case of the COUNT following characters. */ | |
944 | invert_case_line (count, key) | |
945 | int count, key; | |
946 | { | |
947 | register int start, end; | |
948 | ||
949 | start = rl_point; | |
950 | ||
951 | if (count < 0) | |
952 | { | |
953 | direction = -1; | |
954 | count = -count; | |
955 | } | |
956 | else | |
957 | direction = 1; | |
958 | ||
959 | /* Find the end of the range to modify. */ | |
960 | end = start + (count * direction); | |
961 | ||
962 | /* Force it to be within range. */ | |
963 | if (end > rl_end) | |
964 | end = rl_end; | |
965 | else if (end < 0) | |
966 | end = -1; | |
967 | ||
968 | if (start > end) | |
969 | { | |
970 | int temp = start; | |
971 | start = end; | |
972 | end = temp; | |
973 | } | |
974 | ||
975 | if (start == end) | |
976 | return; | |
977 | ||
978 | /* Tell readline that we are modifying the line, so save the undo | |
979 | information. */ | |
980 | rl_modifying (start, end); | |
981 | ||
982 | for (; start != end; start += direction) | |
983 | { | |
984 | if (uppercase_p (rl_line_buffer[start])) | |
985 | rl_line_buffer[start] = to_lower (rl_line_buffer[start]); | |
986 | else if (lowercase_p (rl_line_buffer[start])) | |
987 | rl_line_buffer[start] = to_upper (rl_line_buffer[start]); | |
988 | } | |
989 | /* Move point to on top of the last character changed. */ | |
990 | rl_point = end - direction; | |
991 | } | |
992 | ||
993 | \1f | |
994 | File: readline.info, Node: Custom Completers, Prev: Custom Functions, Up: Programming with GNU Readline | |
995 | ||
996 | Custom Completers | |
997 | ================= | |
998 | ||
999 | Typically, a program that reads commands from the user has a way of | |
1000 | disambiguating commands and data. If your program is one of these, | |
1001 | then it can provide completion for either commands, or data, or both | |
1002 | commands and data. The following sections describe how your program | |
1003 | and Readline cooperate to provide this service to end users. | |
1004 | ||
1005 | * Menu: | |
1006 | ||
1007 | * How Completing Works:: The logic used to do completion. | |
1008 | * Completion Functions:: Functions provided by Readline. | |
1009 | * Completion Variables:: Variables which control completion. | |
1010 | * A Short Completion Example:: An example of writing completer subroutines. | |
1011 | ||
1012 | \1f | |
1013 | File: readline.info, Node: How Completing Works, Next: Completion Functions, Up: Custom Completers | |
1014 | ||
1015 | How Completing Works | |
1016 | -------------------- | |
1017 | ||
1018 | In order to complete some text, the full list of possible | |
1019 | completions must be available. That is to say, it is not possible to | |
1020 | accurately expand a partial word without knowing what all of the | |
1021 | possible words that make sense in that context are. The GNU Readline | |
1022 | library provides the user interface to completion, and additionally, | |
1023 | two of the most common completion functions; filename and username. | |
1024 | For completing other types of text, you must write your own completion | |
1025 | function. This section describes exactly what those functions must | |
1026 | do, and provides an example function. | |
1027 | ||
1028 | There are three major functions used to perform completion: | |
1029 | ||
1030 | 1. The user-interface function `rl_complete ()'. This function is | |
1031 | called interactively with the same calling conventions as other | |
1032 | functions in readline intended for interactive use; i.e. COUNT, | |
1033 | and INVOKING-KEY. It isolates the word to be completed and calls | |
1034 | `completion_matches ()' to generate a list of possible | |
1035 | completions. It then either lists the possible completions or | |
1036 | actually performs the completion, depending on which behaviour is | |
1037 | desired. | |
1038 | ||
1039 | 2. The internal function `completion_matches ()' uses your | |
1040 | "generator" function to generate the list of possible matches, and | |
1041 | then returns the array of these matches. You should place the | |
1042 | address of your generator function in | |
1043 | `rl_completion_entry_function'. | |
1044 | ||
1045 | 3. The generator function is called repeatedly from | |
1046 | `completion_matches ()', returning a string each time. The | |
1047 | arguments to the generator function are TEXT and STATE. TEXT is | |
1048 | the partial word to be completed. STATE is zero the first time | |
1049 | the function is called, and a positive non-zero integer for each | |
1050 | subsequent call. When the generator function returns `(char | |
1051 | *)NULL' this signals `completion_matches ()' that there are no | |
1052 | more possibilities left. | |
1053 | ||
1054 | * Function: rl_complete (INT IGNORE, INT INVOKING_KEY) | |
1055 | Complete the word at or before point. You have supplied the | |
1056 | function that does the initial simple matching selection | |
1057 | algorithm (see `completion_matches ()'). The default is to do | |
1058 | filename completion. | |
1059 | ||
1060 | Note that `rl_complete ()' has the identical calling conventions as | |
1061 | any other key-invokable function; this is because by default it is | |
1062 | bound to the `TAB' key. | |
1063 | ||
1064 | * Variable: Function *rl_completion_entry_function | |
1065 | This is a pointer to the generator function for | |
1066 | `completion_matches ()'. If the value of | |
1067 | `rl_completion_entry_function' is `(Function *)NULL' then the | |
1068 | default filename generator function is used, namely | |
1069 | `filename_entry_function ()'. | |
1070 | ||
1071 | \1f | |
1072 | File: readline.info, Node: Completion Functions, Next: Completion Variables, Prev: How Completing Works, Up: Custom Completers | |
1073 | ||
1074 | Completion Functions | |
1075 | -------------------- | |
1076 | ||
1077 | Here is the complete list of callable completion functions present | |
1078 | in Readline. | |
1079 | ||
1080 | * Function: rl_complete_internal (INT WHAT_TO_DO) | |
1081 | Complete the word at or before point. WHAT_TO_DO says what to do | |
1082 | with the completion. A value of `?' means list the possible | |
1083 | completions. `TAB' means do standard completion. `*' means | |
1084 | insert all of the possible completions. | |
1085 | ||
1086 | * Function: rl_complete (INT IGNORE, INT INVOKING_KEY) | |
1087 | Complete the word at or before point. You have supplied the | |
1088 | function that does the initial simple matching selection | |
1089 | algorithm (see `completion_matches ()'). The default is to do | |
1090 | filename completion. This just calls `rl_complete_internal ()' | |
1091 | with an argument of `TAB'. | |
1092 | ||
1093 | * Function: rl_possible_completions () | |
1094 | List the possible completions. See description of `rl_complete | |
1095 | ()'. This just calls `rl_complete_internal ()' with an argument | |
1096 | of `?'. | |
1097 | ||
1098 | * Function: char **completion_matches (CHAR *TEXT, CHAR | |
1099 | *(*ENTRY_FUNCTION) ()) | |
1100 | Returns an array of `(char *)' which is a list of completions for | |
1101 | TEXT. If there are no completions, returns `(char **)NULL'. The | |
1102 | first entry in the returned array is the substitution for TEXT. | |
1103 | The remaining entries are the possible completions. The array is | |
1104 | terminated with a `NULL' pointer. | |
1105 | ||
1106 | ENTRY_FUNCTION is a function of two args, and returns a `(char | |
1107 | *)'. The first argument is TEXT. The second is a state | |
1108 | argument; it is zero on the first call, and non-zero on subsequent | |
1109 | calls. It returns a `NULL' pointer to the caller when there are | |
1110 | no more matches. | |
1111 | ||
1112 | * Function: char *filename_completion_function (CHAR *TEXT, INT STATE) | |
1113 | A generator function for filename completion in the general case. | |
1114 | Note that completion in the Bash shell is a little different | |
1115 | because of all the pathnames that must be followed when looking | |
1116 | up the completion for a command. | |
1117 | ||
1118 | * Function: char *username_completion_function (CHAR *TEXT, INT STATE) | |
1119 | A completion generator for usernames. TEXT contains a partial | |
1120 | username preceded by a random character (usually `~'). | |
1121 | ||
1122 | \1f | |
1123 | File: readline.info, Node: Completion Variables, Next: A Short Completion Example, Prev: Completion Functions, Up: Custom Completers | |
1124 | ||
1125 | Completion Variables | |
1126 | -------------------- | |
1127 | ||
1128 | * Variable: Function *rl_completion_entry_function | |
1129 | A pointer to the generator function for `completion_matches ()'. | |
1130 | `NULL' means to use `filename_entry_function ()', the default | |
1131 | filename completer. | |
1132 | ||
1133 | * Variable: Function *rl_attempted_completion_function | |
1134 | A pointer to an alternative function to create matches. The | |
1135 | function is called with TEXT, START, and END. START and END are | |
1136 | indices in `rl_line_buffer' saying what the boundaries of TEXT | |
1137 | are. If this function exists and returns `NULL' then | |
1138 | `rl_complete ()' will call the value of | |
1139 | `rl_completion_entry_function' to generate matches, otherwise the | |
1140 | array of strings returned will be used. | |
1141 | ||
1142 | * Variable: int rl_completion_query_items | |
1143 | Up to this many items will be displayed in response to a | |
1144 | possible-completions call. After that, we ask the user if she is | |
1145 | sure she wants to see them all. The default value is 100. | |
1146 | ||
1147 | * Variable: char *rl_basic_word_break_characters | |
1148 | The basic list of characters that signal a break between words | |
1149 | for the completer routine. The contents of this variable is what | |
1150 | breaks words in the Bash shell, i.e. " \t\n\"\\'`@$><=;|&{(". | |
1151 | ||
1152 | * Variable: char *rl_completer_word_break_characters | |
1153 | The list of characters that signal a break between words for | |
1154 | `rl_complete_internal ()'. The default list is the contents of | |
1155 | `rl_basic_word_break_characters'. | |
1156 | ||
1157 | * Variable: char *rl_special_prefixes | |
1158 | The list of characters that are word break characters, but should | |
1159 | be left in TEXT when it is passed to the completion function. | |
1160 | Programs can use this to help determine what kind of completing | |
1161 | to do. | |
1162 | ||
1163 | * Variable: int rl_ignore_completion_duplicates | |
1164 | If non-zero, then disallow duplicates in the matches. Default is | |
1165 | 1. | |
1166 | ||
1167 | * Variable: int rl_filename_completion_desired | |
1168 | Non-zero means that the results of the matches are to be treated | |
1169 | as filenames. This is *always* zero on entry, and can only be | |
1170 | changed within a completion entry generator function. | |
1171 | ||
1172 | * Variable: Function *rl_ignore_some_completions_function | |
1173 | This function, if defined, is called by the completer when real | |
1174 | filename completion is done, after all the matching names have | |
1175 | been generated. It is passed a `NULL' terminated array of `(char | |
1176 | *)' known as MATCHES in the code. The 1st element (`matches[0]') | |
1177 | is the maximal substring that is common to all matches. This | |
1178 | function can re-arrange the list of matches as required, but each | |
1179 | deleted element of the array must be `free()''d. | |
1180 | ||
1181 | \1f | |
1182 | File: readline.info, Node: A Short Completion Example, Prev: Completion Variables, Up: Custom Completers | |
1183 | ||
1184 | A Short Completion Example | |
1185 | -------------------------- | |
1186 | ||
1187 | Here is a small application demonstrating the use of the GNU | |
1188 | Readline library. It is called `fileman', and the source code resides | |
1189 | in `readline/examples/fileman.c'. This sample application provides | |
1190 | completion of command names, line editing features, and access to the | |
1191 | history list. | |
1192 | ||
1193 | /* fileman.c -- A tiny application which demonstrates how to use the | |
1194 | GNU Readline library. This application interactively allows users | |
1195 | to manipulate files and their modes. */ | |
1196 | ||
1197 | #include <stdio.h> | |
1198 | #include <readline/readline.h> | |
1199 | #include <readline/history.h> | |
1200 | #include <sys/types.h> | |
1201 | #include <sys/file.h> | |
1202 | #include <sys/stat.h> | |
1203 | #include <sys/errno.h> | |
1204 | ||
1205 | /* The names of functions that actually do the manipulation. */ | |
1206 | int com_list (), com_view (), com_rename (), com_stat (), com_pwd (); | |
1207 | int com_delete (), com_help (), com_cd (), com_quit (); | |
1208 | ||
1209 | /* A structure which contains information on the commands this program | |
1210 | can understand. */ | |
1211 | ||
1212 | typedef struct { | |
1213 | char *name; /* User printable name of the function. */ | |
1214 | Function *func; /* Function to call to do the job. */ | |
1215 | char *doc; /* Documentation for this function. */ | |
1216 | } COMMAND; | |
1217 | ||
1218 | COMMAND commands[] = { | |
1219 | { "cd", com_cd, "Change to directory DIR" }, | |
1220 | { "delete", com_delete, "Delete FILE" }, | |
1221 | { "help", com_help, "Display this text" }, | |
1222 | { "?", com_help, "Synonym for `help'" }, | |
1223 | { "list", com_list, "List files in DIR" }, | |
1224 | { "ls", com_list, "Synonym for `list'" }, | |
1225 | { "pwd", com_pwd, "Print the current working directory" }, | |
1226 | { "quit", com_quit, "Quit using Fileman" }, | |
1227 | { "rename", com_rename, "Rename FILE to NEWNAME" }, | |
1228 | { "stat", com_stat, "Print out statistics on FILE" }, | |
1229 | { "view", com_view, "View the contents of FILE" }, | |
1230 | { (char *)NULL, (Function *)NULL, (char *)NULL } | |
1231 | }; | |
1232 | ||
1233 | /* The name of this program, as taken from argv[0]. */ | |
1234 | char *progname; | |
1235 | ||
1236 | /* When non-zero, this global means the user is done using this program. */ | |
1237 | int done = 0; | |
1238 | ||
1239 | main (argc, argv) | |
1240 | int argc; | |
1241 | char **argv; | |
1242 | { | |
1243 | progname = argv[0]; | |
1244 | ||
1245 | initialize_readline (); /* Bind our completer. */ | |
1246 | ||
1247 | /* Loop reading and executing lines until the user quits. */ | |
1248 | while (!done) | |
1249 | { | |
1250 | char *line; | |
1251 | ||
1252 | line = readline ("FileMan: "); | |
1253 | ||
1254 | if (!line) | |
1255 | { | |
1256 | done = 1; /* Encountered EOF at top level. */ | |
1257 | } | |
1258 | else | |
1259 | { | |
1260 | /* Remove leading and trailing whitespace from the line. | |
1261 | Then, if there is anything left, add it to the history list | |
1262 | and execute it. */ | |
1263 | stripwhite (line); | |
1264 | ||
1265 | if (*line) | |
1266 | { | |
1267 | add_history (line); | |
1268 | execute_line (line); | |
1269 | } | |
1270 | } | |
1271 | ||
1272 | if (line) | |
1273 | free (line); | |
1274 | } | |
1275 | exit (0); | |
1276 | } | |
1277 | ||
1278 | /* Execute a command line. */ | |
1279 | execute_line (line) | |
1280 | char *line; | |
1281 | { | |
1282 | register int i; | |
1283 | COMMAND *find_command (), *command; | |
1284 | char *word; | |
1285 | ||
1286 | /* Isolate the command word. */ | |
1287 | i = 0; | |
1288 | while (line[i] && !whitespace (line[i])) | |
1289 | i++; | |
1290 | ||
1291 | word = line; | |
1292 | ||
1293 | if (line[i]) | |
1294 | line[i++] = '\0'; | |
1295 | ||
1296 | command = find_command (word); | |
1297 | ||
1298 | if (!command) | |
1299 | { | |
1300 | fprintf (stderr, "%s: No such command for FileMan.\n", word); | |
1301 | return; | |
1302 | } | |
1303 | ||
1304 | /* Get argument to command, if any. */ | |
1305 | while (whitespace (line[i])) | |
1306 | i++; | |
1307 | ||
1308 | word = line + i; | |
1309 | ||
1310 | /* Call the function. */ | |
1311 | (*(command->func)) (word); | |
1312 | } | |
1313 | ||
1314 | /* Look up NAME as the name of a command, and return a pointer to that | |
1315 | command. Return a NULL pointer if NAME isn't a command name. */ | |
1316 | COMMAND * | |
1317 | find_command (name) | |
1318 | char *name; | |
1319 | { | |
1320 | register int i; | |
1321 | ||
1322 | for (i = 0; commands[i].name; i++) | |
1323 | if (strcmp (name, commands[i].name) == 0) | |
1324 | return (&commands[i]); | |
1325 | ||
1326 | return ((COMMAND *)NULL); | |
1327 | } | |
1328 | ||
1329 | /* Strip whitespace from the start and end of STRING. */ | |
1330 | stripwhite (string) | |
1331 | char *string; | |
1332 | { | |
1333 | register int i = 0; | |
1334 | ||
1335 | while (whitespace (string[i])) | |
1336 | i++; | |
1337 | ||
1338 | if (i) | |
1339 | strcpy (string, string + i); | |
1340 | ||
1341 | i = strlen (string) - 1; | |
1342 | ||
1343 | while (i > 0 && whitespace (string[i])) | |
1344 | i--; | |
1345 | ||
1346 | string[++i] = '\0'; | |
1347 | } | |
1348 | ||
1349 | /* **************************************************************** */ | |
1350 | /* */ | |
1351 | /* Interface to Readline Completion */ | |
1352 | /* */ | |
1353 | /* **************************************************************** */ | |
1354 | ||
1355 | /* Tell the GNU Readline library how to complete. We want to try to complete | |
1356 | on command names if this is the first word in the line, or on filenames | |
1357 | if not. */ | |
1358 | initialize_readline () | |
1359 | { | |
1360 | char **fileman_completion (); | |
1361 | ||
1362 | /* Allow conditional parsing of the ~/.inputrc file. */ | |
1363 | rl_readline_name = "FileMan"; | |
1364 | ||
1365 | /* Tell the completer that we want a crack first. */ | |
1366 | rl_attempted_completion_function = (Function *)fileman_completion; | |
1367 | } | |
1368 | ||
1369 | /* Attempt to complete on the contents of TEXT. START and END show the | |
1370 | region of TEXT that contains the word to complete. We can use the | |
1371 | entire line in case we want to do some simple parsing. Return the | |
1372 | array of matches, or NULL if there aren't any. */ | |
1373 | char ** | |
1374 | fileman_completion (text, start, end) | |
1375 | char *text; | |
1376 | int start, end; | |
1377 | { | |
1378 | char **matches; | |
1379 | char *command_generator (); | |
1380 | ||
1381 | matches = (char **)NULL; | |
1382 | ||
1383 | /* If this word is at the start of the line, then it is a command | |
1384 | to complete. Otherwise it is the name of a file in the current | |
1385 | directory. */ | |
1386 | if (start == 0) | |
1387 | matches = completion_matches (text, command_generator); | |
1388 | ||
1389 | return (matches); | |
1390 | } | |
1391 | ||
1392 | /* Generator function for command completion. STATE lets us know whether | |
1393 | to start from scratch; without any state (i.e. STATE == 0), then we | |
1394 | start at the top of the list. */ | |
1395 | char * | |
1396 | command_generator (text, state) | |
1397 | char *text; | |
1398 | int state; | |
1399 | { | |
1400 | static int list_index, len; | |
1401 | char *name; | |
1402 | ||
1403 | /* If this is a new word to complete, initialize now. This includes | |
1404 | saving the length of TEXT for efficiency, and initializing the index | |
1405 | variable to 0. */ | |
1406 | if (!state) | |
1407 | { | |
1408 | list_index = 0; | |
1409 | len = strlen (text); | |
1410 | } | |
1411 | ||
1412 | /* Return the next name which partially matches from the command list. */ | |
1413 | while (name = commands[list_index].name) | |
1414 | { | |
1415 | list_index++; | |
1416 | ||
1417 | if (strncmp (name, text, len) == 0) | |
1418 | return (name); | |
1419 | } | |
1420 | ||
1421 | /* If no names matched, then return NULL. */ | |
1422 | return ((char *)NULL); | |
1423 | } | |
1424 | ||
1425 | /* **************************************************************** */ | |
1426 | /* */ | |
1427 | /* FileMan Commands */ | |
1428 | /* */ | |
1429 | /* **************************************************************** */ | |
1430 | ||
1431 | /* String to pass to system (). This is for the LIST, VIEW and RENAME | |
1432 | commands. */ | |
1433 | static char syscom[1024]; | |
1434 | ||
1435 | /* List the file(s) named in arg. */ | |
1436 | com_list (arg) | |
1437 | char *arg; | |
1438 | { | |
1439 | if (!arg) | |
1440 | arg = "*"; | |
1441 | ||
1442 | sprintf (syscom, "ls -FClg %s", arg); | |
1443 | system (syscom); | |
1444 | } | |
1445 | ||
1446 | com_view (arg) | |
1447 | char *arg; | |
1448 | { | |
1449 | if (!valid_argument ("view", arg)) | |
1450 | return; | |
1451 | ||
1452 | sprintf (syscom, "cat %s | more", arg); | |
1453 | system (syscom); | |
1454 | } | |
1455 | ||
1456 | com_rename (arg) | |
1457 | char *arg; | |
1458 | { | |
1459 | too_dangerous ("rename"); | |
1460 | } | |
1461 | ||
1462 | com_stat (arg) | |
1463 | char *arg; | |
1464 | { | |
1465 | struct stat finfo; | |
1466 | ||
1467 | if (!valid_argument ("stat", arg)) | |
1468 | return; | |
1469 | ||
1470 | if (stat (arg, &finfo) == -1) | |
1471 | { | |
1472 | perror (arg); | |
1473 | return; | |
1474 | } | |
1475 | ||
1476 | printf ("Statistics for `%s':\n", arg); | |
1477 | ||
1478 | printf ("%s has %d link%s, and is %d bytes in length.\n", arg, | |
1479 | finfo.st_nlink, (finfo.st_nlink == 1) ? "" : "s", finfo.st_size); | |
1480 | printf (" Created on: %s", ctime (&finfo.st_ctime)); | |
1481 | printf (" Last access at: %s", ctime (&finfo.st_atime)); | |
1482 | printf ("Last modified at: %s", ctime (&finfo.st_mtime)); | |
1483 | } | |
1484 | ||
1485 | com_delete (arg) | |
1486 | char *arg; | |
1487 | { | |
1488 | too_dangerous ("delete"); | |
1489 | } | |
1490 | ||
1491 | /* Print out help for ARG, or for all of the commands if ARG is | |
1492 | not present. */ | |
1493 | com_help (arg) | |
1494 | char *arg; | |
1495 | { | |
1496 | register int i; | |
1497 | int printed = 0; | |
1498 | ||
1499 | for (i = 0; commands[i].name; i++) | |
1500 | { | |
1501 | if (!*arg || (strcmp (arg, commands[i].name) == 0)) | |
1502 | { | |
1503 | printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc); | |
1504 | printed++; | |
1505 | } | |
1506 | } | |
1507 | ||
1508 | if (!printed) | |
1509 | { | |
1510 | printf ("No commands match `%s'. Possibilties are:\n", arg); | |
1511 | ||
1512 | for (i = 0; commands[i].name; i++) | |
1513 | { | |
1514 | /* Print in six columns. */ | |
1515 | if (printed == 6) | |
1516 | { | |
1517 | printed = 0; | |
1518 | printf ("\n"); | |
1519 | } | |
1520 | ||
1521 | printf ("%s\t", commands[i].name); | |
1522 | printed++; | |
1523 | } | |
1524 | ||
1525 | if (printed) | |
1526 | printf ("\n"); | |
1527 | } | |
1528 | } | |
1529 | ||
1530 | /* Change to the directory ARG. */ | |
1531 | com_cd (arg) | |
1532 | char *arg; | |
1533 | { | |
1534 | if (chdir (arg) == -1) | |
1535 | perror (arg); | |
1536 | ||
1537 | com_pwd (""); | |
1538 | } | |
1539 | ||
1540 | /* Print out the current working directory. */ | |
1541 | com_pwd (ignore) | |
1542 | char *ignore; | |
1543 | { | |
1544 | char dir[1024]; | |
1545 | ||
1546 | (void) getwd (dir); | |
1547 | ||
1548 | printf ("Current directory is %s\n", dir); | |
1549 | } | |
1550 | ||
1551 | /* The user wishes to quit using this program. Just set DONE non-zero. */ | |
1552 | com_quit (arg) | |
1553 | char *arg; | |
1554 | { | |
1555 | done = 1; | |
1556 | } | |
1557 | ||
1558 | /* Function which tells you that you can't do this. */ | |
1559 | too_dangerous (caller) | |
1560 | char *caller; | |
1561 | { | |
1562 | fprintf (stderr, | |
1563 | "%s: Too dangerous for me to distribute. Write it yourself.\n", | |
1564 | caller); | |
1565 | } | |
1566 | ||
1567 | /* Return non-zero if ARG is a valid argument for CALLER, else print | |
1568 | an error message and return zero. */ | |
1569 | int | |
1570 | valid_argument (caller, arg) | |
1571 | char *caller, *arg; | |
1572 | { | |
1573 | if (!arg || !*arg) | |
1574 | { | |
1575 | fprintf (stderr, "%s: Argument required.\n", caller); | |
1576 | return (0); | |
1577 | } | |
1578 | ||
1579 | return (1); | |
1580 | } | |
1581 | ||
1582 | \1f | |
1583 | File: readline.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU Readline, Up: Top | |
1584 | ||
1585 | Concept Index | |
1586 | ************* | |
1587 | ||
1588 | * Menu: | |
1589 | ||
1590 | * interaction, readline: Readline Interaction. | |
1591 | * readline, function: Default Behaviour. | |
1592 | ||
1593 | \1f | |
1594 | File: readline.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top | |
1595 | ||
1596 | Function and Variable Index | |
1597 | *************************** | |
1598 | ||
1599 | * Menu: | |
1600 | ||
1601 | * Function *rl_attempted_completion_function: Completion Variables. | |
1602 | * Function *rl_completion_entry_function: Completion Variables. | |
1603 | * Function *rl_completion_entry_function: How Completing Works. | |
1604 | * Function *rl_ignore_some_completions_function: Completion Variables. | |
1605 | * Keymap rl_copy_keymap: Keymaps. | |
1606 | * Keymap rl_make_bare_keymap: Keymaps. | |
1607 | * Keymap rl_make_keymap: Keymaps. | |
1608 | * abort (C-g): Miscellaneous Commands. | |
1609 | * accept-line (Newline, Return): Commands For History. | |
1610 | * backward-char (C-b): Commands For Moving. | |
1611 | * backward-delete-char (Rubout): Commands For Text. | |
1612 | * backward-kill-line (): Commands For Killing. | |
1613 | * backward-kill-word (M-DEL): Commands For Killing. | |
1614 | * backward-word (M-b): Commands For Moving. | |
1615 | * beginning-of-history (M-<): Commands For History. | |
1616 | * beginning-of-line (C-a): Commands For Moving. | |
1617 | * capitalize-word (M-c): Commands For Text. | |
1618 | * char **completion_matches: Completion Functions. | |
1619 | * char *filename_completion_function: Completion Functions. | |
1620 | * char *rl_basic_word_break_characters: Completion Variables. | |
1621 | * char *rl_completer_word_break_characters: Completion Variables. | |
1622 | * char *rl_line_buffer: Function Writing. | |
1623 | * char *rl_special_prefixes: Completion Variables. | |
1624 | * char *username_completion_function: Completion Functions. | |
1625 | * clear-screen (C-l): Commands For Moving. | |
1626 | * complete (TAB): Commands For Completion. | |
1627 | * delete-char (C-d): Commands For Text. | |
1628 | * digit-argument (M-0, M-1, ... M--): Numeric Arguments. | |
1629 | * do-uppercase-version (M-a, M-b, ...): Miscellaneous Commands. | |
1630 | * downcase-word (M-l): Commands For Text. | |
1631 | * editing-mode: Readline Init Syntax. | |
1632 | * end-of-history (M->): Commands For History. | |
1633 | * end-of-line (C-e): Commands For Moving. | |
1634 | * forward-char (C-f): Commands For Moving. | |
1635 | * forward-search-history (C-s): Commands For History. | |
1636 | * forward-word (M-f): Commands For Moving. | |
1637 | * horizontal-scroll-mode: Readline Init Syntax. | |
1638 | * int rl_bind_key: Binding Keys. | |
1639 | * int rl_bind_key_in_map: Binding Keys. | |
1640 | * int rl_completion_query_items: Completion Variables. | |
1641 | * int rl_end: Function Writing. | |
1642 | * int rl_filename_completion_desired: Completion Variables. | |
1643 | * int rl_ignore_completion_duplicates: Completion Variables. | |
1644 | * int rl_point: Function Writing. | |
1645 | * int rl_unbind_key: Binding Keys. | |
1646 | * int rl_unbind_key_in_map: Binding Keys. | |
1647 | * kill-line (C-k): Commands For Killing. | |
1648 | * kill-word (M-d): Commands For Killing. | |
1649 | * mark-modified-lines: Readline Init Syntax. | |
1650 | * next-history (C-n): Commands For History. | |
1651 | * possible-completions (M-?): Commands For Completion. | |
1652 | * prefer-visible-bell: Readline Init Syntax. | |
1653 | * prefix-meta (ESC): Miscellaneous Commands. | |
1654 | * previous-history (C-p): Commands For History. | |
1655 | * quoted-insert (C-q, C-v): Commands For Text. | |
1656 | * re-read-init-file (C-x C-r): Miscellaneous Commands. | |
1657 | * readline (): Default Behaviour. | |
1658 | * reverse-search-history (C-r): Commands For History. | |
1659 | * revert-line (M-r): Miscellaneous Commands. | |
1660 | * rl_add_defun: Function Naming. | |
1661 | * rl_begin_undo_group: Allowing Undoing. | |
1662 | * rl_bind_key (): Default Behaviour. | |
1663 | * rl_complete: How Completing Works. | |
1664 | * rl_complete: Completion Functions. | |
1665 | * rl_complete_internal: Completion Functions. | |
1666 | * rl_end_undo_group: Allowing Undoing. | |
1667 | * rl_generic_bind: Binding Keys. | |
1668 | * rl_modifying: Allowing Undoing. | |
1669 | * rl_possible_completions: Completion Functions. | |
1670 | * self-insert (a, b, A, 1, !, ...): Commands For Text. | |
1671 | * tab-insert (M-TAB): Commands For Text. | |
1672 | * transpose-chars (C-t): Commands For Text. | |
1673 | * transpose-words (M-t): Commands For Text. | |
1674 | * undo (C-_): Miscellaneous Commands. | |
1675 | * universal-argument (): Numeric Arguments. | |
1676 | * unix-line-discard (C-u): Commands For Killing. | |
1677 | * unix-word-rubout (C-w): Commands For Killing. | |
1678 | * upcase-word (M-u): Commands For Text. | |
1679 | * yank (C-y): Commands For Killing. | |
1680 | * yank-pop (M-y): Commands For Killing. | |
1681 | ||
1682 | ||
1683 | \1f | |
1684 | Tag Table: | |
1685 | Node: Top\7f998 | |
1686 | Node: Command Line Editing\7f1611 | |
1687 | Node: Introduction and Notation\7f2034 | |
1688 | Node: Readline Interaction\7f3056 | |
1689 | Node: Readline Bare Essentials\7f4195 | |
1690 | Node: Readline Movement Commands\7f5703 | |
1691 | Node: Readline Killing Commands\7f6594 | |
1692 | Node: Readline Arguments\7f8438 | |
1693 | Node: Readline Init File\7f9390 | |
1694 | Node: Readline Init Syntax\7f10218 | |
1695 | Node: Commands For Moving\7f14208 | |
1696 | Node: Commands For History\7f14838 | |
1697 | Node: Commands For Text\7f15913 | |
1698 | Node: Commands For Killing\7f17581 | |
1699 | Node: Numeric Arguments\7f18708 | |
1700 | Node: Commands For Completion\7f19152 | |
1701 | Node: Miscellaneous Commands\7f19876 | |
1702 | Node: Readline Vi Mode\7f20718 | |
1703 | Node: Programming with GNU Readline\7f22328 | |
1704 | Node: Default Behaviour\7f23033 | |
1705 | Node: Custom Functions\7f26258 | |
1706 | Node: The Function Type\7f27057 | |
1707 | Node: Function Naming\7f27690 | |
1708 | Node: Keymaps\7f28942 | |
1709 | Node: Binding Keys\7f29857 | |
1710 | Node: Function Writing\7f31158 | |
1711 | Node: Allowing Undoing\7f32599 | |
1712 | Node: Custom Completers\7f36101 | |
1713 | Node: How Completing Works\7f36849 | |
1714 | Node: Completion Functions\7f39664 | |
1715 | Node: Completion Variables\7f42000 | |
1716 | Node: A Short Completion Example\7f44772 | |
1717 | Node: Concept Index\7f56398 | |
1718 | Node: Function and Variable Index\7f56687 | |
1719 | \1f | |
1720 | End Tag Table |