|
3793
|
1 This is readline.info, produced by makeinfo version 4.0 from |
|
|
2 /usr/homes/chet/src/bash/readline-src/doc/rlman.texinfo. |
|
|
3 |
|
|
4 INFO-DIR-SECTION Libraries |
|
|
5 START-INFO-DIR-ENTRY |
|
|
6 * Readline: (readline). The GNU readline library API |
|
|
7 END-INFO-DIR-ENTRY |
|
|
8 |
|
|
9 This document describes the GNU Readline Library, a utility which |
|
|
10 aids in the consistency of user interface across discrete programs that |
|
|
11 need to provide a command line interface. |
|
|
12 |
|
|
13 Copyright (C) 1988-2001 Free Software Foundation, Inc. |
|
|
14 |
|
|
15 Permission is granted to make and distribute verbatim copies of this |
|
|
16 manual provided the copyright notice and this permission notice pare |
|
|
17 preserved on all copies. |
|
|
18 |
|
|
19 Permission is granted to copy and distribute modified versions of |
|
|
20 this manual under the conditions for verbatim copying, provided that |
|
|
21 the entire resulting derived work is distributed under the terms of a |
|
|
22 permission notice identical to this one. |
|
|
23 |
|
|
24 Permission is granted to copy and distribute translations of this |
|
|
25 manual into another language, under the above conditions for modified |
|
|
26 versions, except that this permission notice may be stated in a |
|
|
27 translation approved by the Free Software Foundation. |
|
|
28 |
|
|
29 |
|
|
30 File: readline.info, Node: Top, Next: Command Line Editing, Up: (dir) |
|
|
31 |
|
|
32 GNU Readline Library |
|
|
33 ******************** |
|
|
34 |
|
|
35 This document describes the GNU Readline Library, a utility which |
|
|
36 aids in the consistency of user interface across discrete programs that |
|
|
37 need to provide a command line interface. |
|
|
38 |
|
|
39 * Menu: |
|
|
40 |
|
|
41 * Command Line Editing:: GNU Readline User's Manual. |
|
|
42 * Programming with GNU Readline:: GNU Readline Programmer's Manual. |
|
|
43 * Concept Index:: Index of concepts described in this manual. |
|
|
44 * Function and Variable Index:: Index of externally visible functions |
|
|
45 and variables. |
|
|
46 |
|
|
47 |
|
|
48 File: readline.info, Node: Command Line Editing, Next: Programming with GNU Readline, Prev: Top, Up: Top |
|
|
49 |
|
|
50 Command Line Editing |
|
|
51 ******************** |
|
|
52 |
|
|
53 This chapter describes the basic features of the GNU command line |
|
|
54 editing interface. |
|
|
55 |
|
|
56 * Menu: |
|
|
57 |
|
|
58 * Introduction and Notation:: Notation used in this text. |
|
|
59 * Readline Interaction:: The minimum set of commands for editing a line. |
|
|
60 * Readline Init File:: Customizing Readline from a user's view. |
|
|
61 * Bindable Readline Commands:: A description of most of the Readline commands |
|
|
62 available for binding |
|
|
63 * Readline vi Mode:: A short description of how to make Readline |
|
|
64 behave like the vi editor. |
|
|
65 |
|
|
66 |
|
|
67 File: readline.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing |
|
|
68 |
|
|
69 Introduction to Line Editing |
|
|
70 ============================ |
|
|
71 |
|
|
72 The following paragraphs describe the notation used to represent |
|
|
73 keystrokes. |
|
|
74 |
|
|
75 The text `C-k' is read as `Control-K' and describes the character |
|
|
76 produced when the <k> key is pressed while the Control key is depressed. |
|
|
77 |
|
|
78 The text `M-k' is read as `Meta-K' and describes the character |
|
|
79 produced when the Meta key (if you have one) is depressed, and the <k> |
|
|
80 key is pressed. The Meta key is labeled <ALT> on many keyboards. On |
|
|
81 keyboards with two keys labeled <ALT> (usually to either side of the |
|
|
82 space bar), the <ALT> on the left side is generally set to work as a |
|
|
83 Meta key. The <ALT> key on the right may also be configured to work as |
|
|
84 a Meta key or may be configured as some other modifier, such as a |
|
|
85 Compose key for typing accented characters. |
|
|
86 |
|
|
87 If you do not have a Meta or <ALT> key, or another key working as a |
|
|
88 Meta key, the identical keystroke can be generated by typing <ESC> |
|
|
89 _first_, and then typing <k>. Either process is known as "metafying" |
|
|
90 the <k> key. |
|
|
91 |
|
|
92 The text `M-C-k' is read as `Meta-Control-k' and describes the |
|
|
93 character produced by "metafying" `C-k'. |
|
|
94 |
|
|
95 In addition, several keys have their own names. Specifically, |
|
|
96 <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves |
|
|
97 when seen in this text, or in an init file (*note Readline Init File::). |
|
|
98 If your keyboard lacks a <LFD> key, typing <C-j> will produce the |
|
|
99 desired character. The <RET> key may be labeled <Return> or <Enter> on |
|
|
100 some keyboards. |
|
|
101 |
|
|
102 |
|
|
103 File: readline.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing |
|
|
104 |
|
|
105 Readline Interaction |
|
|
106 ==================== |
|
|
107 |
|
|
108 Often during an interactive session you type in a long line of text, |
|
|
109 only to notice that the first word on the line is misspelled. The |
|
|
110 Readline library gives you a set of commands for manipulating the text |
|
|
111 as you type it in, allowing you to just fix your typo, and not forcing |
|
|
112 you to retype the majority of the line. Using these editing commands, |
|
|
113 you move the cursor to the place that needs correction, and delete or |
|
|
114 insert the text of the corrections. Then, when you are satisfied with |
|
|
115 the line, you simply press <RET>. You do not have to be at the end of |
|
|
116 the line to press <RET>; the entire line is accepted regardless of the |
|
|
117 location of the cursor within the line. |
|
|
118 |
|
|
119 * Menu: |
|
|
120 |
|
|
121 * Readline Bare Essentials:: The least you need to know about Readline. |
|
|
122 * Readline Movement Commands:: Moving about the input line. |
|
|
123 * Readline Killing Commands:: How to delete text, and how to get it back! |
|
|
124 * Readline Arguments:: Giving numeric arguments to commands. |
|
|
125 * Searching:: Searching through previous lines. |
|
|
126 |
|
|
127 |
|
|
128 File: readline.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction |
|
|
129 |
|
|
130 Readline Bare Essentials |
|
|
131 ------------------------ |
|
|
132 |
|
|
133 In order to enter characters into the line, simply type them. The |
|
|
134 typed character appears where the cursor was, and then the cursor moves |
|
|
135 one space to the right. If you mistype a character, you can use your |
|
|
136 erase character to back up and delete the mistyped character. |
|
|
137 |
|
|
138 Sometimes you may mistype a character, and not notice the error |
|
|
139 until you have typed several other characters. In that case, you can |
|
|
140 type `C-b' to move the cursor to the left, and then correct your |
|
|
141 mistake. Afterwards, you can move the cursor to the right with `C-f'. |
|
|
142 |
|
|
143 When you add text in the middle of a line, you will notice that |
|
|
144 characters to the right of the cursor are `pushed over' to make room |
|
|
145 for the text that you have inserted. Likewise, when you delete text |
|
|
146 behind the cursor, characters to the right of the cursor are `pulled |
|
|
147 back' to fill in the blank space created by the removal of the text. A |
|
|
148 list of the bare essentials for editing the text of an input line |
|
|
149 follows. |
|
|
150 |
|
|
151 `C-b' |
|
|
152 Move back one character. |
|
|
153 |
|
|
154 `C-f' |
|
|
155 Move forward one character. |
|
|
156 |
|
|
157 <DEL> or <Backspace> |
|
|
158 Delete the character to the left of the cursor. |
|
|
159 |
|
|
160 `C-d' |
|
|
161 Delete the character underneath the cursor. |
|
|
162 |
|
|
163 Printing characters |
|
|
164 Insert the character into the line at the cursor. |
|
|
165 |
|
|
166 `C-_' or `C-x C-u' |
|
|
167 Undo the last editing command. You can undo all the way back to an |
|
|
168 empty line. |
|
|
169 |
|
|
170 (Depending on your configuration, the <Backspace> key be set to delete |
|
|
171 the character to the left of the cursor and the <DEL> key set to delete |
|
|
172 the character underneath the cursor, like `C-d', rather than the |
|
|
173 character to the left of the cursor.) |
|
|
174 |
|
|
175 |
|
|
176 File: readline.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction |
|
|
177 |
|
|
178 Readline Movement Commands |
|
|
179 -------------------------- |
|
|
180 |
|
|
181 The above table describes the most basic keystrokes that you need in |
|
|
182 order to do editing of the input line. For your convenience, many |
|
|
183 other commands have been added in addition to `C-b', `C-f', `C-d', and |
|
|
184 <DEL>. Here are some commands for moving more rapidly about the line. |
|
|
185 |
|
|
186 `C-a' |
|
|
187 Move to the start of the line. |
|
|
188 |
|
|
189 `C-e' |
|
|
190 Move to the end of the line. |
|
|
191 |
|
|
192 `M-f' |
|
|
193 Move forward a word, where a word is composed of letters and |
|
|
194 digits. |
|
|
195 |
|
|
196 `M-b' |
|
|
197 Move backward a word. |
|
|
198 |
|
|
199 `C-l' |
|
|
200 Clear the screen, reprinting the current line at the top. |
|
|
201 |
|
|
202 Notice how `C-f' moves forward a character, while `M-f' moves |
|
|
203 forward a word. It is a loose convention that control keystrokes |
|
|
204 operate on characters while meta keystrokes operate on words. |
|
|
205 |
|
|
206 |
|
|
207 File: readline.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction |
|
|
208 |
|
|
209 Readline Killing Commands |
|
|
210 ------------------------- |
|
|
211 |
|
|
212 "Killing" text means to delete the text from the line, but to save |
|
|
213 it away for later use, usually by "yanking" (re-inserting) it back into |
|
|
214 the line. (`Cut' and `paste' are more recent jargon for `kill' and |
|
|
215 `yank'.) |
|
|
216 |
|
|
217 If the description for a command says that it `kills' text, then you |
|
|
218 can be sure that you can get the text back in a different (or the same) |
|
|
219 place later. |
|
|
220 |
|
|
221 When you use a kill command, the text is saved in a "kill-ring". |
|
|
222 Any number of consecutive kills save all of the killed text together, so |
|
|
223 that when you yank it back, you get it all. The kill ring is not line |
|
|
224 specific; the text that you killed on a previously typed line is |
|
|
225 available to be yanked back later, when you are typing another line. |
|
|
226 |
|
|
227 Here is the list of commands for killing text. |
|
|
228 |
|
|
229 `C-k' |
|
|
230 Kill the text from the current cursor position to the end of the |
|
|
231 line. |
|
|
232 |
|
|
233 `M-d' |
|
|
234 Kill from the cursor to the end of the current word, or, if between |
|
|
235 words, to the end of the next word. Word boundaries are the same |
|
|
236 as those used by `M-f'. |
|
|
237 |
|
|
238 `M-<DEL>' |
|
|
239 Kill from the cursor the start of the previous word, or, if between |
|
|
240 words, to the start of the previous word. Word boundaries are the |
|
|
241 same as those used by `M-b'. |
|
|
242 |
|
|
243 `C-w' |
|
|
244 Kill from the cursor to the previous whitespace. This is |
|
|
245 different than `M-<DEL>' because the word boundaries differ. |
|
|
246 |
|
|
247 Here is how to "yank" the text back into the line. Yanking means to |
|
|
248 copy the most-recently-killed text from the kill buffer. |
|
|
249 |
|
|
250 `C-y' |
|
|
251 Yank the most recently killed text back into the buffer at the |
|
|
252 cursor. |
|
|
253 |
|
|
254 `M-y' |
|
|
255 Rotate the kill-ring, and yank the new top. You can only do this |
|
|
256 if the prior command is `C-y' or `M-y'. |
|
|
257 |
|
|
258 |
|
|
259 File: readline.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction |
|
|
260 |
|
|
261 Readline Arguments |
|
|
262 ------------------ |
|
|
263 |
|
|
264 You can pass numeric arguments to Readline commands. Sometimes the |
|
|
265 argument acts as a repeat count, other times it is the sign of the |
|
|
266 argument that is significant. If you pass a negative argument to a |
|
|
267 command which normally acts in a forward direction, that command will |
|
|
268 act in a backward direction. For example, to kill text back to the |
|
|
269 start of the line, you might type `M-- C-k'. |
|
|
270 |
|
|
271 The general way to pass numeric arguments to a command is to type |
|
|
272 meta digits before the command. If the first `digit' typed is a minus |
|
|
273 sign (`-'), then the sign of the argument will be negative. Once you |
|
|
274 have typed one meta digit to get the argument started, you can type the |
|
|
275 remainder of the digits, and then the command. For example, to give |
|
|
276 the `C-d' command an argument of 10, you could type `M-1 0 C-d', which |
|
|
277 will delete the next ten characters on the input line. |
|
|
278 |
|
|
279 |
|
|
280 File: readline.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction |
|
|
281 |
|
|
282 Searching for Commands in the History |
|
|
283 ------------------------------------- |
|
|
284 |
|
|
285 Readline provides commands for searching through the command history |
|
|
286 for lines containing a specified string. There are two search modes: |
|
|
287 "incremental" and "non-incremental". |
|
|
288 |
|
|
289 Incremental searches begin before the user has finished typing the |
|
|
290 search string. As each character of the search string is typed, |
|
|
291 Readline displays the next entry from the history matching the string |
|
|
292 typed so far. An incremental search requires only as many characters |
|
|
293 as needed to find the desired history entry. To search backward in the |
|
|
294 history for a particular string, type `C-r'. Typing `C-s' searches |
|
|
295 forward through the history. The characters present in the value of |
|
|
296 the `isearch-terminators' variable are used to terminate an incremental |
|
|
297 search. If that variable has not been assigned a value, the <ESC> and |
|
|
298 `C-J' characters will terminate an incremental search. `C-g' will |
|
|
299 abort an incremental search and restore the original line. When the |
|
|
300 search is terminated, the history entry containing the search string |
|
|
301 becomes the current line. |
|
|
302 |
|
|
303 To find other matching entries in the history list, type `C-r' or |
|
|
304 `C-s' as appropriate. This will search backward or forward in the |
|
|
305 history for the next entry matching the search string typed so far. |
|
|
306 Any other key sequence bound to a Readline command will terminate the |
|
|
307 search and execute that command. For instance, a <RET> will terminate |
|
|
308 the search and accept the line, thereby executing the command from the |
|
|
309 history list. A movement command will terminate the search, make the |
|
|
310 last line found the current line, and begin editing. |
|
|
311 |
|
|
312 Non-incremental searches read the entire search string before |
|
|
313 starting to search for matching history lines. The search string may be |
|
|
314 typed by the user or be part of the contents of the current line. |
|
|
315 |
|
|
316 |
|
|
317 File: readline.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing |
|
|
318 |
|
|
319 Readline Init File |
|
|
320 ================== |
|
|
321 |
|
|
322 Although the Readline library comes with a set of Emacs-like |
|
|
323 keybindings installed by default, it is possible to use a different set |
|
|
324 of keybindings. Any user can customize programs that use Readline by |
|
|
325 putting commands in an "inputrc" file, conventionally in his home |
|
|
326 directory. The name of this file is taken from the value of the |
|
|
327 environment variable `INPUTRC'. If that variable is unset, the default |
|
|
328 is `~/.inputrc'. |
|
|
329 |
|
|
330 When a program which uses the Readline library starts up, the init |
|
|
331 file is read, and the key bindings are set. |
|
|
332 |
|
|
333 In addition, the `C-x C-r' command re-reads this init file, thus |
|
|
334 incorporating any changes that you might have made to it. |
|
|
335 |
|
|
336 * Menu: |
|
|
337 |
|
|
338 * Readline Init File Syntax:: Syntax for the commands in the inputrc file. |
|
|
339 |
|
|
340 * Conditional Init Constructs:: Conditional key bindings in the inputrc file. |
|
|
341 |
|
|
342 * Sample Init File:: An example inputrc file. |
|
|
343 |
|
|
344 |
|
|
345 File: readline.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File |
|
|
346 |
|
|
347 Readline Init File Syntax |
|
|
348 ------------------------- |
|
|
349 |
|
|
350 There are only a few basic constructs allowed in the Readline init |
|
|
351 file. Blank lines are ignored. Lines beginning with a `#' are |
|
|
352 comments. Lines beginning with a `$' indicate conditional constructs |
|
|
353 (*note Conditional Init Constructs::). Other lines denote variable |
|
|
354 settings and key bindings. |
|
|
355 |
|
|
356 Variable Settings |
|
|
357 You can modify the run-time behavior of Readline by altering the |
|
|
358 values of variables in Readline using the `set' command within the |
|
|
359 init file. Here is how to change from the default Emacs-like key |
|
|
360 binding to use `vi' line editing commands: |
|
|
361 |
|
|
362 set editing-mode vi |
|
|
363 |
|
|
364 A great deal of run-time behavior is changeable with the following |
|
|
365 variables. |
|
|
366 |
|
|
367 `bell-style' |
|
|
368 Controls what happens when Readline wants to ring the |
|
|
369 terminal bell. If set to `none', Readline never rings the |
|
|
370 bell. If set to `visible', Readline uses a visible bell if |
|
|
371 one is available. If set to `audible' (the default), |
|
|
372 Readline attempts to ring the terminal's bell. |
|
|
373 |
|
|
374 `comment-begin' |
|
|
375 The string to insert at the beginning of the line when the |
|
|
376 `insert-comment' command is executed. The default value is |
|
|
377 `"#"'. |
|
|
378 |
|
|
379 `completion-ignore-case' |
|
|
380 If set to `on', Readline performs filename matching and |
|
|
381 completion in a case-insensitive fashion. The default value |
|
|
382 is `off'. |
|
|
383 |
|
|
384 `completion-query-items' |
|
|
385 The number of possible completions that determines when the |
|
|
386 user is asked whether he wants to see the list of |
|
|
387 possibilities. If the number of possible completions is |
|
|
388 greater than this value, Readline will ask the user whether |
|
|
389 or not he wishes to view them; otherwise, they are simply |
|
|
390 listed. This variable must be set to an integer value |
|
|
391 greater than or equal to 0. The default limit is `100'. |
|
|
392 |
|
|
393 `convert-meta' |
|
|
394 If set to `on', Readline will convert characters with the |
|
|
395 eighth bit set to an ASCII key sequence by stripping the |
|
|
396 eighth bit and prefixing an <ESC> character, converting them |
|
|
397 to a meta-prefixed key sequence. The default value is `on'. |
|
|
398 |
|
|
399 `disable-completion' |
|
|
400 If set to `On', Readline will inhibit word completion. |
|
|
401 Completion characters will be inserted into the line as if |
|
|
402 they had been mapped to `self-insert'. The default is `off'. |
|
|
403 |
|
|
404 `editing-mode' |
|
|
405 The `editing-mode' variable controls which default set of key |
|
|
406 bindings is used. By default, Readline starts up in Emacs |
|
|
407 editing mode, where the keystrokes are most similar to Emacs. |
|
|
408 This variable can be set to either `emacs' or `vi'. |
|
|
409 |
|
|
410 `enable-keypad' |
|
|
411 When set to `on', Readline will try to enable the application |
|
|
412 keypad when it is called. Some systems need this to enable |
|
|
413 the arrow keys. The default is `off'. |
|
|
414 |
|
|
415 `expand-tilde' |
|
|
416 If set to `on', tilde expansion is performed when Readline |
|
|
417 attempts word completion. The default is `off'. |
|
|
418 |
|
|
419 `horizontal-scroll-mode' |
|
|
420 This variable can be set to either `on' or `off'. Setting it |
|
|
421 to `on' means that the text of the lines being edited will |
|
|
422 scroll horizontally on a single screen line when they are |
|
|
423 longer than the width of the screen, instead of wrapping onto |
|
|
424 a new screen line. By default, this variable is set to `off'. |
|
|
425 |
|
|
426 `input-meta' |
|
|
427 If set to `on', Readline will enable eight-bit input (it will |
|
|
428 not clear the eighth bit in the characters it reads), |
|
|
429 regardless of what the terminal claims it can support. The |
|
|
430 default value is `off'. The name `meta-flag' is a synonym |
|
|
431 for this variable. |
|
|
432 |
|
|
433 `isearch-terminators' |
|
|
434 The string of characters that should terminate an incremental |
|
|
435 search without subsequently executing the character as a |
|
|
436 command (*note Searching::). If this variable has not been |
|
|
437 given a value, the characters <ESC> and `C-J' will terminate |
|
|
438 an incremental search. |
|
|
439 |
|
|
440 `keymap' |
|
|
441 Sets Readline's idea of the current keymap for key binding |
|
|
442 commands. Acceptable `keymap' names are `emacs', |
|
|
443 `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', |
|
|
444 `vi-command', and `vi-insert'. `vi' is equivalent to |
|
|
445 `vi-command'; `emacs' is equivalent to `emacs-standard'. The |
|
|
446 default value is `emacs'. The value of the `editing-mode' |
|
|
447 variable also affects the default keymap. |
|
|
448 |
|
|
449 `mark-directories' |
|
|
450 If set to `on', completed directory names have a slash |
|
|
451 appended. The default is `on'. |
|
|
452 |
|
|
453 `mark-modified-lines' |
|
|
454 This variable, when set to `on', causes Readline to display an |
|
|
455 asterisk (`*') at the start of history lines which have been |
|
|
456 modified. This variable is `off' by default. |
|
|
457 |
|
|
458 `output-meta' |
|
|
459 If set to `on', Readline will display characters with the |
|
|
460 eighth bit set directly rather than as a meta-prefixed escape |
|
|
461 sequence. The default is `off'. |
|
|
462 |
|
|
463 `print-completions-horizontally' |
|
|
464 If set to `on', Readline will display completions with matches |
|
|
465 sorted horizontally in alphabetical order, rather than down |
|
|
466 the screen. The default is `off'. |
|
|
467 |
|
|
468 `show-all-if-ambiguous' |
|
|
469 This alters the default behavior of the completion functions. |
|
|
470 If set to `on', words which have more than one possible |
|
|
471 completion cause the matches to be listed immediately instead |
|
|
472 of ringing the bell. The default value is `off'. |
|
|
473 |
|
|
474 `visible-stats' |
|
|
475 If set to `on', a character denoting a file's type is |
|
|
476 appended to the filename when listing possible completions. |
|
|
477 The default is `off'. |
|
|
478 |
|
|
479 Key Bindings |
|
|
480 The syntax for controlling key bindings in the init file is |
|
|
481 simple. First you need to find the name of the command that you |
|
|
482 want to change. The following sections contain tables of the |
|
|
483 command name, the default keybinding, if any, and a short |
|
|
484 description of what the command does. |
|
|
485 |
|
|
486 Once you know the name of the command, simply place on a line in |
|
|
487 the init file the name of the key you wish to bind the command to, |
|
|
488 a colon, and then the name of the command. The name of the key |
|
|
489 can be expressed in different ways, depending on what you find most |
|
|
490 comfortable. |
|
|
491 |
|
|
492 KEYNAME: FUNCTION-NAME or MACRO |
|
|
493 KEYNAME is the name of a key spelled out in English. For |
|
|
494 example: |
|
|
495 Control-u: universal-argument |
|
|
496 Meta-Rubout: backward-kill-word |
|
|
497 Control-o: "> output" |
|
|
498 |
|
|
499 In the above example, `C-u' is bound to the function |
|
|
500 `universal-argument', `M-DEL' is bound to the function |
|
|
501 `backward-kill-word', and `C-o' is bound to run the macro |
|
|
502 expressed on the right hand side (that is, to insert the text |
|
|
503 `> output' into the line). |
|
|
504 |
|
|
505 A number of symbolic character names are recognized while |
|
|
506 processing this key binding syntax: DEL, ESC, ESCAPE, LFD, |
|
|
507 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. |
|
|
508 |
|
|
509 "KEYSEQ": FUNCTION-NAME or MACRO |
|
|
510 KEYSEQ differs from KEYNAME above in that strings denoting an |
|
|
511 entire key sequence can be specified, by placing the key |
|
|
512 sequence in double quotes. Some GNU Emacs style key escapes |
|
|
513 can be used, as in the following example, but the special |
|
|
514 character names are not recognized. |
|
|
515 |
|
|
516 "\C-u": universal-argument |
|
|
517 "\C-x\C-r": re-read-init-file |
|
|
518 "\e[11~": "Function Key 1" |
|
|
519 |
|
|
520 In the above example, `C-u' is again bound to the function |
|
|
521 `universal-argument' (just as it was in the first example), |
|
|
522 `C-x C-r' is bound to the function `re-read-init-file', and |
|
|
523 `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function |
|
|
524 Key 1'. |
|
|
525 |
|
|
526 The following GNU Emacs style escape sequences are available when |
|
|
527 specifying key sequences: |
|
|
528 |
|
|
529 `\C-' |
|
|
530 control prefix |
|
|
531 |
|
|
532 `\M-' |
|
|
533 meta prefix |
|
|
534 |
|
|
535 `\e' |
|
|
536 an escape character |
|
|
537 |
|
|
538 `\\' |
|
|
539 backslash |
|
|
540 |
|
|
541 `\"' |
|
|
542 <">, a double quotation mark |
|
|
543 |
|
|
544 `\'' |
|
|
545 <'>, a single quote or apostrophe |
|
|
546 |
|
|
547 In addition to the GNU Emacs style escape sequences, a second set |
|
|
548 of backslash escapes is available: |
|
|
549 |
|
|
550 `\a' |
|
|
551 alert (bell) |
|
|
552 |
|
|
553 `\b' |
|
|
554 backspace |
|
|
555 |
|
|
556 `\d' |
|
|
557 delete |
|
|
558 |
|
|
559 `\f' |
|
|
560 form feed |
|
|
561 |
|
|
562 `\n' |
|
|
563 newline |
|
|
564 |
|
|
565 `\r' |
|
|
566 carriage return |
|
|
567 |
|
|
568 `\t' |
|
|
569 horizontal tab |
|
|
570 |
|
|
571 `\v' |
|
|
572 vertical tab |
|
|
573 |
|
|
574 `\NNN' |
|
|
575 the character whose ASCII code is the octal value NNN (one to |
|
|
576 three digits) |
|
|
577 |
|
|
578 `\xNNN' |
|
|
579 the character whose ASCII code is the hexadecimal value NNN |
|
|
580 (one to three digits) |
|
|
581 |
|
|
582 When entering the text of a macro, single or double quotes must be |
|
|
583 used to indicate a macro definition. Unquoted text is assumed to |
|
|
584 be a function name. In the macro body, the backslash escapes |
|
|
585 described above are expanded. Backslash will quote any other |
|
|
586 character in the macro text, including `"' and `''. For example, |
|
|
587 the following binding will make `C-x \' insert a single `\' into |
|
|
588 the line: |
|
|
589 "\C-x\\": "\\" |
|
|
590 |
|
|
591 |
|
|
592 File: readline.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File |
|
|
593 |
|
|
594 Conditional Init Constructs |
|
|
595 --------------------------- |
|
|
596 |
|
|
597 Readline implements a facility similar in spirit to the conditional |
|
|
598 compilation features of the C preprocessor which allows key bindings |
|
|
599 and variable settings to be performed as the result of tests. There |
|
|
600 are four parser directives used. |
|
|
601 |
|
|
602 `$if' |
|
|
603 The `$if' construct allows bindings to be made based on the |
|
|
604 editing mode, the terminal being used, or the application using |
|
|
605 Readline. The text of the test extends to the end of the line; no |
|
|
606 characters are required to isolate it. |
|
|
607 |
|
|
608 `mode' |
|
|
609 The `mode=' form of the `$if' directive is used to test |
|
|
610 whether Readline is in `emacs' or `vi' mode. This may be |
|
|
611 used in conjunction with the `set keymap' command, for |
|
|
612 instance, to set bindings in the `emacs-standard' and |
|
|
613 `emacs-ctlx' keymaps only if Readline is starting out in |
|
|
614 `emacs' mode. |
|
|
615 |
|
|
616 `term' |
|
|
617 The `term=' form may be used to include terminal-specific key |
|
|
618 bindings, perhaps to bind the key sequences output by the |
|
|
619 terminal's function keys. The word on the right side of the |
|
|
620 `=' is tested against both the full name of the terminal and |
|
|
621 the portion of the terminal name before the first `-'. This |
|
|
622 allows `sun' to match both `sun' and `sun-cmd', for instance. |
|
|
623 |
|
|
624 `application' |
|
|
625 The APPLICATION construct is used to include |
|
|
626 application-specific settings. Each program using the |
|
|
627 Readline library sets the APPLICATION NAME, and you can test |
|
|
628 for it. This could be used to bind key sequences to |
|
|
629 functions useful for a specific program. For instance, the |
|
|
630 following command adds a key sequence that quotes the current |
|
|
631 or previous word in Bash: |
|
|
632 $if Bash |
|
|
633 # Quote the current or previous word |
|
|
634 "\C-xq": "\eb\"\ef\"" |
|
|
635 $endif |
|
|
636 |
|
|
637 `$endif' |
|
|
638 This command, as seen in the previous example, terminates an `$if' |
|
|
639 command. |
|
|
640 |
|
|
641 `$else' |
|
|
642 Commands in this branch of the `$if' directive are executed if the |
|
|
643 test fails. |
|
|
644 |
|
|
645 `$include' |
|
|
646 This directive takes a single filename as an argument and reads |
|
|
647 commands and bindings from that file. |
|
|
648 $include /etc/inputrc |
|
|
649 |
|
|
650 |
|
|
651 File: readline.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File |
|
|
652 |
|
|
653 Sample Init File |
|
|
654 ---------------- |
|
|
655 |
|
|
656 Here is an example of an INPUTRC file. This illustrates key |
|
|
657 binding, variable assignment, and conditional syntax. |
|
|
658 |
|
|
659 |
|
|
660 # This file controls the behaviour of line input editing for |
|
|
661 # programs that use the Gnu Readline library. Existing programs |
|
|
662 # include FTP, Bash, and Gdb. |
|
|
663 # |
|
|
664 # You can re-read the inputrc file with C-x C-r. |
|
|
665 # Lines beginning with '#' are comments. |
|
|
666 # |
|
|
667 # First, include any systemwide bindings and variable assignments from |
|
|
668 # /etc/Inputrc |
|
|
669 $include /etc/Inputrc |
|
|
670 |
|
|
671 # |
|
|
672 # Set various bindings for emacs mode. |
|
|
673 |
|
|
674 set editing-mode emacs |
|
|
675 |
|
|
676 $if mode=emacs |
|
|
677 |
|
|
678 Meta-Control-h: backward-kill-word Text after the function name is ignored |
|
|
679 |
|
|
680 # |
|
|
681 # Arrow keys in keypad mode |
|
|
682 # |
|
|
683 #"\M-OD": backward-char |
|
|
684 #"\M-OC": forward-char |
|
|
685 #"\M-OA": previous-history |
|
|
686 #"\M-OB": next-history |
|
|
687 # |
|
|
688 # Arrow keys in ANSI mode |
|
|
689 # |
|
|
690 "\M-[D": backward-char |
|
|
691 "\M-[C": forward-char |
|
|
692 "\M-[A": previous-history |
|
|
693 "\M-[B": next-history |
|
|
694 # |
|
|
695 # Arrow keys in 8 bit keypad mode |
|
|
696 # |
|
|
697 #"\M-\C-OD": backward-char |
|
|
698 #"\M-\C-OC": forward-char |
|
|
699 #"\M-\C-OA": previous-history |
|
|
700 #"\M-\C-OB": next-history |
|
|
701 # |
|
|
702 # Arrow keys in 8 bit ANSI mode |
|
|
703 # |
|
|
704 #"\M-\C-[D": backward-char |
|
|
705 #"\M-\C-[C": forward-char |
|
|
706 #"\M-\C-[A": previous-history |
|
|
707 #"\M-\C-[B": next-history |
|
|
708 |
|
|
709 C-q: quoted-insert |
|
|
710 |
|
|
711 $endif |
|
|
712 |
|
|
713 # An old-style binding. This happens to be the default. |
|
|
714 TAB: complete |
|
|
715 |
|
|
716 # Macros that are convenient for shell interaction |
|
|
717 $if Bash |
|
|
718 # edit the path |
|
|
719 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" |
|
|
720 # prepare to type a quoted word -- insert open and close double quotes |
|
|
721 # and move to just after the open quote |
|
|
722 "\C-x\"": "\"\"\C-b" |
|
|
723 # insert a backslash (testing backslash escapes in sequences and macros) |
|
|
724 "\C-x\\": "\\" |
|
|
725 # Quote the current or previous word |
|
|
726 "\C-xq": "\eb\"\ef\"" |
|
|
727 # Add a binding to refresh the line, which is unbound |
|
|
728 "\C-xr": redraw-current-line |
|
|
729 # Edit variable on current line. |
|
|
730 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" |
|
|
731 $endif |
|
|
732 |
|
|
733 # use a visible bell if one is available |
|
|
734 set bell-style visible |
|
|
735 |
|
|
736 # don't strip characters to 7 bits when reading |
|
|
737 set input-meta on |
|
|
738 |
|
|
739 # allow iso-latin1 characters to be inserted rather than converted to |
|
|
740 # prefix-meta sequences |
|
|
741 set convert-meta off |
|
|
742 |
|
|
743 # display characters with the eighth bit set directly rather than |
|
|
744 # as meta-prefixed characters |
|
|
745 set output-meta on |
|
|
746 |
|
|
747 # if there are more than 150 possible completions for a word, ask the |
|
|
748 # user if he wants to see all of them |
|
|
749 set completion-query-items 150 |
|
|
750 |
|
|
751 # For FTP |
|
|
752 $if Ftp |
|
|
753 "\C-xg": "get \M-?" |
|
|
754 "\C-xt": "put \M-?" |
|
|
755 "\M-.": yank-last-arg |
|
|
756 $endif |
|
|
757 |
|
|
758 |
|
|
759 File: readline.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing |
|
|
760 |
|
|
761 Bindable Readline Commands |
|
|
762 ========================== |
|
|
763 |
|
|
764 * Menu: |
|
|
765 |
|
|
766 * Commands For Moving:: Moving about the line. |
|
|
767 * Commands For History:: Getting at previous lines. |
|
|
768 * Commands For Text:: Commands for changing text. |
|
|
769 * Commands For Killing:: Commands for killing and yanking. |
|
|
770 * Numeric Arguments:: Specifying numeric arguments, repeat counts. |
|
|
771 * Commands For Completion:: Getting Readline to do the typing for you. |
|
|
772 * Keyboard Macros:: Saving and re-executing typed characters |
|
|
773 * Miscellaneous Commands:: Other miscellaneous commands. |
|
|
774 |
|
|
775 This section describes Readline commands that may be bound to key |
|
|
776 sequences. |
|
|
777 |
|
|
778 Command names without an accompanying key sequence are unbound by |
|
|
779 default. In the following descriptions, "point" refers to the current |
|
|
780 cursor position, and "mark" refers to a cursor position saved by the |
|
|
781 `set-mark' command. The text between the point and mark is referred to |
|
|
782 as the "region". |
|
|
783 |
|
|
784 |
|
|
785 File: readline.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands |
|
|
786 |
|
|
787 Commands For Moving |
|
|
788 ------------------- |
|
|
789 |
|
|
790 `beginning-of-line (C-a)' |
|
|
791 Move to the start of the current line. |
|
|
792 |
|
|
793 `end-of-line (C-e)' |
|
|
794 Move to the end of the line. |
|
|
795 |
|
|
796 `forward-char (C-f)' |
|
|
797 Move forward a character. |
|
|
798 |
|
|
799 `backward-char (C-b)' |
|
|
800 Move back a character. |
|
|
801 |
|
|
802 `forward-word (M-f)' |
|
|
803 Move forward to the end of the next word. Words are composed of |
|
|
804 letters and digits. |
|
|
805 |
|
|
806 `backward-word (M-b)' |
|
|
807 Move back to the start of the current or previous word. Words are |
|
|
808 composed of letters and digits. |
|
|
809 |
|
|
810 `clear-screen (C-l)' |
|
|
811 Clear the screen and redraw the current line, leaving the current |
|
|
812 line at the top of the screen. |
|
|
813 |
|
|
814 `redraw-current-line ()' |
|
|
815 Refresh the current line. By default, this is unbound. |
|
|
816 |
|
|
817 |
|
|
818 File: readline.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands |
|
|
819 |
|
|
820 Commands For Manipulating The History |
|
|
821 ------------------------------------- |
|
|
822 |
|
|
823 `accept-line (Newline or Return)' |
|
|
824 Accept the line regardless of where the cursor is. If this line is |
|
|
825 non-empty, it may be added to the history list for future recall |
|
|
826 with `add_history()'. If this line is a modified history line, |
|
|
827 then restore the history line to its original state. |
|
|
828 |
|
|
829 `previous-history (C-p)' |
|
|
830 Move `up' through the history list. |
|
|
831 |
|
|
832 `next-history (C-n)' |
|
|
833 Move `down' through the history list. |
|
|
834 |
|
|
835 `beginning-of-history (M-<)' |
|
|
836 Move to the first line in the history. |
|
|
837 |
|
|
838 `end-of-history (M->)' |
|
|
839 Move to the end of the input history, i.e., the line currently |
|
|
840 being entered. |
|
|
841 |
|
|
842 `reverse-search-history (C-r)' |
|
|
843 Search backward starting at the current line and moving `up' |
|
|
844 through the history as necessary. This is an incremental search. |
|
|
845 |
|
|
846 `forward-search-history (C-s)' |
|
|
847 Search forward starting at the current line and moving `down' |
|
|
848 through the the history as necessary. This is an incremental |
|
|
849 search. |
|
|
850 |
|
|
851 `non-incremental-reverse-search-history (M-p)' |
|
|
852 Search backward starting at the current line and moving `up' |
|
|
853 through the history as necessary using a non-incremental search |
|
|
854 for a string supplied by the user. |
|
|
855 |
|
|
856 `non-incremental-forward-search-history (M-n)' |
|
|
857 Search forward starting at the current line and moving `down' |
|
|
858 through the the history as necessary using a non-incremental search |
|
|
859 for a string supplied by the user. |
|
|
860 |
|
|
861 `history-search-forward ()' |
|
|
862 Search forward through the history for the string of characters |
|
|
863 between the start of the current line and the point. This is a |
|
|
864 non-incremental search. By default, this command is unbound. |
|
|
865 |
|
|
866 `history-search-backward ()' |
|
|
867 Search backward through the history for the string of characters |
|
|
868 between the start of the current line and the point. This is a |
|
|
869 non-incremental search. By default, this command is unbound. |
|
|
870 |
|
|
871 `yank-nth-arg (M-C-y)' |
|
|
872 Insert the first argument to the previous command (usually the |
|
|
873 second word on the previous line). With an argument N, insert the |
|
|
874 Nth word from the previous command (the words in the previous |
|
|
875 command begin with word 0). A negative argument inserts the Nth |
|
|
876 word from the end of the previous command. |
|
|
877 |
|
|
878 `yank-last-arg (M-. or M-_)' |
|
|
879 Insert last argument to the previous command (the last word of the |
|
|
880 previous history entry). With an argument, behave exactly like |
|
|
881 `yank-nth-arg'. Successive calls to `yank-last-arg' move back |
|
|
882 through the history list, inserting the last argument of each line |
|
|
883 in turn. |
|
|
884 |
|
|
885 |
|
|
886 File: readline.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands |
|
|
887 |
|
|
888 Commands For Changing Text |
|
|
889 -------------------------- |
|
|
890 |
|
|
891 `delete-char (C-d)' |
|
|
892 Delete the character under the cursor. If the cursor is at the |
|
|
893 beginning of the line, there are no characters in the line, and |
|
|
894 the last character typed was not bound to `delete-char', then |
|
|
895 return EOF. |
|
|
896 |
|
|
897 `backward-delete-char (Rubout)' |
|
|
898 Delete the character behind the cursor. A numeric argument means |
|
|
899 to kill the characters instead of deleting them. |
|
|
900 |
|
|
901 `forward-backward-delete-char ()' |
|
|
902 Delete the character under the cursor, unless the cursor is at the |
|
|
903 end of the line, in which case the character behind the cursor is |
|
|
904 deleted. By default, this is not bound to a key. |
|
|
905 |
|
|
906 `quoted-insert (C-q or C-v)' |
|
|
907 Add the next character typed to the line verbatim. This is how to |
|
|
908 insert key sequences like `C-q', for example. |
|
|
909 |
|
|
910 `tab-insert (M-<TAB>)' |
|
|
911 Insert a tab character. |
|
|
912 |
|
|
913 `self-insert (a, b, A, 1, !, ...)' |
|
|
914 Insert yourself. |
|
|
915 |
|
|
916 `transpose-chars (C-t)' |
|
|
917 Drag the character before the cursor forward over the character at |
|
|
918 the cursor, moving the cursor forward as well. If the insertion |
|
|
919 point is at the end of the line, then this transposes the last two |
|
|
920 characters of the line. Negative arguments have no effect. |
|
|
921 |
|
|
922 `transpose-words (M-t)' |
|
|
923 Drag the word before point past the word after point, moving point |
|
|
924 past that word as well. |
|
|
925 |
|
|
926 `upcase-word (M-u)' |
|
|
927 Uppercase the current (or following) word. With a negative |
|
|
928 argument, uppercase the previous word, but do not move the cursor. |
|
|
929 |
|
|
930 `downcase-word (M-l)' |
|
|
931 Lowercase the current (or following) word. With a negative |
|
|
932 argument, lowercase the previous word, but do not move the cursor. |
|
|
933 |
|
|
934 `capitalize-word (M-c)' |
|
|
935 Capitalize the current (or following) word. With a negative |
|
|
936 argument, capitalize the previous word, but do not move the cursor. |
|
|
937 |
|
|
938 |
|
|
939 File: readline.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands |
|
|
940 |
|
|
941 Killing And Yanking |
|
|
942 ------------------- |
|
|
943 |
|
|
944 `kill-line (C-k)' |
|
|
945 Kill the text from point to the end of the line. |
|
|
946 |
|
|
947 `backward-kill-line (C-x Rubout)' |
|
|
948 Kill backward to the beginning of the line. |
|
|
949 |
|
|
950 `unix-line-discard (C-u)' |
|
|
951 Kill backward from the cursor to the beginning of the current line. |
|
|
952 |
|
|
953 `kill-whole-line ()' |
|
|
954 Kill all characters on the current line, no matter point is. By |
|
|
955 default, this is unbound. |
|
|
956 |
|
|
957 `kill-word (M-d)' |
|
|
958 Kill from point to the end of the current word, or if between |
|
|
959 words, to the end of the next word. Word boundaries are the same |
|
|
960 as `forward-word'. |
|
|
961 |
|
|
962 `backward-kill-word (M-<DEL>)' |
|
|
963 Kill the word behind point. Word boundaries are the same as |
|
|
964 `backward-word'. |
|
|
965 |
|
|
966 `unix-word-rubout (C-w)' |
|
|
967 Kill the word behind point, using white space as a word boundary. |
|
|
968 The killed text is saved on the kill-ring. |
|
|
969 |
|
|
970 `delete-horizontal-space ()' |
|
|
971 Delete all spaces and tabs around point. By default, this is |
|
|
972 unbound. |
|
|
973 |
|
|
974 `kill-region ()' |
|
|
975 Kill the text in the current region. By default, this command is |
|
|
976 unbound. |
|
|
977 |
|
|
978 `copy-region-as-kill ()' |
|
|
979 Copy the text in the region to the kill buffer, so it can be yanked |
|
|
980 right away. By default, this command is unbound. |
|
|
981 |
|
|
982 `copy-backward-word ()' |
|
|
983 Copy the word before point to the kill buffer. The word |
|
|
984 boundaries are the same as `backward-word'. By default, this |
|
|
985 command is unbound. |
|
|
986 |
|
|
987 `copy-forward-word ()' |
|
|
988 Copy the word following point to the kill buffer. The word |
|
|
989 boundaries are the same as `forward-word'. By default, this |
|
|
990 command is unbound. |
|
|
991 |
|
|
992 `yank (C-y)' |
|
|
993 Yank the top of the kill ring into the buffer at the current |
|
|
994 cursor position. |
|
|
995 |
|
|
996 `yank-pop (M-y)' |
|
|
997 Rotate the kill-ring, and yank the new top. You can only do this |
|
|
998 if the prior command is `yank' or `yank-pop'. |
|
|
999 |
|
|
1000 |
|
|
1001 File: readline.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands |
|
|
1002 |
|
|
1003 Specifying Numeric Arguments |
|
|
1004 ---------------------------- |
|
|
1005 |
|
|
1006 `digit-argument (M-0, M-1, ... M--)' |
|
|
1007 Add this digit to the argument already accumulating, or start a new |
|
|
1008 argument. `M--' starts a negative argument. |
|
|
1009 |
|
|
1010 `universal-argument ()' |
|
|
1011 This is another way to specify an argument. If this command is |
|
|
1012 followed by one or more digits, optionally with a leading minus |
|
|
1013 sign, those digits define the argument. If the command is |
|
|
1014 followed by digits, executing `universal-argument' again ends the |
|
|
1015 numeric argument, but is otherwise ignored. As a special case, if |
|
|
1016 this command is immediately followed by a character that is |
|
|
1017 neither a digit or minus sign, the argument count for the next |
|
|
1018 command is multiplied by four. The argument count is initially |
|
|
1019 one, so executing this function the first time makes the argument |
|
|
1020 count four, a second time makes the argument count sixteen, and so |
|
|
1021 on. By default, this is not bound to a key. |
|
|
1022 |
|
|
1023 |
|
|
1024 File: readline.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands |
|
|
1025 |
|
|
1026 Letting Readline Type For You |
|
|
1027 ----------------------------- |
|
|
1028 |
|
|
1029 `complete (<TAB>)' |
|
|
1030 Attempt to perform completion on the text before point. The |
|
|
1031 actual completion performed is application-specific. The default |
|
|
1032 is filename completion. |
|
|
1033 |
|
|
1034 `possible-completions (M-?)' |
|
|
1035 List the possible completions of the text before the cursor. |
|
|
1036 |
|
|
1037 `insert-completions (M-*)' |
|
|
1038 Insert all completions of the text before point that would have |
|
|
1039 been generated by `possible-completions'. |
|
|
1040 |
|
|
1041 `menu-complete ()' |
|
|
1042 Similar to `complete', but replaces the word to be completed with |
|
|
1043 a single match from the list of possible completions. Repeated |
|
|
1044 execution of `menu-complete' steps through the list of possible |
|
|
1045 completions, inserting each match in turn. At the end of the list |
|
|
1046 of completions, the bell is rung and the original text is restored. |
|
|
1047 An argument of N moves N positions forward in the list of matches; |
|
|
1048 a negative argument may be used to move backward through the list. |
|
|
1049 This command is intended to be bound to <TAB>, but is unbound by |
|
|
1050 default. |
|
|
1051 |
|
|
1052 `delete-char-or-list ()' |
|
|
1053 Deletes the character under the cursor if not at the beginning or |
|
|
1054 end of the line (like `delete-char'). If at the end of the line, |
|
|
1055 behaves identically to `possible-completions'. This command is |
|
|
1056 unbound by default. |
|
|
1057 |
|
|
1058 |
|
|
1059 File: readline.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands |
|
|
1060 |
|
|
1061 Keyboard Macros |
|
|
1062 --------------- |
|
|
1063 |
|
|
1064 `start-kbd-macro (C-x ()' |
|
|
1065 Begin saving the characters typed into the current keyboard macro. |
|
|
1066 |
|
|
1067 `end-kbd-macro (C-x ))' |
|
|
1068 Stop saving the characters typed into the current keyboard macro |
|
|
1069 and save the definition. |
|
|
1070 |
|
|
1071 `call-last-kbd-macro (C-x e)' |
|
|
1072 Re-execute the last keyboard macro defined, by making the |
|
|
1073 characters in the macro appear as if typed at the keyboard. |
|
|
1074 |
|
|
1075 |
|
|
1076 File: readline.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands |
|
|
1077 |
|
|
1078 Some Miscellaneous Commands |
|
|
1079 --------------------------- |
|
|
1080 |
|
|
1081 `re-read-init-file (C-x C-r)' |
|
|
1082 Read in the contents of the INPUTRC file, and incorporate any |
|
|
1083 bindings or variable assignments found there. |
|
|
1084 |
|
|
1085 `abort (C-g)' |
|
|
1086 Abort the current editing command and ring the terminal's bell |
|
|
1087 (subject to the setting of `bell-style'). |
|
|
1088 |
|
|
1089 `do-uppercase-version (M-a, M-b, M-X, ...)' |
|
|
1090 If the metafied character X is lowercase, run the command that is |
|
|
1091 bound to the corresponding uppercase character. |
|
|
1092 |
|
|
1093 `prefix-meta (<ESC>)' |
|
|
1094 Make the next character typed be metafied. This is for keyboards |
|
|
1095 without a meta key. Typing `<ESC> f' is equivalent to typing |
|
|
1096 `M-f'. |
|
|
1097 |
|
|
1098 `undo (C-_ or C-x C-u)' |
|
|
1099 Incremental undo, separately remembered for each line. |
|
|
1100 |
|
|
1101 `revert-line (M-r)' |
|
|
1102 Undo all changes made to this line. This is like executing the |
|
|
1103 `undo' command enough times to get back to the beginning. |
|
|
1104 |
|
|
1105 `tilde-expand (M-~)' |
|
|
1106 Perform tilde expansion on the current word. |
|
|
1107 |
|
|
1108 `set-mark (C-@)' |
|
|
1109 Set the mark to the current point. If a numeric argument is |
|
|
1110 supplied, the mark is set to that position. |
|
|
1111 |
|
|
1112 `exchange-point-and-mark (C-x C-x)' |
|
|
1113 Swap the point with the mark. The current cursor position is set |
|
|
1114 to the saved position, and the old cursor position is saved as the |
|
|
1115 mark. |
|
|
1116 |
|
|
1117 `character-search (C-])' |
|
|
1118 A character is read and point is moved to the next occurrence of |
|
|
1119 that character. A negative count searches for previous |
|
|
1120 occurrences. |
|
|
1121 |
|
|
1122 `character-search-backward (M-C-])' |
|
|
1123 A character is read and point is moved to the previous occurrence |
|
|
1124 of that character. A negative count searches for subsequent |
|
|
1125 occurrences. |
|
|
1126 |
|
|
1127 `insert-comment (M-#)' |
|
|
1128 The value of the `comment-begin' variable is inserted at the |
|
|
1129 beginning of the current line, and the line is accepted as if a |
|
|
1130 newline had been typed. |
|
|
1131 |
|
|
1132 `dump-functions ()' |
|
|
1133 Print all of the functions and their key bindings to the Readline |
|
|
1134 output stream. If a numeric argument is supplied, the output is |
|
|
1135 formatted in such a way that it can be made part of an INPUTRC |
|
|
1136 file. This command is unbound by default. |
|
|
1137 |
|
|
1138 `dump-variables ()' |
|
|
1139 Print all of the settable variables and their values to the |
|
|
1140 Readline output stream. If a numeric argument is supplied, the |
|
|
1141 output is formatted in such a way that it can be made part of an |
|
|
1142 INPUTRC file. This command is unbound by default. |
|
|
1143 |
|
|
1144 `dump-macros ()' |
|
|
1145 Print all of the Readline key sequences bound to macros and the |
|
|
1146 strings they output. If a numeric argument is supplied, the |
|
|
1147 output is formatted in such a way that it can be made part of an |
|
|
1148 INPUTRC file. This command is unbound by default. |
|
|
1149 |
|
|
1150 |
|
|
1151 File: readline.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing |
|
|
1152 |
|
|
1153 Readline vi Mode |
|
|
1154 ================ |
|
|
1155 |
|
|
1156 While the Readline library does not have a full set of `vi' editing |
|
|
1157 functions, it does contain enough to allow simple editing of the line. |
|
|
1158 The Readline `vi' mode behaves as specified in the POSIX 1003.2 |
|
|
1159 standard. |
|
|
1160 |
|
|
1161 In order to switch interactively between `emacs' and `vi' editing |
|
|
1162 modes, use the command `M-C-j' (toggle-editing-mode). The Readline |
|
|
1163 default is `emacs' mode. |
|
|
1164 |
|
|
1165 When you enter a line in `vi' mode, you are already placed in |
|
|
1166 `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches |
|
|
1167 you into `command' mode, where you can edit the text of the line with |
|
|
1168 the standard `vi' movement keys, move to previous history lines with |
|
|
1169 `k' and subsequent lines with `j', and so forth. |
|
|
1170 |
|
|
1171 This document describes the GNU Readline Library, a utility for |
|
|
1172 aiding in the consitency of user interface across discrete programs |
|
|
1173 that need to provide a command line interface. |
|
|
1174 |
|
|
1175 Copyright (C) 1988-2001 Free Software Foundation, Inc. |
|
|
1176 |
|
|
1177 Permission is granted to make and distribute verbatim copies of this |
|
|
1178 manual provided the copyright notice and this permission notice pare |
|
|
1179 preserved on all copies. |
|
|
1180 |
|
|
1181 Permission is granted to copy and distribute modified versions of |
|
|
1182 this manual under the conditions for verbatim copying, provided that |
|
|
1183 the entire resulting derived work is distributed under the terms of a |
|
|
1184 permission notice identical to this one. |
|
|
1185 |
|
|
1186 Permission is granted to copy and distribute translations of this |
|
|
1187 manual into another language, under the above conditions for modified |
|
|
1188 versions, except that this permission notice may be stated in a |
|
|
1189 translation approved by the Foundation. |
|
|
1190 |
|
|
1191 |
|
|
1192 File: readline.info, Node: Programming with GNU Readline, Next: Concept Index, Prev: Command Line Editing, Up: Top |
|
|
1193 |
|
|
1194 Programming with GNU Readline |
|
|
1195 ***************************** |
|
|
1196 |
|
|
1197 This chapter describes the interface between the GNU Readline |
|
|
1198 Library and other programs. If you are a programmer, and you wish to |
|
|
1199 include the features found in GNU Readline such as completion, line |
|
|
1200 editing, and interactive history manipulation in your own programs, |
|
|
1201 this section is for you. |
|
|
1202 |
|
|
1203 * Menu: |
|
|
1204 |
|
|
1205 * Basic Behavior:: Using the default behavior of Readline. |
|
|
1206 * Custom Functions:: Adding your own functions to Readline. |
|
|
1207 * Readline Variables:: Variables accessible to custom |
|
|
1208 functions. |
|
|
1209 * Readline Convenience Functions:: Functions which Readline supplies to |
|
|
1210 aid in writing your own custom |
|
|
1211 functions. |
|
|
1212 * Readline Signal Handling:: How Readline behaves when it receives signals. |
|
|
1213 * Custom Completers:: Supplanting or supplementing Readline's |
|
|
1214 completion functions. |
|
|
1215 |
|
|
1216 |
|
|
1217 File: readline.info, Node: Basic Behavior, Next: Custom Functions, Up: Programming with GNU Readline |
|
|
1218 |
|
|
1219 Basic Behavior |
|
|
1220 ============== |
|
|
1221 |
|
|
1222 Many programs provide a command line interface, such as `mail', |
|
|
1223 `ftp', and `sh'. For such programs, the default behaviour of Readline |
|
|
1224 is sufficient. This section describes how to use Readline in the |
|
|
1225 simplest way possible, perhaps to replace calls in your code to |
|
|
1226 `gets()' or `fgets()'. |
|
|
1227 |
|
|
1228 `char *readline (const char *PROMPT);' |
|
|
1229 |
|
|
1230 The function `readline()' prints a prompt PROMPT and then reads and |
|
|
1231 returns a single line of text from the user. If PROMPT is `NULL' or |
|
|
1232 the empty string, no prompt is displayed. The line `readline' returns |
|
|
1233 is allocated with `malloc()'; the caller should `free()' the line when |
|
|
1234 it has finished with it. The declaration for `readline' in ANSI C is |
|
|
1235 |
|
|
1236 So, one might say |
|
|
1237 `char *line = readline ("Enter a line: ");' |
|
|
1238 |
|
|
1239 in order to read a line of text from the user. The line returned has |
|
|
1240 the final newline removed, so only the text remains. |
|
|
1241 |
|
|
1242 If `readline' encounters an `EOF' while reading the line, and the |
|
|
1243 line is empty at that point, then `(char *)NULL' is returned. |
|
|
1244 Otherwise, the line is ended just as if a newline had been typed. |
|
|
1245 |
|
|
1246 If you want the user to be able to get at the line later, (with |
|
|
1247 <C-p> for example), you must call `add_history()' to save the line away |
|
|
1248 in a "history" list of such lines. |
|
|
1249 |
|
|
1250 `add_history (line)'; |
|
|
1251 |
|
|
1252 For full details on the GNU History Library, see the associated manual. |
|
|
1253 |
|
|
1254 It is preferable to avoid saving empty lines on the history list, |
|
|
1255 since users rarely have a burning need to reuse a blank line. Here is |
|
|
1256 a function which usefully replaces the standard `gets()' library |
|
|
1257 function, and has the advantage of no static buffer to overflow: |
|
|
1258 |
|
|
1259 /* A static variable for holding the line. */ |
|
|
1260 static char *line_read = (char *)NULL; |
|
|
1261 |
|
|
1262 /* Read a string, and return a pointer to it. Returns NULL on EOF. */ |
|
|
1263 char * |
|
|
1264 rl_gets () |
|
|
1265 { |
|
|
1266 /* If the buffer has already been allocated, return the memory |
|
|
1267 to the free pool. */ |
|
|
1268 if (line_read) |
|
|
1269 { |
|
|
1270 free (line_read); |
|
|
1271 line_read = (char *)NULL; |
|
|
1272 } |
|
|
1273 |
|
|
1274 /* Get a line from the user. */ |
|
|
1275 line_read = readline (""); |
|
|
1276 |
|
|
1277 /* If the line has any text in it, save it on the history. */ |
|
|
1278 if (line_read && *line_read) |
|
|
1279 add_history (line_read); |
|
|
1280 |
|
|
1281 return (line_read); |
|
|
1282 } |
|
|
1283 |
|
|
1284 This function gives the user the default behaviour of <TAB> |
|
|
1285 completion: completion on file names. If you do not want Readline to |
|
|
1286 complete on filenames, you can change the binding of the <TAB> key with |
|
|
1287 `rl_bind_key()'. |
|
|
1288 |
|
|
1289 `int rl_bind_key (int KEY, rl_command_func_t *FUNCTION);' |
|
|
1290 |
|
|
1291 `rl_bind_key()' takes two arguments: KEY is the character that you |
|
|
1292 want to bind, and FUNCTION is the address of the function to call when |
|
|
1293 KEY is pressed. Binding <TAB> to `rl_insert()' makes <TAB> insert |
|
|
1294 itself. `rl_bind_key()' returns non-zero if KEY is not a valid ASCII |
|
|
1295 character code (between 0 and 255). |
|
|
1296 |
|
|
1297 Thus, to disable the default <TAB> behavior, the following suffices: |
|
|
1298 `rl_bind_key ('\t', rl_insert);' |
|
|
1299 |
|
|
1300 This code should be executed once at the start of your program; you |
|
|
1301 might write a function called `initialize_readline()' which performs |
|
|
1302 this and other desired initializations, such as installing custom |
|
|
1303 completers (*note Custom Completers::). |
|
|
1304 |
|
|
1305 |
|
|
1306 File: readline.info, Node: Custom Functions, Next: Readline Variables, Prev: Basic Behavior, Up: Programming with GNU Readline |
|
|
1307 |
|
|
1308 Custom Functions |
|
|
1309 ================ |
|
|
1310 |
|
|
1311 Readline provides many functions for manipulating the text of the |
|
|
1312 line, but it isn't possible to anticipate the needs of all programs. |
|
|
1313 This section describes the various functions and variables defined |
|
|
1314 within the Readline library which allow a user program to add |
|
|
1315 customized functionality to Readline. |
|
|
1316 |
|
|
1317 Before declaring any functions that customize Readline's behavior, or |
|
|
1318 using any functionality Readline provides in other code, an application |
|
|
1319 writer should include the file `<readline/readline.h>' in any file that |
|
|
1320 uses Readline's features. Since some of the definitions in |
|
|
1321 `readline.h' use the `stdio' library, the file `<stdio.h>' should be |
|
|
1322 included before `readline.h'. |
|
|
1323 |
|
|
1324 * Menu: |
|
|
1325 |
|
|
1326 * Readline Typedefs:: C declarations to make code readable. |
|
|
1327 * Function Writing:: Variables and calling conventions. |
|
|
1328 |
|
|
1329 |
|
|
1330 File: readline.info, Node: Readline Typedefs, Next: Function Writing, Up: Custom Functions |
|
|
1331 |
|
|
1332 Readline Typedefs |
|
|
1333 ----------------- |
|
|
1334 |
|
|
1335 For readabilty, we declare a number of new object types, all pointers |
|
|
1336 to functions. |
|
|
1337 |
|
|
1338 The reason for declaring these new types is to make it easier to |
|
|
1339 write code describing pointers to C functions with appropriately |
|
|
1340 prototyped arguments and return values. |
|
|
1341 |
|
|
1342 For instance, say we want to declare a variable FUNC as a pointer to |
|
|
1343 a function which takes two `int' arguments and returns an `int' (this |
|
|
1344 is the type of all of the Readline bindable functions). Instead of the |
|
|
1345 classic C declaration |
|
|
1346 |
|
|
1347 `int (*func)();' |
|
|
1348 |
|
|
1349 or the ANSI-C style declaration |
|
|
1350 |
|
|
1351 `int (*func)(int, int);' |
|
|
1352 |
|
|
1353 we may write |
|
|
1354 |
|
|
1355 `rl_command_func_t *func;' |
|
|
1356 |
|
|
1357 The full list of function pointer types available is |
|
|
1358 |
|
|
1359 `typedef int rl_command_func_t (int, int);' |
|
|
1360 |
|
|
1361 `typedef char *rl_compentry_func_t (const char *, int);' |
|
|
1362 |
|
|
1363 `typedef char **rl_completion_func_t (const char *, int, int);' |
|
|
1364 |
|
|
1365 `typedef char *rl_quote_func_t (char *, int, char *);' |
|
|
1366 |
|
|
1367 `typedef char *rl_dequote_func_t (char *, int);' |
|
|
1368 |
|
|
1369 `typedef int rl_compignore_func_t (char **);' |
|
|
1370 |
|
|
1371 `typedef void rl_compdisp_func_t (char **, int, int);' |
|
|
1372 |
|
|
1373 `typedef int rl_hook_func_t (void);' |
|
|
1374 |
|
|
1375 `typedef int rl_getc_func_t (FILE *);' |
|
|
1376 |
|
|
1377 `typedef int rl_linebuf_func_t (char *, int);' |
|
|
1378 |
|
|
1379 `typedef int rl_intfunc_t (int);' |
|
|
1380 |
|
|
1381 `#define rl_ivoidfunc_t rl_hook_func_t' |
|
|
1382 |
|
|
1383 `typedef int rl_icpfunc_t (char *);' |
|
|
1384 |
|
|
1385 `typedef int rl_icppfunc_t (char **);' |
|
|
1386 |
|
|
1387 `typedef void rl_voidfunc_t (void);' |
|
|
1388 |
|
|
1389 `typedef void rl_vintfunc_t (int);' |
|
|
1390 |
|
|
1391 `typedef void rl_vcpfunc_t (char *);' |
|
|
1392 |
|
|
1393 `typedef void rl_vcppfunc_t (char **);' |
|
|
1394 |
|
|
1395 File: readline.info, Node: Function Writing, Prev: Readline Typedefs, Up: Custom Functions |
|
|
1396 |
|
|
1397 Writing a New Function |
|
|
1398 ---------------------- |
|
|
1399 |
|
|
1400 In order to write new functions for Readline, you need to know the |
|
|
1401 calling conventions for keyboard-invoked functions, and the names of the |
|
|
1402 variables that describe the current state of the line read so far. |
|
|
1403 |
|
|
1404 The calling sequence for a command `foo' looks like |
|
|
1405 |
|
|
1406 `foo (int count, int key)' |
|
|
1407 |
|
|
1408 where COUNT is the numeric argument (or 1 if defaulted) and KEY is the |
|
|
1409 key that invoked this function. |
|
|
1410 |
|
|
1411 It is completely up to the function as to what should be done with |
|
|
1412 the numeric argument. Some functions use it as a repeat count, some as |
|
|
1413 a flag, and others to choose alternate behavior (refreshing the current |
|
|
1414 line as opposed to refreshing the screen, for example). Some choose to |
|
|
1415 ignore it. In general, if a function uses the numeric argument as a |
|
|
1416 repeat count, it should be able to do something useful with both |
|
|
1417 negative and positive arguments. At the very least, it should be aware |
|
|
1418 that it can be passed a negative argument. |
|
|
1419 |
|
|
1420 |
|
|
1421 File: readline.info, Node: Readline Variables, Next: Readline Convenience Functions, Prev: Custom Functions, Up: Programming with GNU Readline |
|
|
1422 |
|
|
1423 Readline Variables |
|
|
1424 ================== |
|
|
1425 |
|
|
1426 These variables are available to function writers. |
|
|
1427 |
|
|
1428 - Variable: char * rl_line_buffer |
|
|
1429 This is the line gathered so far. You are welcome to modify the |
|
|
1430 contents of the line, but see *Note Allowing Undoing::. The |
|
|
1431 function `rl_extend_line_buffer' is available to increase the |
|
|
1432 memory allocated to `rl_line_buffer'. |
|
|
1433 |
|
|
1434 - Variable: int rl_point |
|
|
1435 The offset of the current cursor position in `rl_line_buffer' (the |
|
|
1436 _point_). |
|
|
1437 |
|
|
1438 - Variable: int rl_end |
|
|
1439 The number of characters present in `rl_line_buffer'. When |
|
|
1440 `rl_point' is at the end of the line, `rl_point' and `rl_end' are |
|
|
1441 equal. |
|
|
1442 |
|
|
1443 - Variable: int rl_mark |
|
|
1444 The MARK (saved position) in the current line. If set, the mark |
|
|
1445 and point define a _region_. |
|
|
1446 |
|
|
1447 - Variable: int rl_done |
|
|
1448 Setting this to a non-zero value causes Readline to return the |
|
|
1449 current line immediately. |
|
|
1450 |
|
|
1451 - Variable: int rl_num_chars_to_read |
|
|
1452 Setting this to a positive value before calling `readline()' causes |
|
|
1453 Readline to return after accepting that many characters, rather |
|
|
1454 than reading up to a character bound to `accept-line'. |
|
|
1455 |
|
|
1456 - Variable: int rl_pending_input |
|
|
1457 Setting this to a value makes it the next keystroke read. This is |
|
|
1458 a way to stuff a single character into the input stream. |
|
|
1459 |
|
|
1460 - Variable: int rl_dispatching |
|
|
1461 Set to a non-zero value if a function is being called from a key |
|
|
1462 binding; zero otherwise. Application functions can test this to |
|
|
1463 discover whether they were called directly or by Readline's |
|
|
1464 dispatching mechanism. |
|
|
1465 |
|
|
1466 - Variable: int rl_erase_empty_line |
|
|
1467 Setting this to a non-zero value causes Readline to completely |
|
|
1468 erase the current line, including any prompt, any time a newline |
|
|
1469 is typed as the only character on an otherwise-empty line. The |
|
|
1470 cursor is moved to the beginning of the newly-blank line. |
|
|
1471 |
|
|
1472 - Variable: char * rl_prompt |
|
|
1473 The prompt Readline uses. This is set from the argument to |
|
|
1474 `readline()', and should not be assigned to directly. |
|
|
1475 |
|
|
1476 - Variable: int rl_already_prompted |
|
|
1477 If an application wishes to display the prompt itself, rather than |
|
|
1478 have Readline do it the first time `readline()' is called, it |
|
|
1479 should set this variable to a non-zero value after displaying the |
|
|
1480 prompt. The prompt must also be passed as the argument to |
|
|
1481 `readline()' so the redisplay functions can update the display |
|
|
1482 properly. The calling application is responsible for managing the |
|
|
1483 value; Readline never sets it. |
|
|
1484 |
|
|
1485 - Variable: const char * rl_library_version |
|
|
1486 The version number of this revision of the library. |
|
|
1487 |
|
|
1488 - Variable: int rl_gnu_readline_p |
|
|
1489 Always set to 1, denoting that this is GNU readline rather than |
|
|
1490 some emulation. |
|
|
1491 |
|
|
1492 - Variable: const char * rl_terminal_name |
|
|
1493 The terminal type, used for initialization. If not set by the |
|
|
1494 application, Readline sets this to the value of the `TERM' |
|
|
1495 environment variable the first time it is called. |
|
|
1496 |
|
|
1497 - Variable: const char * rl_readline_name |
|
|
1498 This variable is set to a unique name by each application using |
|
|
1499 Readline. The value allows conditional parsing of the inputrc file |
|
|
1500 (*note Conditional Init Constructs::). |
|
|
1501 |
|
|
1502 - Variable: FILE * rl_instream |
|
|
1503 The stdio stream from which Readline reads input. |
|
|
1504 |
|
|
1505 - Variable: FILE * rl_outstream |
|
|
1506 The stdio stream to which Readline performs output. |
|
|
1507 |
|
|
1508 - Variable: rl_command_func_t * rl_last_func |
|
|
1509 The address of the last command function Readline executed. May |
|
|
1510 be used to test whether or not a function is being executed twice |
|
|
1511 in succession, for example. |
|
|
1512 |
|
|
1513 - Variable: rl_hook_func_t * rl_startup_hook |
|
|
1514 If non-zero, this is the address of a function to call just before |
|
|
1515 `readline' prints the first prompt. |
|
|
1516 |
|
|
1517 - Variable: rl_hook_func_t * rl_pre_input_hook |
|
|
1518 If non-zero, this is the address of a function to call after the |
|
|
1519 first prompt has been printed and just before `readline' starts |
|
|
1520 reading input characters. |
|
|
1521 |
|
|
1522 - Variable: rl_hook_func_t * rl_event_hook |
|
|
1523 If non-zero, this is the address of a function to call periodically |
|
|
1524 when readline is waiting for terminal input. |
|
|
1525 |
|
|
1526 - Variable: rl_getc_func_t * rl_getc_function |
|
|
1527 If non-zero, `readline' will call indirectly through this pointer |
|
|
1528 to get a character from the input stream. By default, it is set to |
|
|
1529 `rl_getc', the default `readline' character input function (*note |
|
|
1530 Character Input::). |
|
|
1531 |
|
|
1532 - Variable: rl_voidfunc_t * rl_redisplay_function |
|
|
1533 If non-zero, `readline' will call indirectly through this pointer |
|
|
1534 to update the display with the current contents of the editing |
|
|
1535 buffer. By default, it is set to `rl_redisplay', the default |
|
|
1536 `readline' redisplay function (*note Redisplay::). |
|
|
1537 |
|
|
1538 - Variable: rl_vintfunc_t * rl_prep_term_function |
|
|
1539 If non-zero, `readline' will call indirectly through this pointer |
|
|
1540 to initialize the terminal. The function takes a single argument, |
|
|
1541 an `int' flag that says whether or not to use eight-bit characters. |
|
|
1542 By default, this is set to `rl_prep_terminal' (*note Terminal |
|
|
1543 Management::). |
|
|
1544 |
|
|
1545 - Variable: rl_voidfunc_t * rl_deprep_term_function |
|
|
1546 If non-zero, `readline' will call indirectly through this pointer |
|
|
1547 to reset the terminal. This function should undo the effects of |
|
|
1548 `rl_prep_term_function'. By default, this is set to |
|
|
1549 `rl_deprep_terminal' (*note Terminal Management::). |
|
|
1550 |
|
|
1551 - Variable: Keymap rl_executing_keymap |
|
|
1552 This variable is set to the keymap (*note Keymaps::) in which the |
|
|
1553 currently executing readline function was found. |
|
|
1554 |
|
|
1555 - Variable: Keymap rl_binding_keymap |
|
|
1556 This variable is set to the keymap (*note Keymaps::) in which the |
|
|
1557 last key binding occurred. |
|
|
1558 |
|
|
1559 - Variable: char * rl_executing_macro |
|
|
1560 This variable is set to the text of any currently-executing macro. |
|
|
1561 |
|
|
1562 - Variable: int rl_readline_state |
|
|
1563 A variable with bit values that encapsulate the current Readline |
|
|
1564 state. A bit is set with the `RL_SETSTATE' macro, and unset with |
|
|
1565 the `RL_UNSETSTATE' macro. Use the `RL_ISSTATE' macro to test |
|
|
1566 whether a particular state bit is set. Current state bits include: |
|
|
1567 |
|
|
1568 `RL_STATE_NONE' |
|
|
1569 Readline has not yet been called, nor has it begun to |
|
|
1570 intialize. |
|
|
1571 |
|
|
1572 `RL_STATE_INITIALIZING' |
|
|
1573 Readline is initializing its internal data structures. |
|
|
1574 |
|
|
1575 `RL_STATE_INITIALIZED' |
|
|
1576 Readline has completed its initialization. |
|
|
1577 |
|
|
1578 `RL_STATE_TERMPREPPED' |
|
|
1579 Readline has modified the terminal modes to do its own input |
|
|
1580 and redisplay. |
|
|
1581 |
|
|
1582 `RL_STATE_READCMD' |
|
|
1583 Readline is reading a command from the keyboard. |
|
|
1584 |
|
|
1585 `RL_STATE_METANEXT' |
|
|
1586 Readline is reading more input after reading the meta-prefix |
|
|
1587 character. |
|
|
1588 |
|
|
1589 `RL_STATE_DISPATCHING' |
|
|
1590 Readline is dispatching to a command. |
|
|
1591 |
|
|
1592 `RL_STATE_MOREINPUT' |
|
|
1593 Readline is reading more input while executing an editing |
|
|
1594 command. |
|
|
1595 |
|
|
1596 `RL_STATE_ISEARCH' |
|
|
1597 Readline is performing an incremental history search. |
|
|
1598 |
|
|
1599 `RL_STATE_NSEARCH' |
|
|
1600 Readline is performing a non-incremental history search. |
|
|
1601 |
|
|
1602 `RL_STATE_SEARCH' |
|
|
1603 Readline is searching backward or forward through the history |
|
|
1604 for a string. |
|
|
1605 |
|
|
1606 `RL_STATE_NUMERICARG' |
|
|
1607 Readline is reading a numeric argument. |
|
|
1608 |
|
|
1609 `RL_STATE_MACROINPUT' |
|
|
1610 Readline is currently getting its input from a |
|
|
1611 previously-defined keyboard macro. |
|
|
1612 |
|
|
1613 `RL_STATE_MACRODEF' |
|
|
1614 Readline is currently reading characters defining a keyboard |
|
|
1615 macro. |
|
|
1616 |
|
|
1617 `RL_STATE_OVERWRITE' |
|
|
1618 Readline is in overwrite mode. |
|
|
1619 |
|
|
1620 `RL_STATE_COMPLETING' |
|
|
1621 Readline is performing word completion. |
|
|
1622 |
|
|
1623 `RL_STATE_SIGHANDLER' |
|
|
1624 Readline is currently executing the readline signal handler. |
|
|
1625 |
|
|
1626 `RL_STATE_UNDOING' |
|
|
1627 Readline is performing an undo. |
|
|
1628 |
|
|
1629 `RL_STATE_DONE' |
|
|
1630 Readline has read a key sequence bound to `accept-line' and |
|
|
1631 is about to return the line to the caller. |
|
|
1632 |
|
|
1633 |
|
|
1634 - Variable: int rl_explicit_arg |
|
|
1635 Set to a non-zero value if an explicit numeric argument was |
|
|
1636 specified by the user. Only valid in a bindable command function. |
|
|
1637 |
|
|
1638 - Variable: int rl_numeric_arg |
|
|
1639 Set to the value of any numeric argument explicitly specified by |
|
|
1640 the user before executing the current Readline function. Only |
|
|
1641 valid in a bindable command function. |
|
|
1642 |
|
|
1643 - Variable: int rl_editing_mode |
|
|
1644 Set to a value denoting Readline's current editing mode. A value |
|
|
1645 of EMACS_MODE means Readline is currently in emacs mode; VI_MODE |
|
|
1646 means that vi mode is active. |
|
|
1647 |
|
|
1648 |
|
|
1649 File: readline.info, Node: Readline Convenience Functions, Next: Readline Signal Handling, Prev: Readline Variables, Up: Programming with GNU Readline |
|
|
1650 |
|
|
1651 Readline Convenience Functions |
|
|
1652 ============================== |
|
|
1653 |
|
|
1654 * Menu: |
|
|
1655 |
|
|
1656 * Function Naming:: How to give a function you write a name. |
|
|
1657 * Keymaps:: Making keymaps. |
|
|
1658 * Binding Keys:: Changing Keymaps. |
|
|
1659 * Associating Function Names and Bindings:: Translate function names to |
|
|
1660 key sequences. |
|
|
1661 * Allowing Undoing:: How to make your functions undoable. |
|
|
1662 * Redisplay:: Functions to control line display. |
|
|
1663 * Modifying Text:: Functions to modify `rl_line_buffer'. |
|
|
1664 * Character Input:: Functions to read keyboard input. |
|
|
1665 * Terminal Management:: Functions to manage terminal settings. |
|
|
1666 * Utility Functions:: Generally useful functions and hooks. |
|
|
1667 * Alternate Interface:: Using Readline in a `callback' fashion. |
|
|
1668 |
|
|
1669 |
|
|
1670 File: readline.info, Node: Function Naming, Next: Keymaps, Up: Readline Convenience Functions |
|
|
1671 |
|
|
1672 Naming a Function |
|
|
1673 ----------------- |
|
|
1674 |
|
|
1675 The user can dynamically change the bindings of keys while using |
|
|
1676 Readline. This is done by representing the function with a descriptive |
|
|
1677 name. The user is able to type the descriptive name when referring to |
|
|
1678 the function. Thus, in an init file, one might find |
|
|
1679 |
|
|
1680 Meta-Rubout: backward-kill-word |
|
|
1681 |
|
|
1682 This binds the keystroke <Meta-Rubout> to the function |
|
|
1683 _descriptively_ named `backward-kill-word'. You, as the programmer, |
|
|
1684 should bind the functions you write to descriptive names as well. |
|
|
1685 Readline provides a function for doing that: |
|
|
1686 |
|
|
1687 - Function: int rl_add_defun (const char *name, rl_command_func_t |
|
|
1688 *function, int key) |
|
|
1689 Add NAME to the list of named functions. Make FUNCTION be the |
|
|
1690 function that gets called. If KEY is not -1, then bind it to |
|
|
1691 FUNCTION using `rl_bind_key()'. |
|
|
1692 |
|
|
1693 Using this function alone is sufficient for most applications. It is |
|
|
1694 the recommended way to add a few functions to the default functions that |
|
|
1695 Readline has built in. If you need to do something other than adding a |
|
|
1696 function to Readline, you may need to use the underlying functions |
|
|
1697 described below. |
|
|
1698 |
|
|
1699 |
|
|
1700 File: readline.info, Node: Keymaps, Next: Binding Keys, Prev: Function Naming, Up: Readline Convenience Functions |
|
|
1701 |
|
|
1702 Selecting a Keymap |
|
|
1703 ------------------ |
|
|
1704 |
|
|
1705 Key bindings take place on a "keymap". The keymap is the |
|
|
1706 association between the keys that the user types and the functions that |
|
|
1707 get run. You can make your own keymaps, copy existing keymaps, and tell |
|
|
1708 Readline which keymap to use. |
|
|
1709 |
|
|
1710 - Function: Keymap rl_make_bare_keymap (void) |
|
|
1711 Returns a new, empty keymap. The space for the keymap is |
|
|
1712 allocated with `malloc()'; the caller should free it by calling |
|
|
1713 `rl_discard_keymap()' when done. |
|
|
1714 |
|
|
1715 - Function: Keymap rl_copy_keymap (Keymap map) |
|
|
1716 Return a new keymap which is a copy of MAP. |
|
|
1717 |
|
|
1718 - Function: Keymap rl_make_keymap (void) |
|
|
1719 Return a new keymap with the printing characters bound to |
|
|
1720 rl_insert, the lowercase Meta characters bound to run their |
|
|
1721 equivalents, and the Meta digits bound to produce numeric |
|
|
1722 arguments. |
|
|
1723 |
|
|
1724 - Function: void rl_discard_keymap (Keymap keymap) |
|
|
1725 Free the storage associated with KEYMAP. |
|
|
1726 |
|
|
1727 Readline has several internal keymaps. These functions allow you to |
|
|
1728 change which keymap is active. |
|
|
1729 |
|
|
1730 - Function: Keymap rl_get_keymap (void) |
|
|
1731 Returns the currently active keymap. |
|
|
1732 |
|
|
1733 - Function: void rl_set_keymap (Keymap keymap) |
|
|
1734 Makes KEYMAP the currently active keymap. |
|
|
1735 |
|
|
1736 - Function: Keymap rl_get_keymap_by_name (const char *name) |
|
|
1737 Return the keymap matching NAME. NAME is one which would be |
|
|
1738 supplied in a `set keymap' inputrc line (*note Readline Init |
|
|
1739 File::). |
|
|
1740 |
|
|
1741 - Function: char * rl_get_keymap_name (Keymap keymap) |
|
|
1742 Return the name matching KEYMAP. NAME is one which would be |
|
|
1743 supplied in a `set keymap' inputrc line (*note Readline Init |
|
|
1744 File::). |
|
|
1745 |
|
|
1746 |
|
|
1747 File: readline.info, Node: Binding Keys, Next: Associating Function Names and Bindings, Prev: Keymaps, Up: Readline Convenience Functions |
|
|
1748 |
|
|
1749 Binding Keys |
|
|
1750 ------------ |
|
|
1751 |
|
|
1752 Key sequences are associate with functions through the keymap. |
|
|
1753 Readline has several internal keymaps: `emacs_standard_keymap', |
|
|
1754 `emacs_meta_keymap', `emacs_ctlx_keymap', `vi_movement_keymap', and |
|
|
1755 `vi_insertion_keymap'. `emacs_standard_keymap' is the default, and the |
|
|
1756 examples in this manual assume that. |
|
|
1757 |
|
|
1758 Since `readline()' installs a set of default key bindings the first |
|
|
1759 time it is called, there is always the danger that a custom binding |
|
|
1760 installed before the first call to `readline()' will be overridden. An |
|
|
1761 alternate mechanism is to install custom key bindings in an |
|
|
1762 initialization function assigned to the `rl_startup_hook' variable |
|
|
1763 (*note Readline Variables::). |
|
|
1764 |
|
|
1765 These functions manage key bindings. |
|
|
1766 |
|
|
1767 - Function: int rl_bind_key (int key, rl_command_func_t *function) |
|
|
1768 Binds KEY to FUNCTION in the currently active keymap. Returns |
|
|
1769 non-zero in the case of an invalid KEY. |
|
|
1770 |
|
|
1771 - Function: int rl_bind_key_in_map (int key, rl_command_func_t |
|
|
1772 *function, Keymap map) |
|
|
1773 Bind KEY to FUNCTION in MAP. Returns non-zero in the case of an |
|
|
1774 invalid KEY. |
|
|
1775 |
|
|
1776 - Function: int rl_unbind_key (int key) |
|
|
1777 Bind KEY to the null function in the currently active keymap. |
|
|
1778 Returns non-zero in case of error. |
|
|
1779 |
|
|
1780 - Function: int rl_unbind_key_in_map (int key, Keymap map) |
|
|
1781 Bind KEY to the null function in MAP. Returns non-zero in case of |
|
|
1782 error. |
|
|
1783 |
|
|
1784 - Function: int rl_unbind_function_in_map (rl_command_func_t |
|
|
1785 *function, Keymap map) |
|
|
1786 Unbind all keys that execute FUNCTION in MAP. |
|
|
1787 |
|
|
1788 - Function: int rl_unbind_command_in_map (const char *command, Keymap |
|
|
1789 map) |
|
|
1790 Unbind all keys that are bound to COMMAND in MAP. |
|
|
1791 |
|
|
1792 - Function: int rl_set_key (const char *keyseq, rl_command_func_t |
|
|
1793 *function, Keymap map) |
|
|
1794 Bind the key sequence represented by the string KEYSEQ to the |
|
|
1795 function FUNCTION. This makes new keymaps as necessary. The |
|
|
1796 initial keymap in which to do bindings is MAP. |
|
|
1797 |
|
|
1798 - Function: int rl_generic_bind (int type, const char *keyseq, char |
|
|
1799 *data, Keymap map) |
|
|
1800 Bind the key sequence represented by the string KEYSEQ to the |
|
|
1801 arbitrary pointer DATA. TYPE says what kind of data is pointed to |
|
|
1802 by DATA; this can be a function (`ISFUNC'), a macro (`ISMACR'), or |
|
|
1803 a keymap (`ISKMAP'). This makes new keymaps as necessary. The |
|
|
1804 initial keymap in which to do bindings is MAP. |
|
|
1805 |
|
|
1806 - Function: int rl_parse_and_bind (char *line) |
|
|
1807 Parse LINE as if it had been read from the `inputrc' file and |
|
|
1808 perform any key bindings and variable assignments found (*note |
|
|
1809 Readline Init File::). |
|
|
1810 |
|
|
1811 - Function: int rl_read_init_file (const char *filename) |
|
|
1812 Read keybindings and variable assignments from FILENAME (*note |
|
|
1813 Readline Init File::). |
|
|
1814 |
|
|
1815 |
|
|
1816 File: readline.info, Node: Associating Function Names and Bindings, Next: Allowing Undoing, Prev: Binding Keys, Up: Readline Convenience Functions |
|
|
1817 |
|
|
1818 Associating Function Names and Bindings |
|
|
1819 --------------------------------------- |
|
|
1820 |
|
|
1821 These functions allow you to find out what keys invoke named |
|
|
1822 functions and the functions invoked by a particular key sequence. You |
|
|
1823 may also associate a new function name with an arbitrary function. |
|
|
1824 |
|
|
1825 - Function: rl_command_func_t * rl_named_function (const char *name) |
|
|
1826 Return the function with name NAME. |
|
|
1827 |
|
|
1828 - Function: rl_command_func_t * rl_function_of_keyseq (const char |
|
|
1829 *keyseq, Keymap map, int *type) |
|
|
1830 Return the function invoked by KEYSEQ in keymap MAP. If MAP is |
|
|
1831 `NULL', the current keymap is used. If TYPE is not `NULL', the |
|
|
1832 type of the object is returned in the `int' variable it points to |
|
|
1833 (one of `ISFUNC', `ISKMAP', or `ISMACR'). |
|
|
1834 |
|
|
1835 - Function: char ** rl_invoking_keyseqs (rl_command_func_t *function) |
|
|
1836 Return an array of strings representing the key sequences used to |
|
|
1837 invoke FUNCTION in the current keymap. |
|
|
1838 |
|
|
1839 - Function: char ** rl_invoking_keyseqs_in_map (rl_command_func_t |
|
|
1840 *function, Keymap map) |
|
|
1841 Return an array of strings representing the key sequences used to |
|
|
1842 invoke FUNCTION in the keymap MAP. |
|
|
1843 |
|
|
1844 - Function: void rl_function_dumper (int readable) |
|
|
1845 Print the readline function names and the key sequences currently |
|
|
1846 bound to them to `rl_outstream'. If READABLE is non-zero, the |
|
|
1847 list is formatted in such a way that it can be made part of an |
|
|
1848 `inputrc' file and re-read. |
|
|
1849 |
|
|
1850 - Function: void rl_list_funmap_names (void) |
|
|
1851 Print the names of all bindable Readline functions to |
|
|
1852 `rl_outstream'. |
|
|
1853 |
|
|
1854 - Function: const char ** rl_funmap_names (void) |
|
|
1855 Return a NULL terminated array of known function names. The array |
|
|
1856 is sorted. The array itself is allocated, but not the strings |
|
|
1857 inside. You should `free()' the array when you are done, but not |
|
|
1858 the pointers. |
|
|
1859 |
|
|
1860 - Function: int rl_add_funmap_entry (const char *name, |
|
|
1861 rl_command_func_t *function) |
|
|
1862 Add NAME to the list of bindable Readline command names, and make |
|
|
1863 FUNCTION the function to be called when NAME is invoked. |
|
|
1864 |
|
|
1865 |
|
|
1866 File: readline.info, Node: Allowing Undoing, Next: Redisplay, Prev: Associating Function Names and Bindings, Up: Readline Convenience Functions |
|
|
1867 |
|
|
1868 Allowing Undoing |
|
|
1869 ---------------- |
|
|
1870 |
|
|
1871 Supporting the undo command is a painless thing, and makes your |
|
|
1872 functions much more useful. It is certainly easy to try something if |
|
|
1873 you know you can undo it. |
|
|
1874 |
|
|
1875 If your function simply inserts text once, or deletes text once, and |
|
|
1876 uses `rl_insert_text()' or `rl_delete_text()' to do it, then undoing is |
|
|
1877 already done for you automatically. |
|
|
1878 |
|
|
1879 If you do multiple insertions or multiple deletions, or any |
|
|
1880 combination of these operations, you should group them together into |
|
|
1881 one operation. This is done with `rl_begin_undo_group()' and |
|
|
1882 `rl_end_undo_group()'. |
|
|
1883 |
|
|
1884 The types of events that can be undone are: |
|
|
1885 |
|
|
1886 enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END }; |
|
|
1887 |
|
|
1888 Notice that `UNDO_DELETE' means to insert some text, and |
|
|
1889 `UNDO_INSERT' means to delete some text. That is, the undo code tells |
|
|
1890 what to undo, not how to undo it. `UNDO_BEGIN' and `UNDO_END' are tags |
|
|
1891 added by `rl_begin_undo_group()' and `rl_end_undo_group()'. |
|
|
1892 |
|
|
1893 - Function: int rl_begin_undo_group (void) |
|
|
1894 Begins saving undo information in a group construct. The undo |
|
|
1895 information usually comes from calls to `rl_insert_text()' and |
|
|
1896 `rl_delete_text()', but could be the result of calls to |
|
|
1897 `rl_add_undo()'. |
|
|
1898 |
|
|
1899 - Function: int rl_end_undo_group (void) |
|
|
1900 Closes the current undo group started with `rl_begin_undo_group |
|
|
1901 ()'. There should be one call to `rl_end_undo_group()' for each |
|
|
1902 call to `rl_begin_undo_group()'. |
|
|
1903 |
|
|
1904 - Function: void rl_add_undo (enum undo_code what, int start, int end, |
|
|
1905 char *text) |
|
|
1906 Remember how to undo an event (according to WHAT). The affected |
|
|
1907 text runs from START to END, and encompasses TEXT. |
|
|
1908 |
|
|
1909 - Function: void rl_free_undo_list (void) |
|
|
1910 Free the existing undo list. |
|
|
1911 |
|
|
1912 - Function: int rl_do_undo (void) |
|
|
1913 Undo the first thing on the undo list. Returns `0' if there was |
|
|
1914 nothing to undo, non-zero if something was undone. |
|
|
1915 |
|
|
1916 Finally, if you neither insert nor delete text, but directly modify |
|
|
1917 the existing text (e.g., change its case), call `rl_modifying()' once, |
|
|
1918 just before you modify the text. You must supply the indices of the |
|
|
1919 text range that you are going to modify. |
|
|
1920 |
|
|
1921 - Function: int rl_modifying (int start, int end) |
|
|
1922 Tell Readline to save the text between START and END as a single |
|
|
1923 undo unit. It is assumed that you will subsequently modify that |
|
|
1924 text. |
|
|
1925 |
|
|
1926 |
|
|
1927 File: readline.info, Node: Redisplay, Next: Modifying Text, Prev: Allowing Undoing, Up: Readline Convenience Functions |
|
|
1928 |
|
|
1929 Redisplay |
|
|
1930 --------- |
|
|
1931 |
|
|
1932 - Function: void rl_redisplay (void) |
|
|
1933 Change what's displayed on the screen to reflect the current |
|
|
1934 contents of `rl_line_buffer'. |
|
|
1935 |
|
|
1936 - Function: int rl_forced_update_display (void) |
|
|
1937 Force the line to be updated and redisplayed, whether or not |
|
|
1938 Readline thinks the screen display is correct. |
|
|
1939 |
|
|
1940 - Function: int rl_on_new_line (void) |
|
|
1941 Tell the update functions that we have moved onto a new (empty) |
|
|
1942 line, usually after ouputting a newline. |
|
|
1943 |
|
|
1944 - Function: int rl_on_new_line_with_prompt (void) |
|
|
1945 Tell the update functions that we have moved onto a new line, with |
|
|
1946 RL_PROMPT already displayed. This could be used by applications |
|
|
1947 that want to output the prompt string themselves, but still need |
|
|
1948 Readline to know the prompt string length for redisplay. It |
|
|
1949 should be used after setting RL_ALREADY_PROMPTED. |
|
|
1950 |
|
|
1951 - Function: int rl_reset_line_state (void) |
|
|
1952 Reset the display state to a clean state and redisplay the current |
|
|
1953 line starting on a new line. |
|
|
1954 |
|
|
1955 - Function: int rl_crlf (void) |
|
|
1956 Move the cursor to the start of the next screen line. |
|
|
1957 |
|
|
1958 - Function: int rl_message (const char *, ...) |
|
|
1959 The arguments are a format string as would be supplied to `printf', |
|
|
1960 possibly containing conversion specifications such as `%d', and |
|
|
1961 any additional arguments necessary to satisfy the conversion |
|
|
1962 specifications. The resulting string is displayed in the "echo |
|
|
1963 area". The echo area is also used to display numeric arguments |
|
|
1964 and search strings. |
|
|
1965 |
|
|
1966 - Function: int rl_clear_message (void) |
|
|
1967 Clear the message in the echo area. |
|
|
1968 |
|
|
1969 - Function: void rl_save_prompt (void) |
|
|
1970 Save the local Readline prompt display state in preparation for |
|
|
1971 displaying a new message in the message area with `rl_message()'. |
|
|
1972 |
|
|
1973 - Function: void rl_restore_prompt (void) |
|
|
1974 Restore the local Readline prompt display state saved by the most |
|
|
1975 recent call to `rl_save_prompt'. |
|
|
1976 |
|
|
1977 - Function: int rl_expand_prompt (char *prompt) |
|
|
1978 Expand any special character sequences in PROMPT and set up the |
|
|
1979 local Readline prompt redisplay variables. This function is |
|
|
1980 called by `readline()'. It may also be called to expand the |
|
|
1981 primary prompt if the `rl_on_new_line_with_prompt()' function or |
|
|
1982 `rl_already_prompted' variable is used. It returns the number of |
|
|
1983 visible characters on the last line of the (possibly multi-line) |
|
|
1984 prompt. |
|
|
1985 |
|
|
1986 |
|
|
1987 File: readline.info, Node: Modifying Text, Next: Character Input, Prev: Redisplay, Up: Readline Convenience Functions |
|
|
1988 |
|
|
1989 Modifying Text |
|
|
1990 -------------- |
|
|
1991 |
|
|
1992 - Function: int rl_insert_text (const char *text) |
|
|
1993 Insert TEXT into the line at the current cursor position. |
|
|
1994 |
|
|
1995 - Function: int rl_delete_text (int start, int end) |
|
|
1996 Delete the text between START and END in the current line. |
|
|
1997 |
|
|
1998 - Function: char * rl_copy_text (int start, int end) |
|
|
1999 Return a copy of the text between START and END in the current |
|
|
2000 line. |
|
|
2001 |
|
|
2002 - Function: int rl_kill_text (int start, int end) |
|
|
2003 Copy the text between START and END in the current line to the |
|
|
2004 kill ring, appending or prepending to the last kill if the last |
|
|
2005 command was a kill command. The text is deleted. If START is |
|
|
2006 less than END, the text is appended, otherwise prepended. If the |
|
|
2007 last command was not a kill, a new kill ring slot is used. |
|
|
2008 |
|
|
2009 |
|
|
2010 File: readline.info, Node: Character Input, Next: Terminal Management, Prev: Modifying Text, Up: Readline Convenience Functions |
|
|
2011 |
|
|
2012 Character Input |
|
|
2013 --------------- |
|
|
2014 |
|
|
2015 - Function: int rl_read_key (void) |
|
|
2016 Return the next character available from Readline's current input |
|
|
2017 stream. This handles input inserted into the input stream via |
|
|
2018 RL_PENDING_INPUT (*note Readline Variables::) and |
|
|
2019 `rl_stuff_char()', macros, and characters read from the keyboard. |
|
|
2020 |
|
|
2021 - Function: int rl_getc (FILE *stream) |
|
|
2022 Return the next character available from STREAM, which is assumed |
|
|
2023 to be the keyboard. |
|
|
2024 |
|
|
2025 - Function: int rl_stuff_char (int c) |
|
|
2026 Insert C into the Readline input stream. It will be "read" before |
|
|
2027 Readline attempts to read characters from the terminal with |
|
|
2028 `rl_read_key()'. |
|
|
2029 |
|
|
2030 - Function: int rl_execute_next (int c) |
|
|
2031 Make C be the next command to be executed when `rl_read_key()' is |
|
|
2032 called. This sets RL_PENDING_INPUT. |
|
|
2033 |
|
|
2034 - Function: int rl_clear_pending_input (void) |
|
|
2035 Unet RL_PENDING_INPUT, effectively negating the effect of any |
|
|
2036 previous call to `rl_execute_next()'. This works only if the |
|
|
2037 pending input has not already been read with `rl_read_key()'. |
|
|
2038 |
|
|
2039 |
|
|
2040 File: readline.info, Node: Terminal Management, Next: Utility Functions, Prev: Character Input, Up: Readline Convenience Functions |
|
|
2041 |
|
|
2042 Terminal Management |
|
|
2043 ------------------- |
|
|
2044 |
|
|
2045 - Function: int rl_prep_terminal (int meta_flag) |
|
|
2046 Modify the terminal settings for Readline's use, so `readline()' |
|
|
2047 can read a single character at a time from the keyboard. The |
|
|
2048 META_FLAG argument should be non-zero if Readline should read |
|
|
2049 eight-bit input. |
|
|
2050 |
|
|
2051 - Function: in rl_deprep_terminal (void) |
|
|
2052 Undo the effects of `rl_prep_terminal()', leaving the terminal in |
|
|
2053 the state in which it was before the most recent call to |
|
|
2054 `rl_prep_terminal()'. |
|
|
2055 |
|
|
2056 - Function: void rl_tty_set_default_bindings (Keymap kmap) |
|
|
2057 Read the operating system's terminal editing characters (as would |
|
|
2058 be displayed by `stty' to their readline equivalents. The |
|
|
2059 bindings are performed in KMAP. |
|
|
2060 |
|
|
2061 - Function: int rl_reset_terminal (const char *terminal_name) |
|
|
2062 Reinitialize Readline's idea of the terminal settings using |
|
|
2063 TERMINAL_NAME as the terminal type (e.g., `vt100'). If |
|
|
2064 TERMINAL_NAME is NULL, the value of the `TERM' environment |
|
|
2065 variable is used. |
|
|
2066 |
|
|
2067 |
|
|
2068 File: readline.info, Node: Utility Functions, Next: Alternate Interface, Prev: Terminal Management, Up: Readline Convenience Functions |
|
|
2069 |
|
|
2070 Utility Functions |
|
|
2071 ----------------- |
|
|
2072 |
|
|
2073 - Function: int rl_extend_line_buffer (int len) |
|
|
2074 Ensure that `rl_line_buffer' has enough space to hold LEN |
|
|
2075 characters, possibly reallocating it if necessary. |
|
|
2076 |
|
|
2077 - Function: int rl_initialize (void) |
|
|
2078 Initialize or re-initialize Readline's internal state. It's not |
|
|
2079 strictly necessary to call this; `readline()' calls it before |
|
|
2080 reading any input. |
|
|
2081 |
|
|
2082 - Function: int rl_ding (void) |
|
|
2083 Ring the terminal bell, obeying the setting of `bell-style'. |
|
|
2084 |
|
|
2085 - Function: int rl_alphabetic (int c) |
|
|
2086 Return 1 if C is an alphabetic character. |
|
|
2087 |
|
|
2088 - Function: void rl_display_match_list (char **matches, int len, int |
|
|
2089 max) |
|
|
2090 A convenience function for displaying a list of strings in |
|
|
2091 columnar format on Readline's output stream. `matches' is the list |
|
|
2092 of strings, in argv format, such as a list of completion matches. |
|
|
2093 `len' is the number of strings in `matches', and `max' is the |
|
|
2094 length of the longest string in `matches'. This function uses the |
|
|
2095 setting of `print-completions-horizontally' to select how the |
|
|
2096 matches are displayed (*note Readline Init File Syntax::). |
|
|
2097 |
|
|
2098 The following are implemented as macros, defined in `chardefs.h'. |
|
|
2099 Applications should refrain from using them. |
|
|
2100 |
|
|
2101 - Function: int _rl_uppercase_p (int c) |
|
|
2102 Return 1 if C is an uppercase alphabetic character. |
|
|
2103 |
|
|
2104 - Function: int _rl_lowercase_p (int c) |
|
|
2105 Return 1 if C is a lowercase alphabetic character. |
|
|
2106 |
|
|
2107 - Function: int _rl_digit_p (int c) |
|
|
2108 Return 1 if C is a numeric character. |
|
|
2109 |
|
|
2110 - Function: int _rl_to_upper (int c) |
|
|
2111 If C is a lowercase alphabetic character, return the corresponding |
|
|
2112 uppercase character. |
|
|
2113 |
|
|
2114 - Function: int _rl_to_lower (int c) |
|
|
2115 If C is an uppercase alphabetic character, return the corresponding |
|
|
2116 lowercase character. |
|
|
2117 |
|
|
2118 - Function: int _rl_digit_value (int c) |
|
|
2119 If C is a number, return the value it represents. |
|
|
2120 |
|
|
2121 |
|
|
2122 File: readline.info, Node: Alternate Interface, Prev: Utility Functions, Up: Readline Convenience Functions |
|
|
2123 |
|
|
2124 Alternate Interface |
|
|
2125 ------------------- |
|
|
2126 |
|
|
2127 An alternate interface is available to plain `readline()'. Some |
|
|
2128 applications need to interleave keyboard I/O with file, device, or |
|
|
2129 window system I/O, typically by using a main loop to `select()' on |
|
|
2130 various file descriptors. To accomodate this need, readline can also |
|
|
2131 be invoked as a `callback' function from an event loop. There are |
|
|
2132 functions available to make this easy. |
|
|
2133 |
|
|
2134 - Function: void rl_callback_handler_install (const char *prompt, |
|
|
2135 rl_vcpfunc_t *lhandler) |
|
|
2136 Set up the terminal for readline I/O and display the initial |
|
|
2137 expanded value of PROMPT. Save the value of LHANDLER to use as a |
|
|
2138 function to call when a complete line of input has been entered. |
|
|
2139 The function takes the text of the line as an argument. |
|
|
2140 |
|
|
2141 - Function: void rl_callback_read_char (void) |
|
|
2142 Whenever an application determines that keyboard input is |
|
|
2143 available, it should call `rl_callback_read_char()', which will |
|
|
2144 read the next character from the current input source. If that |
|
|
2145 character completes the line, `rl_callback_read_char' will invoke |
|
|
2146 the LHANDLER function saved by `rl_callback_handler_install' to |
|
|
2147 process the line. `EOF' is indicated by calling LHANDLER with a |
|
|
2148 `NULL' line. |
|
|
2149 |
|
|
2150 - Function: void rl_callback_handler_remove (void) |
|
|
2151 Restore the terminal to its initial state and remove the line |
|
|
2152 handler. This may be called from within a callback as well as |
|
|
2153 independently. |
|
|
2154 |
|
|
2155 An Example |
|
|
2156 ---------- |
|
|
2157 |
|
|
2158 Here is a function which changes lowercase characters to their |
|
|
2159 uppercase equivalents, and uppercase characters to lowercase. If this |
|
|
2160 function was bound to `M-c', then typing `M-c' would change the case of |
|
|
2161 the character under point. Typing `M-1 0 M-c' would change the case of |
|
|
2162 the following 10 characters, leaving the cursor on the last character |
|
|
2163 changed. |
|
|
2164 |
|
|
2165 /* Invert the case of the COUNT following characters. */ |
|
|
2166 int |
|
|
2167 invert_case_line (count, key) |
|
|
2168 int count, key; |
|
|
2169 { |
|
|
2170 register int start, end, i; |
|
|
2171 |
|
|
2172 start = rl_point; |
|
|
2173 |
|
|
2174 if (rl_point >= rl_end) |
|
|
2175 return (0); |
|
|
2176 |
|
|
2177 if (count < 0) |
|
|
2178 { |
|
|
2179 direction = -1; |
|
|
2180 count = -count; |
|
|
2181 } |
|
|
2182 else |
|
|
2183 direction = 1; |
|
|
2184 |
|
|
2185 /* Find the end of the range to modify. */ |
|
|
2186 end = start + (count * direction); |
|
|
2187 |
|
|
2188 /* Force it to be within range. */ |
|
|
2189 if (end > rl_end) |
|
|
2190 end = rl_end; |
|
|
2191 else if (end < 0) |
|
|
2192 end = 0; |
|
|
2193 |
|
|
2194 if (start == end) |
|
|
2195 return (0); |
|
|
2196 |
|
|
2197 if (start > end) |
|
|
2198 { |
|
|
2199 int temp = start; |
|
|
2200 start = end; |
|
|
2201 end = temp; |
|
|
2202 } |
|
|
2203 |
|
|
2204 /* Tell readline that we are modifying the line, so it will save |
|
|
2205 the undo information. */ |
|
|
2206 rl_modifying (start, end); |
|
|
2207 |
|
|
2208 for (i = start; i != end; i++) |
|
|
2209 { |
|
|
2210 if (_rl_uppercase_p (rl_line_buffer[i])) |
|
|
2211 rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]); |
|
|
2212 else if (_rl_lowercase_p (rl_line_buffer[i])) |
|
|
2213 rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]); |
|
|
2214 } |
|
|
2215 /* Move point to on top of the last character changed. */ |
|
|
2216 rl_point = (direction == 1) ? end - 1 : start; |
|
|
2217 return (0); |
|
|
2218 } |
|
|
2219 |
|
|
2220 |
|
|
2221 File: readline.info, Node: Readline Signal Handling, Next: Custom Completers, Prev: Readline Convenience Functions, Up: Programming with GNU Readline |
|
|
2222 |
|
|
2223 Readline Signal Handling |
|
|
2224 ======================== |
|
|
2225 |
|
|
2226 Signals are asynchronous events sent to a process by the Unix kernel, |
|
|
2227 sometimes on behalf of another process. They are intended to indicate |
|
|
2228 exceptional events, like a user pressing the interrupt key on his |
|
|
2229 terminal, or a network connection being broken. There is a class of |
|
|
2230 signals that can be sent to the process currently reading input from |
|
|
2231 the keyboard. Since Readline changes the terminal attributes when it |
|
|
2232 is called, it needs to perform special processing when a signal is |
|
|
2233 received to restore the terminal to a sane state, or provide application |
|
|
2234 writers with functions to do so manually. |
|
|
2235 |
|
|
2236 Readline contains an internal signal handler that is installed for a |
|
|
2237 number of signals (`SIGINT', `SIGQUIT', `SIGTERM', `SIGALRM', |
|
|
2238 `SIGTSTP', `SIGTTIN', and `SIGTTOU'). When one of these signals is |
|
|
2239 received, the signal handler will reset the terminal attributes to |
|
|
2240 those that were in effect before `readline()' was called, reset the |
|
|
2241 signal handling to what it was before `readline()' was called, and |
|
|
2242 resend the signal to the calling application. If and when the calling |
|
|
2243 application's signal handler returns, Readline will reinitialize the |
|
|
2244 terminal and continue to accept input. When a `SIGINT' is received, |
|
|
2245 the Readline signal handler performs some additional work, which will |
|
|
2246 cause any partially-entered line to be aborted (see the description of |
|
|
2247 `rl_free_line_state()' below). |
|
|
2248 |
|
|
2249 There is an additional Readline signal handler, for `SIGWINCH', which |
|
|
2250 the kernel sends to a process whenever the terminal's size changes (for |
|
|
2251 example, if a user resizes an `xterm'). The Readline `SIGWINCH' |
|
|
2252 handler updates Readline's internal screen size information, and then |
|
|
2253 calls any `SIGWINCH' signal handler the calling application has |
|
|
2254 installed. Readline calls the application's `SIGWINCH' signal handler |
|
|
2255 without resetting the terminal to its original state. If the |
|
|
2256 application's signal handler does more than update its idea of the |
|
|
2257 terminal size and return (for example, a `longjmp' back to a main |
|
|
2258 processing loop), it _must_ call `rl_cleanup_after_signal()' (described |
|
|
2259 below), to restore the terminal state. |
|
|
2260 |
|
|
2261 Readline provides two variables that allow application writers to |
|
|
2262 control whether or not it will catch certain signals and act on them |
|
|
2263 when they are received. It is important that applications change the |
|
|
2264 values of these variables only when calling `readline()', not in a |
|
|
2265 signal handler, so Readline's internal signal state is not corrupted. |
|
|
2266 |
|
|
2267 - Variable: int rl_catch_signals |
|
|
2268 If this variable is non-zero, Readline will install signal |
|
|
2269 handlers for `SIGINT', `SIGQUIT', `SIGTERM', `SIGALRM', `SIGTSTP', |
|
|
2270 `SIGTTIN', and `SIGTTOU'. |
|
|
2271 |
|
|
2272 The default value of `rl_catch_signals' is 1. |
|
|
2273 |
|
|
2274 - Variable: int rl_catch_sigwinch |
|
|
2275 If this variable is non-zero, Readline will install a signal |
|
|
2276 handler for `SIGWINCH'. |
|
|
2277 |
|
|
2278 The default value of `rl_catch_sigwinch' is 1. |
|
|
2279 |
|
|
2280 If an application does not wish to have Readline catch any signals, |
|
|
2281 or to handle signals other than those Readline catches (`SIGHUP', for |
|
|
2282 example), Readline provides convenience functions to do the necessary |
|
|
2283 terminal and internal state cleanup upon receipt of a signal. |
|
|
2284 |
|
|
2285 - Function: void rl_cleanup_after_signal (void) |
|
|
2286 This function will reset the state of the terminal to what it was |
|
|
2287 before `readline()' was called, and remove the Readline signal |
|
|
2288 handlers for all signals, depending on the values of |
|
|
2289 `rl_catch_signals' and `rl_catch_sigwinch'. |
|
|
2290 |
|
|
2291 - Function: void rl_free_line_state (void) |
|
|
2292 This will free any partial state associated with the current input |
|
|
2293 line (undo information, any partial history entry, any |
|
|
2294 partially-entered keyboard macro, and any partially-entered |
|
|
2295 numeric argument). This should be called before |
|
|
2296 `rl_cleanup_after_signal()'. The Readline signal handler for |
|
|
2297 `SIGINT' calls this to abort the current input line. |
|
|
2298 |
|
|
2299 - Function: void rl_reset_after_signal (void) |
|
|
2300 This will reinitialize the terminal and reinstall any Readline |
|
|
2301 signal handlers, depending on the values of `rl_catch_signals' and |
|
|
2302 `rl_catch_sigwinch'. |
|
|
2303 |
|
|
2304 If an application does not wish Readline to catch `SIGWINCH', it may |
|
|
2305 call `rl_resize_terminal()' or `rl_set_screen_size()' to force Readline |
|
|
2306 to update its idea of the terminal size when a `SIGWINCH' is received. |
|
|
2307 |
|
|
2308 - Function: void rl_resize_terminal (void) |
|
|
2309 Update Readline's internal screen size by reading values from the |
|
|
2310 kernel. |
|
|
2311 |
|
|
2312 - Function: void rl_set_screen_size (int rows, int cols) |
|
|
2313 Set Readline's idea of the terminal size to ROWS rows and COLS |
|
|
2314 columns. |
|
|
2315 |
|
|
2316 The following functions install and remove Readline's signal |
|
|
2317 handlers. |
|
|
2318 |
|
|
2319 - Function: int rl_set_signals (void) |
|
|
2320 Install Readline's signal handler for `SIGINT', `SIGQUIT', |
|
|
2321 `SIGTERM', `SIGALRM', `SIGTSTP', `SIGTTIN', `SIGTTOU', and |
|
|
2322 `SIGWINCH', depending on the values of `rl_catch_signals' and |
|
|
2323 `rl_catch_sigwinch'. |
|
|
2324 |
|
|
2325 - Function: int rl_clear_signals (void) |
|
|
2326 Remove all of the Readline signal handlers installed by |
|
|
2327 `rl_set_signals()'. |
|
|
2328 |
|
|
2329 |
|
|
2330 File: readline.info, Node: Custom Completers, Prev: Readline Signal Handling, Up: Programming with GNU Readline |
|
|
2331 |
|
|
2332 Custom Completers |
|
|
2333 ================= |
|
|
2334 |
|
|
2335 Typically, a program that reads commands from the user has a way of |
|
|
2336 disambiguating commands and data. If your program is one of these, then |
|
|
2337 it can provide completion for commands, data, or both. The following |
|
|
2338 sections describe how your program and Readline cooperate to provide |
|
|
2339 this service. |
|
|
2340 |
|
|
2341 * Menu: |
|
|
2342 |
|
|
2343 * How Completing Works:: The logic used to do completion. |
|
|
2344 * Completion Functions:: Functions provided by Readline. |
|
|
2345 * Completion Variables:: Variables which control completion. |
|
|
2346 * A Short Completion Example:: An example of writing completer subroutines. |
|
|
2347 |
|
|
2348 |
|
|
2349 File: readline.info, Node: How Completing Works, Next: Completion Functions, Up: Custom Completers |
|
|
2350 |
|
|
2351 How Completing Works |
|
|
2352 -------------------- |
|
|
2353 |
|
|
2354 In order to complete some text, the full list of possible completions |
|
|
2355 must be available. That is, it is not possible to accurately expand a |
|
|
2356 partial word without knowing all of the possible words which make sense |
|
|
2357 in that context. The Readline library provides the user interface to |
|
|
2358 completion, and two of the most common completion functions: filename |
|
|
2359 and username. For completing other types of text, you must write your |
|
|
2360 own completion function. This section describes exactly what such |
|
|
2361 functions must do, and provides an example. |
|
|
2362 |
|
|
2363 There are three major functions used to perform completion: |
|
|
2364 |
|
|
2365 1. The user-interface function `rl_complete()'. This function is |
|
|
2366 called with the same arguments as other bindable Readline |
|
|
2367 functions: COUNT and INVOKING_KEY. It isolates the word to be |
|
|
2368 completed and calls `rl_completion_matches()' to generate a list |
|
|
2369 of possible completions. It then either lists the possible |
|
|
2370 completions, inserts the possible completions, or actually |
|
|
2371 performs the completion, depending on which behavior is desired. |
|
|
2372 |
|
|
2373 2. The internal function `rl_completion_matches()' uses an |
|
|
2374 application-supplied "generator" function to generate the list of |
|
|
2375 possible matches, and then returns the array of these matches. |
|
|
2376 The caller should place the address of its generator function in |
|
|
2377 `rl_completion_entry_function'. |
|
|
2378 |
|
|
2379 3. The generator function is called repeatedly from |
|
|
2380 `rl_completion_matches()', returning a string each time. The |
|
|
2381 arguments to the generator function are TEXT and STATE. TEXT is |
|
|
2382 the partial word to be completed. STATE is zero the first time |
|
|
2383 the function is called, allowing the generator to perform any |
|
|
2384 necessary initialization, and a positive non-zero integer for each |
|
|
2385 subsequent call. The generator function returns `(char *)NULL' to |
|
|
2386 inform `rl_completion_matches()' that there are no more |
|
|
2387 possibilities left. Usually the generator function computes the |
|
|
2388 list of possible completions when STATE is zero, and returns them |
|
|
2389 one at a time on subsequent calls. Each string the generator |
|
|
2390 function returns as a match must be allocated with `malloc()'; |
|
|
2391 Readline frees the strings when it has finished with them. |
|
|
2392 |
|
|
2393 |
|
|
2394 - Function: int rl_complete (int ignore, int invoking_key) |
|
|
2395 Complete the word at or before point. You have supplied the |
|
|
2396 function that does the initial simple matching selection algorithm |
|
|
2397 (see `rl_completion_matches()'). The default is to do filename |
|
|
2398 completion. |
|
|
2399 |
|
|
2400 - Variable: rl_compentry_func_t * rl_completion_entry_function |
|
|
2401 This is a pointer to the generator function for |
|
|
2402 `rl_completion_matches()'. If the value of |
|
|
2403 `rl_completion_entry_function' is `NULL' then the default filename |
|
|
2404 generator function, `rl_filename_completion_function()', is used. |
|
|
2405 |
|
|
2406 |
|
|
2407 File: readline.info, Node: Completion Functions, Next: Completion Variables, Prev: How Completing Works, Up: Custom Completers |
|
|
2408 |
|
|
2409 Completion Functions |
|
|
2410 -------------------- |
|
|
2411 |
|
|
2412 Here is the complete list of callable completion functions present in |
|
|
2413 Readline. |
|
|
2414 |
|
|
2415 - Function: int rl_complete_internal (int what_to_do) |
|
|
2416 Complete the word at or before point. WHAT_TO_DO says what to do |
|
|
2417 with the completion. A value of `?' means list the possible |
|
|
2418 completions. `TAB' means do standard completion. `*' means |
|
|
2419 insert all of the possible completions. `!' means to display all |
|
|
2420 of the possible completions, if there is more than one, as well as |
|
|
2421 performing partial completion. |
|
|
2422 |
|
|
2423 - Function: int rl_complete (int ignore, int invoking_key) |
|
|
2424 Complete the word at or before point. You have supplied the |
|
|
2425 function that does the initial simple matching selection algorithm |
|
|
2426 (see `rl_completion_matches()' and `rl_completion_entry_function'). |
|
|
2427 The default is to do filename completion. This calls |
|
|
2428 `rl_complete_internal()' with an argument depending on |
|
|
2429 INVOKING_KEY. |
|
|
2430 |
|
|
2431 - Function: int rl_possible_completions (int count, int invoking_key) |
|
|
2432 List the possible completions. See description of `rl_complete |
|
|
2433 ()'. This calls `rl_complete_internal()' with an argument of `?'. |
|
|
2434 |
|
|
2435 - Function: int rl_insert_completions (int count, int invoking_key) |
|
|
2436 Insert the list of possible completions into the line, deleting the |
|
|
2437 partially-completed word. See description of `rl_complete()'. |
|
|
2438 This calls `rl_complete_internal()' with an argument of `*'. |
|
|
2439 |
|
|
2440 - Function: char ** rl_completion_matches (const char *text, |
|
|
2441 rl_compentry_func_t *entry_func) |
|
|
2442 Returns an array of `(char *)' which is a list of completions for |
|
|
2443 TEXT. If there are no completions, returns `NULL'. The first |
|
|
2444 entry in the returned array is the substitution for TEXT. The |
|
|
2445 remaining entries are the possible completions. The array is |
|
|
2446 terminated with a `NULL' pointer. |
|
|
2447 |
|
|
2448 ENTRY_FUNC is a function of two args, and returns a `(char *)'. |
|
|
2449 The first argument is TEXT. The second is a state argument; it is |
|
|
2450 zero on the first call, and non-zero on subsequent calls. |
|
|
2451 ENTRY_FUNC returns a `NULL' pointer to the caller when there are |
|
|
2452 no more matches. |
|
|
2453 |
|
|
2454 - Function: char * rl_filename_completion_function (const char *text, |
|
|
2455 int state) |
|
|
2456 A generator function for filename completion in the general case. |
|
|
2457 Note that completion in Bash is a little different because of all |
|
|
2458 the pathnames that must be followed when looking up completions |
|
|
2459 for a command. The Bash source is a useful reference for writing |
|
|
2460 custom completion functions. |
|
|
2461 |
|
|
2462 - Function: char * rl_username_completion_function (const char *text, |
|
|
2463 int state) |
|
|
2464 A completion generator for usernames. TEXT contains a partial |
|
|
2465 username preceded by a random character (usually `~'). As with all |
|
|
2466 completion generators, STATE is zero on the first call and non-zero |
|
|
2467 for subsequent calls. |
|
|
2468 |
|
|
2469 |
|
|
2470 File: readline.info, Node: Completion Variables, Next: A Short Completion Example, Prev: Completion Functions, Up: Custom Completers |
|
|
2471 |
|
|
2472 Completion Variables |
|
|
2473 -------------------- |
|
|
2474 |
|
|
2475 - Variable: rl_compentry_func_t * rl_completion_entry_function |
|
|
2476 A pointer to the generator function for `rl_completion_matches()'. |
|
|
2477 `NULL' means to use `rl_filename_completion_function()', the |
|
|
2478 default filename completer. |
|
|
2479 |
|
|
2480 - Variable: rl_completion_func_t * rl_attempted_completion_function |
|
|
2481 A pointer to an alternative function to create matches. The |
|
|
2482 function is called with TEXT, START, and END. START and END are |
|
|
2483 indices in `rl_line_buffer' defining the boundaries of TEXT, which |
|
|
2484 is a character string. If this function exists and returns |
|
|
2485 `NULL', or if this variable is set to `NULL', then `rl_complete()' |
|
|
2486 will call the value of `rl_completion_entry_function' to generate |
|
|
2487 matches, otherwise the array of strings returned will be used. If |
|
|
2488 this function sets the `rl_attempted_completion_over' variable to |
|
|
2489 a non-zero value, Readline will not perform its default completion |
|
|
2490 if this function returns no matches. |
|
|
2491 |
|
|
2492 - Variable: rl_quote_func_t * rl_filename_quoting_function |
|
|
2493 A pointer to a function that will quote a filename in an |
|
|
2494 application-specific fashion. This is called if filename |
|
|
2495 completion is being attempted and one of the characters in |
|
|
2496 `rl_filename_quote_characters' appears in a completed filename. |
|
|
2497 The function is called with TEXT, MATCH_TYPE, and QUOTE_POINTER. |
|
|
2498 The TEXT is the filename to be quoted. The MATCH_TYPE is either |
|
|
2499 `SINGLE_MATCH', if there is only one completion match, or |
|
|
2500 `MULT_MATCH'. Some functions use this to decide whether or not to |
|
|
2501 insert a closing quote character. The QUOTE_POINTER is a pointer |
|
|
2502 to any opening quote character the user typed. Some functions |
|
|
2503 choose to reset this character. |
|
|
2504 |
|
|
2505 - Variable: rl_dequote_func_t * rl_filename_dequoting_function |
|
|
2506 A pointer to a function that will remove application-specific |
|
|
2507 quoting characters from a filename before completion is attempted, |
|
|
2508 so those characters do not interfere with matching the text |
|
|
2509 against names in the filesystem. It is called with TEXT, the text |
|
|
2510 of the word to be dequoted, and QUOTE_CHAR, which is the quoting |
|
|
2511 character that delimits the filename (usually `'' or `"'). If |
|
|
2512 QUOTE_CHAR is zero, the filename was not in an embedded string. |
|
|
2513 |
|
|
2514 - Variable: rl_linebuf_func_t * rl_char_is_quoted_p |
|
|
2515 A pointer to a function to call that determines whether or not a |
|
|
2516 specific character in the line buffer is quoted, according to |
|
|
2517 whatever quoting mechanism the program calling readline uses. The |
|
|
2518 function is called with two arguments: TEXT, the text of the line, |
|
|
2519 and INDEX, the index of the character in the line. It is used to |
|
|
2520 decide whether a character found in |
|
|
2521 `rl_completer_word_break_characters' should be used to break words |
|
|
2522 for the completer. |
|
|
2523 |
|
|
2524 - Variable: int rl_completion_query_items |
|
|
2525 Up to this many items will be displayed in response to a |
|
|
2526 possible-completions call. After that, we ask the user if she is |
|
|
2527 sure she wants to see them all. The default value is 100. |
|
|
2528 |
|
|
2529 - Variable: const char * rl_basic_word_break_characters |
|
|
2530 The basic list of characters that signal a break between words for |
|
|
2531 the completer routine. The default value of this variable is the |
|
|
2532 characters which break words for completion in Bash, i.e., `" |
|
|
2533 \t\n\"\\'`@$><=;|&{("'. |
|
|
2534 |
|
|
2535 - Variable: const char * rl_basic_quote_characters |
|
|
2536 List of quote characters which can cause a word break. |
|
|
2537 |
|
|
2538 - Variable: const char * rl_completer_word_break_characters |
|
|
2539 The list of characters that signal a break between words for |
|
|
2540 `rl_complete_internal()'. The default list is the value of |
|
|
2541 `rl_basic_word_break_characters'. |
|
|
2542 |
|
|
2543 - Variable: const char * rl_completer_quote_characters |
|
|
2544 List of characters which can be used to quote a substring of the |
|
|
2545 line. Completion occurs on the entire substring, and within the |
|
|
2546 substring `rl_completer_word_break_characters' are treated as any |
|
|
2547 other character, unless they also appear within this list. |
|
|
2548 |
|
|
2549 - Variable: const char * rl_filename_quote_characters |
|
|
2550 A list of characters that cause a filename to be quoted by the |
|
|
2551 completer when they appear in a completed filename. The default |
|
|
2552 is the null string. |
|
|
2553 |
|
|
2554 - Variable: const char * rl_special_prefixes |
|
|
2555 The list of characters that are word break characters, but should |
|
|
2556 be left in TEXT when it is passed to the completion function. |
|
|
2557 Programs can use this to help determine what kind of completing to |
|
|
2558 do. For instance, Bash sets this variable to "$@" so that it can |
|
|
2559 complete shell variables and hostnames. |
|
|
2560 |
|
|
2561 - Variable: int rl_completion_append_character |
|
|
2562 When a single completion alternative matches at the end of the |
|
|
2563 command line, this character is appended to the inserted |
|
|
2564 completion text. The default is a space character (` '). Setting |
|
|
2565 this to the null character (`\0') prevents anything being appended |
|
|
2566 automatically. This can be changed in custom completion functions |
|
|
2567 to provide the "most sensible word separator character" according |
|
|
2568 to an application-specific command line syntax specification. |
|
|
2569 |
|
|
2570 - Variable: int rl_ignore_completion_duplicates |
|
|
2571 If non-zero, then disallow duplicates in the matches. Default is |
|
|
2572 1. |
|
|
2573 |
|
|
2574 - Variable: int rl_filename_completion_desired |
|
|
2575 Non-zero means that the results of the matches are to be treated as |
|
|
2576 filenames. This is _always_ zero on entry, and can only be changed |
|
|
2577 within a completion entry generator function. If it is set to a |
|
|
2578 non-zero value, directory names have a slash appended and Readline |
|
|
2579 attempts to quote completed filenames if they contain any |
|
|
2580 characters in `rl_filename_quote_characters' and |
|
|
2581 `rl_filename_quoting_desired' is set to a non-zero value. |
|
|
2582 |
|
|
2583 - Variable: int rl_filename_quoting_desired |
|
|
2584 Non-zero means that the results of the matches are to be quoted |
|
|
2585 using double quotes (or an application-specific quoting mechanism) |
|
|
2586 if the completed filename contains any characters in |
|
|
2587 `rl_filename_quote_chars'. This is _always_ non-zero on entry, |
|
|
2588 and can only be changed within a completion entry generator |
|
|
2589 function. The quoting is effected via a call to the function |
|
|
2590 pointed to by `rl_filename_quoting_function'. |
|
|
2591 |
|
|
2592 - Variable: int rl_attempted_completion_over |
|
|
2593 If an application-specific completion function assigned to |
|
|
2594 `rl_attempted_completion_function' sets this variable to a non-zero |
|
|
2595 value, Readline will not perform its default filename completion |
|
|
2596 if the application's completion function returns no matches. It |
|
|
2597 should be set only by an application's completion function. |
|
|
2598 |
|
|
2599 - Variable: int rl_completion_type |
|
|
2600 Set to a character describing the type of completion Readline is |
|
|
2601 currently attempting; see the description of |
|
|
2602 `rl_complete_internal()' (*note Completion Functions::) for the |
|
|
2603 list of characters. |
|
|
2604 |
|
|
2605 - Variable: int rl_inhibit_completion |
|
|
2606 If this variable is non-zero, completion is inhibited. The |
|
|
2607 completion character will be inserted as any other bound to |
|
|
2608 `self-insert'. |
|
|
2609 |
|
|
2610 - Variable: rl_compignore_func_t * rl_ignore_some_completions_function |
|
|
2611 This function, if defined, is called by the completer when real |
|
|
2612 filename completion is done, after all the matching names have |
|
|
2613 been generated. It is passed a `NULL' terminated array of matches. |
|
|
2614 The first element (`matches[0]') is the maximal substring common |
|
|
2615 to all matches. This function can re-arrange the list of matches |
|
|
2616 as required, but each element deleted from the array must be freed. |
|
|
2617 |
|
|
2618 - Variable: rl_icppfunc_t * rl_directory_completion_hook |
|
|
2619 This function, if defined, is allowed to modify the directory |
|
|
2620 portion of filenames Readline completes. It is called with the |
|
|
2621 address of a string (the current directory name) as an argument, |
|
|
2622 and may modify that string. If the string is replaced with a new |
|
|
2623 string, the old value should be freed. Any modified directory |
|
|
2624 name should have a trailing slash. The modified value will be |
|
|
2625 displayed as part of the completion, replacing the directory |
|
|
2626 portion of the pathname the user typed. It returns an integer |
|
|
2627 that should be non-zero if the function modifies its directory |
|
|
2628 argument. It could be used to expand symbolic links or shell |
|
|
2629 variables in pathnames. |
|
|
2630 |
|
|
2631 - Variable: rl_compdisp_func_t * rl_completion_display_matches_hook |
|
|
2632 If non-zero, then this is the address of a function to call when |
|
|
2633 completing a word would normally display the list of possible |
|
|
2634 matches. This function is called in lieu of Readline displaying |
|
|
2635 the list. It takes three arguments: (`char **'MATCHES, `int' |
|
|
2636 NUM_MATCHES, `int' MAX_LENGTH) where MATCHES is the array of |
|
|
2637 matching strings, NUM_MATCHES is the number of strings in that |
|
|
2638 array, and MAX_LENGTH is the length of the longest string in that |
|
|
2639 array. Readline provides a convenience function, |
|
|
2640 `rl_display_match_list', that takes care of doing the display to |
|
|
2641 Readline's output stream. That function may be called from this |
|
|
2642 hook. |
|
|
2643 |
|
|
2644 |
|
|
2645 File: readline.info, Node: A Short Completion Example, Prev: Completion Variables, Up: Custom Completers |
|
|
2646 |
|
|
2647 A Short Completion Example |
|
|
2648 -------------------------- |
|
|
2649 |
|
|
2650 Here is a small application demonstrating the use of the GNU Readline |
|
|
2651 library. It is called `fileman', and the source code resides in |
|
|
2652 `examples/fileman.c'. This sample application provides completion of |
|
|
2653 command names, line editing features, and access to the history list. |
|
|
2654 |
|
|
2655 /* fileman.c -- A tiny application which demonstrates how to use the |
|
|
2656 GNU Readline library. This application interactively allows users |
|
|
2657 to manipulate files and their modes. */ |
|
|
2658 |
|
|
2659 #include <stdio.h> |
|
|
2660 #include <sys/types.h> |
|
|
2661 #include <sys/file.h> |
|
|
2662 #include <sys/stat.h> |
|
|
2663 #include <sys/errno.h> |
|
|
2664 |
|
|
2665 #include <readline/readline.h> |
|
|
2666 #include <readline/history.h> |
|
|
2667 |
|
|
2668 extern char *xmalloc (); |
|
|
2669 |
|
|
2670 /* The names of functions that actually do the manipulation. */ |
|
|
2671 int com_list __P((char *)); |
|
|
2672 int com_view __P((char *)); |
|
|
2673 int com_rename __P((char *)); |
|
|
2674 int com_stat __P((char *)); |
|
|
2675 int com_pwd __P((char *)); |
|
|
2676 int com_delete __P((char *)); |
|
|
2677 int com_help __P((char *)); |
|
|
2678 int com_cd __P((char *)); |
|
|
2679 int com_quit __P((char *)); |
|
|
2680 |
|
|
2681 /* A structure which contains information on the commands this program |
|
|
2682 can understand. */ |
|
|
2683 |
|
|
2684 typedef struct { |
|
|
2685 char *name; /* User printable name of the function. */ |
|
|
2686 rl_icpfunc_t *func; /* Function to call to do the job. */ |
|
|
2687 char *doc; /* Documentation for this function. */ |
|
|
2688 } COMMAND; |
|
|
2689 |
|
|
2690 COMMAND commands[] = { |
|
|
2691 { "cd", com_cd, "Change to directory DIR" }, |
|
|
2692 { "delete", com_delete, "Delete FILE" }, |
|
|
2693 { "help", com_help, "Display this text" }, |
|
|
2694 { "?", com_help, "Synonym for `help'" }, |
|
|
2695 { "list", com_list, "List files in DIR" }, |
|
|
2696 { "ls", com_list, "Synonym for `list'" }, |
|
|
2697 { "pwd", com_pwd, "Print the current working directory" }, |
|
|
2698 { "quit", com_quit, "Quit using Fileman" }, |
|
|
2699 { "rename", com_rename, "Rename FILE to NEWNAME" }, |
|
|
2700 { "stat", com_stat, "Print out statistics on FILE" }, |
|
|
2701 { "view", com_view, "View the contents of FILE" }, |
|
|
2702 { (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL } |
|
|
2703 }; |
|
|
2704 |
|
|
2705 /* Forward declarations. */ |
|
|
2706 char *stripwhite (); |
|
|
2707 COMMAND *find_command (); |
|
|
2708 |
|
|
2709 /* The name of this program, as taken from argv[0]. */ |
|
|
2710 char *progname; |
|
|
2711 |
|
|
2712 /* When non-zero, this means the user is done using this program. */ |
|
|
2713 int done; |
|
|
2714 |
|
|
2715 char * |
|
|
2716 dupstr (s) |
|
|
2717 int s; |
|
|
2718 { |
|
|
2719 char *r; |
|
|
2720 |
|
|
2721 r = xmalloc (strlen (s) + 1); |
|
|
2722 strcpy (r, s); |
|
|
2723 return (r); |
|
|
2724 } |
|
|
2725 |
|
|
2726 main (argc, argv) |
|
|
2727 int argc; |
|
|
2728 char **argv; |
|
|
2729 { |
|
|
2730 char *line, *s; |
|
|
2731 |
|
|
2732 progname = argv[0]; |
|
|
2733 |
|
|
2734 initialize_readline (); /* Bind our completer. */ |
|
|
2735 |
|
|
2736 /* Loop reading and executing lines until the user quits. */ |
|
|
2737 for ( ; done == 0; ) |
|
|
2738 { |
|
|
2739 line = readline ("FileMan: "); |
|
|
2740 |
|
|
2741 if (!line) |
|
|
2742 break; |
|
|
2743 |
|
|
2744 /* Remove leading and trailing whitespace from the line. |
|
|
2745 Then, if there is anything left, add it to the history list |
|
|
2746 and execute it. */ |
|
|
2747 s = stripwhite (line); |
|
|
2748 |
|
|
2749 if (*s) |
|
|
2750 { |
|
|
2751 add_history (s); |
|
|
2752 execute_line (s); |
|
|
2753 } |
|
|
2754 |
|
|
2755 free (line); |
|
|
2756 } |
|
|
2757 exit (0); |
|
|
2758 } |
|
|
2759 |
|
|
2760 /* Execute a command line. */ |
|
|
2761 int |
|
|
2762 execute_line (line) |
|
|
2763 char *line; |
|
|
2764 { |
|
|
2765 register int i; |
|
|
2766 COMMAND *command; |
|
|
2767 char *word; |
|
|
2768 |
|
|
2769 /* Isolate the command word. */ |
|
|
2770 i = 0; |
|
|
2771 while (line[i] && whitespace (line[i])) |
|
|
2772 i++; |
|
|
2773 word = line + i; |
|
|
2774 |
|
|
2775 while (line[i] && !whitespace (line[i])) |
|
|
2776 i++; |
|
|
2777 |
|
|
2778 if (line[i]) |
|
|
2779 line[i++] = '\0'; |
|
|
2780 |
|
|
2781 command = find_command (word); |
|
|
2782 |
|
|
2783 if (!command) |
|
|
2784 { |
|
|
2785 fprintf (stderr, "%s: No such command for FileMan.\n", word); |
|
|
2786 return (-1); |
|
|
2787 } |
|
|
2788 |
|
|
2789 /* Get argument to command, if any. */ |
|
|
2790 while (whitespace (line[i])) |
|
|
2791 i++; |
|
|
2792 |
|
|
2793 word = line + i; |
|
|
2794 |
|
|
2795 /* Call the function. */ |
|
|
2796 return ((*(command->func)) (word)); |
|
|
2797 } |
|
|
2798 |
|
|
2799 /* Look up NAME as the name of a command, and return a pointer to that |
|
|
2800 command. Return a NULL pointer if NAME isn't a command name. */ |
|
|
2801 COMMAND * |
|
|
2802 find_command (name) |
|
|
2803 char *name; |
|
|
2804 { |
|
|
2805 register int i; |
|
|
2806 |
|
|
2807 for (i = 0; commands[i].name; i++) |
|
|
2808 if (strcmp (name, commands[i].name) == 0) |
|
|
2809 return (&commands[i]); |
|
|
2810 |
|
|
2811 return ((COMMAND *)NULL); |
|
|
2812 } |
|
|
2813 |
|
|
2814 /* Strip whitespace from the start and end of STRING. Return a pointer |
|
|
2815 into STRING. */ |
|
|
2816 char * |
|
|
2817 stripwhite (string) |
|
|
2818 char *string; |
|
|
2819 { |
|
|
2820 register char *s, *t; |
|
|
2821 |
|
|
2822 for (s = string; whitespace (*s); s++) |
|
|
2823 ; |
|
|
2824 |
|
|
2825 if (*s == 0) |
|
|
2826 return (s); |
|
|
2827 |
|
|
2828 t = s + strlen (s) - 1; |
|
|
2829 while (t > s && whitespace (*t)) |
|
|
2830 t--; |
|
|
2831 *++t = '\0'; |
|
|
2832 |
|
|
2833 return s; |
|
|
2834 } |
|
|
2835 |
|
|
2836 /* **************************************************************** */ |
|
|
2837 /* */ |
|
|
2838 /* Interface to Readline Completion */ |
|
|
2839 /* */ |
|
|
2840 /* **************************************************************** */ |
|
|
2841 |
|
|
2842 char *command_generator __P((const char *, int)); |
|
|
2843 char **fileman_completion __P((const char *, int, int)); |
|
|
2844 |
|
|
2845 /* Tell the GNU Readline library how to complete. We want to try to |
|
|
2846 complete on command names if this is the first word in the line, or |
|
|
2847 on filenames if not. */ |
|
|
2848 initialize_readline () |
|
|
2849 { |
|
|
2850 /* Allow conditional parsing of the ~/.inputrc file. */ |
|
|
2851 rl_readline_name = "FileMan"; |
|
|
2852 |
|
|
2853 /* Tell the completer that we want a crack first. */ |
|
|
2854 rl_attempted_completion_function = fileman_completion; |
|
|
2855 } |
|
|
2856 |
|
|
2857 /* Attempt to complete on the contents of TEXT. START and END |
|
|
2858 bound the region of rl_line_buffer that contains the word to |
|
|
2859 complete. TEXT is the word to complete. We can use the entire |
|
|
2860 contents of rl_line_buffer in case we want to do some simple |
|
|
2861 parsing. Returnthe array of matches, or NULL if there aren't any. */ |
|
|
2862 char ** |
|
|
2863 fileman_completion (text, start, end) |
|
|
2864 const char *text; |
|
|
2865 int start, end; |
|
|
2866 { |
|
|
2867 char **matches; |
|
|
2868 |
|
|
2869 matches = (char **)NULL; |
|
|
2870 |
|
|
2871 /* If this word is at the start of the line, then it is a command |
|
|
2872 to complete. Otherwise it is the name of a file in the current |
|
|
2873 directory. */ |
|
|
2874 if (start == 0) |
|
|
2875 matches = rl_completion_matches (text, command_generator); |
|
|
2876 |
|
|
2877 return (matches); |
|
|
2878 } |
|
|
2879 |
|
|
2880 /* Generator function for command completion. STATE lets us |
|
|
2881 know whether to start from scratch; without any state |
|
|
2882 (i.e. STATE == 0), then we start at the top of the list. */ |
|
|
2883 char * |
|
|
2884 command_generator (text, state) |
|
|
2885 const char *text; |
|
|
2886 int state; |
|
|
2887 { |
|
|
2888 static int list_index, len; |
|
|
2889 char *name; |
|
|
2890 |
|
|
2891 /* If this is a new word to complete, initialize now. This |
|
|
2892 includes saving the length of TEXT for efficiency, and |
|
|
2893 initializing the index variable to 0. */ |
|
|
2894 if (!state) |
|
|
2895 { |
|
|
2896 list_index = 0; |
|
|
2897 len = strlen (text); |
|
|
2898 } |
|
|
2899 |
|
|
2900 /* Return the next name which partially matches from the |
|
|
2901 command list. */ |
|
|
2902 while (name = commands[list_index].name) |
|
|
2903 { |
|
|
2904 list_index++; |
|
|
2905 |
|
|
2906 if (strncmp (name, text, len) == 0) |
|
|
2907 return (dupstr(name)); |
|
|
2908 } |
|
|
2909 |
|
|
2910 /* If no names matched, then return NULL. */ |
|
|
2911 return ((char *)NULL); |
|
|
2912 } |
|
|
2913 |
|
|
2914 /* **************************************************************** */ |
|
|
2915 /* */ |
|
|
2916 /* FileMan Commands */ |
|
|
2917 /* */ |
|
|
2918 /* **************************************************************** */ |
|
|
2919 |
|
|
2920 /* String to pass to system (). This is for the LIST, VIEW and RENAME |
|
|
2921 commands. */ |
|
|
2922 static char syscom[1024]; |
|
|
2923 |
|
|
2924 /* List the file(s) named in arg. */ |
|
|
2925 com_list (arg) |
|
|
2926 char *arg; |
|
|
2927 { |
|
|
2928 if (!arg) |
|
|
2929 arg = ""; |
|
|
2930 |
|
|
2931 sprintf (syscom, "ls -FClg %s", arg); |
|
|
2932 return (system (syscom)); |
|
|
2933 } |
|
|
2934 |
|
|
2935 com_view (arg) |
|
|
2936 char *arg; |
|
|
2937 { |
|
|
2938 if (!valid_argument ("view", arg)) |
|
|
2939 return 1; |
|
|
2940 |
|
|
2941 sprintf (syscom, "more %s", arg); |
|
|
2942 return (system (syscom)); |
|
|
2943 } |
|
|
2944 |
|
|
2945 com_rename (arg) |
|
|
2946 char *arg; |
|
|
2947 { |
|
|
2948 too_dangerous ("rename"); |
|
|
2949 return (1); |
|
|
2950 } |
|
|
2951 |
|
|
2952 com_stat (arg) |
|
|
2953 char *arg; |
|
|
2954 { |
|
|
2955 struct stat finfo; |
|
|
2956 |
|
|
2957 if (!valid_argument ("stat", arg)) |
|
|
2958 return (1); |
|
|
2959 |
|
|
2960 if (stat (arg, &finfo) == -1) |
|
|
2961 { |
|
|
2962 perror (arg); |
|
|
2963 return (1); |
|
|
2964 } |
|
|
2965 |
|
|
2966 printf ("Statistics for `%s':\n", arg); |
|
|
2967 |
|
|
2968 printf ("%s has %d link%s, and is %d byte%s in length.\n", arg, |
|
|
2969 finfo.st_nlink, |
|
|
2970 (finfo.st_nlink == 1) ? "" : "s", |
|
|
2971 finfo.st_size, |
|
|
2972 (finfo.st_size == 1) ? "" : "s"); |
|
|
2973 printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime)); |
|
|
2974 printf (" Last access at: %s", ctime (&finfo.st_atime)); |
|
|
2975 printf (" Last modified at: %s", ctime (&finfo.st_mtime)); |
|
|
2976 return (0); |
|
|
2977 } |
|
|
2978 |
|
|
2979 com_delete (arg) |
|
|
2980 char *arg; |
|
|
2981 { |
|
|
2982 too_dangerous ("delete"); |
|
|
2983 return (1); |
|
|
2984 } |
|
|
2985 |
|
|
2986 /* Print out help for ARG, or for all of the commands if ARG is |
|
|
2987 not present. */ |
|
|
2988 com_help (arg) |
|
|
2989 char *arg; |
|
|
2990 { |
|
|
2991 register int i; |
|
|
2992 int printed = 0; |
|
|
2993 |
|
|
2994 for (i = 0; commands[i].name; i++) |
|
|
2995 { |
|
|
2996 if (!*arg || (strcmp (arg, commands[i].name) == 0)) |
|
|
2997 { |
|
|
2998 printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc); |
|
|
2999 printed++; |
|
|
3000 } |
|
|
3001 } |
|
|
3002 |
|
|
3003 if (!printed) |
|
|
3004 { |
|
|
3005 printf ("No commands match `%s'. Possibilties are:\n", arg); |
|
|
3006 |
|
|
3007 for (i = 0; commands[i].name; i++) |
|
|
3008 { |
|
|
3009 /* Print in six columns. */ |
|
|
3010 if (printed == 6) |
|
|
3011 { |
|
|
3012 printed = 0; |
|
|
3013 printf ("\n"); |
|
|
3014 } |
|
|
3015 |
|
|
3016 printf ("%s\t", commands[i].name); |
|
|
3017 printed++; |
|
|
3018 } |
|
|
3019 |
|
|
3020 if (printed) |
|
|
3021 printf ("\n"); |
|
|
3022 } |
|
|
3023 return (0); |
|
|
3024 } |
|
|
3025 |
|
|
3026 /* Change to the directory ARG. */ |
|
|
3027 com_cd (arg) |
|
|
3028 char *arg; |
|
|
3029 { |
|
|
3030 if (chdir (arg) == -1) |
|
|
3031 { |
|
|
3032 perror (arg); |
|
|
3033 return 1; |
|
|
3034 } |
|
|
3035 |
|
|
3036 com_pwd (""); |
|
|
3037 return (0); |
|
|
3038 } |
|
|
3039 |
|
|
3040 /* Print out the current working directory. */ |
|
|
3041 com_pwd (ignore) |
|
|
3042 char *ignore; |
|
|
3043 { |
|
|
3044 char dir[1024], *s; |
|
|
3045 |
|
|
3046 s = getcwd (dir, sizeof(dir) - 1); |
|
|
3047 if (s == 0) |
|
|
3048 { |
|
|
3049 printf ("Error getting pwd: %s\n", dir); |
|
|
3050 return 1; |
|
|
3051 } |
|
|
3052 |
|
|
3053 printf ("Current directory is %s\n", dir); |
|
|
3054 return 0; |
|
|
3055 } |
|
|
3056 |
|
|
3057 /* The user wishes to quit using this program. Just set DONE |
|
|
3058 non-zero. */ |
|
|
3059 com_quit (arg) |
|
|
3060 char *arg; |
|
|
3061 { |
|
|
3062 done = 1; |
|
|
3063 return (0); |
|
|
3064 } |
|
|
3065 |
|
|
3066 /* Function which tells you that you can't do this. */ |
|
|
3067 too_dangerous (caller) |
|
|
3068 char *caller; |
|
|
3069 { |
|
|
3070 fprintf (stderr, |
|
|
3071 "%s: Too dangerous for me to distribute. Write it yourself.\n", |
|
|
3072 caller); |
|
|
3073 } |
|
|
3074 |
|
|
3075 /* Return non-zero if ARG is a valid argument for CALLER, else print |
|
|
3076 an error message and return zero. */ |
|
|
3077 int |
|
|
3078 valid_argument (caller, arg) |
|
|
3079 char *caller, *arg; |
|
|
3080 { |
|
|
3081 if (!arg || !*arg) |
|
|
3082 { |
|
|
3083 fprintf (stderr, "%s: Argument required.\n", caller); |
|
|
3084 return (0); |
|
|
3085 } |
|
|
3086 |
|
|
3087 return (1); |
|
|
3088 } |
|
|
3089 |
|
|
3090 |
|
|
3091 File: readline.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU Readline, Up: Top |
|
|
3092 |
|
|
3093 Concept Index |
|
|
3094 ************* |
|
|
3095 |
|
|
3096 * Menu: |
|
|
3097 |
|
|
3098 * command editing: Readline Bare Essentials. |
|
|
3099 * editing command lines: Readline Bare Essentials. |
|
|
3100 * initialization file, readline: Readline Init File. |
|
|
3101 * interaction, readline: Readline Interaction. |
|
|
3102 * kill ring: Readline Killing Commands. |
|
|
3103 * killing text: Readline Killing Commands. |
|
|
3104 * notation, readline: Readline Bare Essentials. |
|
|
3105 * readline, function: Basic Behavior. |
|
|
3106 * yanking text: Readline Killing Commands. |
|
|
3107 |
|
|
3108 |
|
|
3109 File: readline.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top |
|
|
3110 |
|
|
3111 Function and Variable Index |
|
|
3112 *************************** |
|
|
3113 |
|
|
3114 * Menu: |
|
|
3115 |
|
|
3116 * _rl_digit_p: Utility Functions. |
|
|
3117 * _rl_digit_value: Utility Functions. |
|
|
3118 * _rl_lowercase_p: Utility Functions. |
|
|
3119 * _rl_to_lower: Utility Functions. |
|
|
3120 * _rl_to_upper: Utility Functions. |
|
|
3121 * _rl_uppercase_p: Utility Functions. |
|
|
3122 * abort (C-g): Miscellaneous Commands. |
|
|
3123 * accept-line (Newline or Return): Commands For History. |
|
|
3124 * backward-char (C-b): Commands For Moving. |
|
|
3125 * backward-delete-char (Rubout): Commands For Text. |
|
|
3126 * backward-kill-line (C-x Rubout): Commands For Killing. |
|
|
3127 * backward-kill-word (M-<DEL>): Commands For Killing. |
|
|
3128 * backward-word (M-b): Commands For Moving. |
|
|
3129 * beginning-of-history (M-<): Commands For History. |
|
|
3130 * beginning-of-line (C-a): Commands For Moving. |
|
|
3131 * bell-style: Readline Init File Syntax. |
|
|
3132 * call-last-kbd-macro (C-x e): Keyboard Macros. |
|
|
3133 * capitalize-word (M-c): Commands For Text. |
|
|
3134 * character-search (C-]): Miscellaneous Commands. |
|
|
3135 * character-search-backward (M-C-]): Miscellaneous Commands. |
|
|
3136 * clear-screen (C-l): Commands For Moving. |
|
|
3137 * comment-begin: Readline Init File Syntax. |
|
|
3138 * complete (<TAB>): Commands For Completion. |
|
|
3139 * completion-query-items: Readline Init File Syntax. |
|
|
3140 * convert-meta: Readline Init File Syntax. |
|
|
3141 * copy-backward-word (): Commands For Killing. |
|
|
3142 * copy-forward-word (): Commands For Killing. |
|
|
3143 * copy-region-as-kill (): Commands For Killing. |
|
|
3144 * delete-char (C-d): Commands For Text. |
|
|
3145 * delete-char-or-list (): Commands For Completion. |
|
|
3146 * delete-horizontal-space (): Commands For Killing. |
|
|
3147 * digit-argument (M-0, M-1, ... M--): Numeric Arguments. |
|
|
3148 * disable-completion: Readline Init File Syntax. |
|
|
3149 * do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands. |
|
|
3150 * downcase-word (M-l): Commands For Text. |
|
|
3151 * dump-functions (): Miscellaneous Commands. |
|
|
3152 * dump-macros (): Miscellaneous Commands. |
|
|
3153 * dump-variables (): Miscellaneous Commands. |
|
|
3154 * editing-mode: Readline Init File Syntax. |
|
|
3155 * enable-keypad: Readline Init File Syntax. |
|
|
3156 * end-kbd-macro (C-x )): Keyboard Macros. |
|
|
3157 * end-of-history (M->): Commands For History. |
|
|
3158 * end-of-line (C-e): Commands For Moving. |
|
|
3159 * exchange-point-and-mark (C-x C-x): Miscellaneous Commands. |
|
|
3160 * expand-tilde: Readline Init File Syntax. |
|
|
3161 * forward-backward-delete-char (): Commands For Text. |
|
|
3162 * forward-char (C-f): Commands For Moving. |
|
|
3163 * forward-search-history (C-s): Commands For History. |
|
|
3164 * forward-word (M-f): Commands For Moving. |
|
|
3165 * history-search-backward (): Commands For History. |
|
|
3166 * history-search-forward (): Commands For History. |
|
|
3167 * horizontal-scroll-mode: Readline Init File Syntax. |
|
|
3168 * input-meta: Readline Init File Syntax. |
|
|
3169 * insert-comment (M-#): Miscellaneous Commands. |
|
|
3170 * insert-completions (M-*): Commands For Completion. |
|
|
3171 * isearch-terminators: Readline Init File Syntax. |
|
|
3172 * keymap: Readline Init File Syntax. |
|
|
3173 * kill-line (C-k): Commands For Killing. |
|
|
3174 * kill-region (): Commands For Killing. |
|
|
3175 * kill-whole-line (): Commands For Killing. |
|
|
3176 * kill-word (M-d): Commands For Killing. |
|
|
3177 * mark-modified-lines: Readline Init File Syntax. |
|
|
3178 * menu-complete (): Commands For Completion. |
|
|
3179 * meta-flag: Readline Init File Syntax. |
|
|
3180 * next-history (C-n): Commands For History. |
|
|
3181 * non-incremental-forward-search-history (M-n): Commands For History. |
|
|
3182 * non-incremental-reverse-search-history (M-p): Commands For History. |
|
|
3183 * output-meta: Readline Init File Syntax. |
|
|
3184 * possible-completions (M-?): Commands For Completion. |
|
|
3185 * prefix-meta (<ESC>): Miscellaneous Commands. |
|
|
3186 * previous-history (C-p): Commands For History. |
|
|
3187 * quoted-insert (C-q or C-v): Commands For Text. |
|
|
3188 * re-read-init-file (C-x C-r): Miscellaneous Commands. |
|
|
3189 * readline: Basic Behavior. |
|
|
3190 * redraw-current-line (): Commands For Moving. |
|
|
3191 * reverse-search-history (C-r): Commands For History. |
|
|
3192 * revert-line (M-r): Miscellaneous Commands. |
|
|
3193 * rl_add_defun: Function Naming. |
|
|
3194 * rl_add_funmap_entry: Associating Function Names and Bindings. |
|
|
3195 * rl_add_undo: Allowing Undoing. |
|
|
3196 * rl_alphabetic: Utility Functions. |
|
|
3197 * rl_already_prompted: Readline Variables. |
|
|
3198 * rl_attempted_completion_function: Completion Variables. |
|
|
3199 * rl_attempted_completion_over: Completion Variables. |
|
|
3200 * rl_basic_quote_characters: Completion Variables. |
|
|
3201 * rl_basic_word_break_characters: Completion Variables. |
|
|
3202 * rl_begin_undo_group: Allowing Undoing. |
|
|
3203 * rl_bind_key: Binding Keys. |
|
|
3204 * rl_bind_key_in_map: Binding Keys. |
|
|
3205 * rl_binding_keymap: Readline Variables. |
|
|
3206 * rl_callback_handler_install: Alternate Interface. |
|
|
3207 * rl_callback_handler_remove: Alternate Interface. |
|
|
3208 * rl_callback_read_char: Alternate Interface. |
|
|
3209 * rl_catch_signals: Readline Signal Handling. |
|
|
3210 * rl_catch_sigwinch: Readline Signal Handling. |
|
|
3211 * rl_char_is_quoted_p: Completion Variables. |
|
|
3212 * rl_cleanup_after_signal: Readline Signal Handling. |
|
|
3213 * rl_clear_message: Redisplay. |
|
|
3214 * rl_clear_pending_input: Character Input. |
|
|
3215 * rl_clear_signals: Readline Signal Handling. |
|
|
3216 * rl_complete <1>: How Completing Works. |
|
|
3217 * rl_complete: Completion Functions. |
|
|
3218 * rl_complete_internal: Completion Functions. |
|
|
3219 * rl_completer_quote_characters: Completion Variables. |
|
|
3220 * rl_completer_word_break_characters: Completion Variables. |
|
|
3221 * rl_completion_append_character: Completion Variables. |
|
|
3222 * rl_completion_display_matches_hook: Completion Variables. |
|
|
3223 * rl_completion_entry_function <1>: How Completing Works. |
|
|
3224 * rl_completion_entry_function: Completion Variables. |
|
|
3225 * rl_completion_matches: Completion Functions. |
|
|
3226 * rl_completion_query_items: Completion Variables. |
|
|
3227 * rl_completion_type: Completion Variables. |
|
|
3228 * rl_copy_keymap: Keymaps. |
|
|
3229 * rl_copy_text: Modifying Text. |
|
|
3230 * rl_crlf: Redisplay. |
|
|
3231 * rl_delete_text: Modifying Text. |
|
|
3232 * rl_deprep_term_function: Readline Variables. |
|
|
3233 * rl_deprep_terminal: Terminal Management. |
|
|
3234 * rl_ding: Utility Functions. |
|
|
3235 * rl_directory_completion_hook: Completion Variables. |
|
|
3236 * rl_discard_keymap: Keymaps. |
|
|
3237 * rl_dispatching: Readline Variables. |
|
|
3238 * rl_display_match_list: Utility Functions. |
|
|
3239 * rl_do_undo: Allowing Undoing. |
|
|
3240 * rl_done: Readline Variables. |
|
|
3241 * rl_editing_mode: Readline Variables. |
|
|
3242 * rl_end: Readline Variables. |
|
|
3243 * rl_end_undo_group: Allowing Undoing. |
|
|
3244 * rl_erase_empty_line: Readline Variables. |
|
|
3245 * rl_event_hook: Readline Variables. |
|
|
3246 * rl_execute_next: Character Input. |
|
|
3247 * rl_executing_keymap: Readline Variables. |
|
|
3248 * rl_executing_macro: Readline Variables. |
|
|
3249 * rl_expand_prompt: Redisplay. |
|
|
3250 * rl_explicit_arg: Readline Variables. |
|
|
3251 * rl_extend_line_buffer: Utility Functions. |
|
|
3252 * rl_filename_completion_desired: Completion Variables. |
|
|
3253 * rl_filename_completion_function: Completion Functions. |
|
|
3254 * rl_filename_dequoting_function: Completion Variables. |
|
|
3255 * rl_filename_quote_characters: Completion Variables. |
|
|
3256 * rl_filename_quoting_desired: Completion Variables. |
|
|
3257 * rl_filename_quoting_function: Completion Variables. |
|
|
3258 * rl_forced_update_display: Redisplay. |
|
|
3259 * rl_free_line_state: Readline Signal Handling. |
|
|
3260 * rl_free_undo_list: Allowing Undoing. |
|
|
3261 * rl_function_dumper: Associating Function Names and Bindings. |
|
|
3262 * rl_function_of_keyseq: Associating Function Names and Bindings. |
|
|
3263 * rl_funmap_names: Associating Function Names and Bindings. |
|
|
3264 * rl_generic_bind: Binding Keys. |
|
|
3265 * rl_get_keymap: Keymaps. |
|
|
3266 * rl_get_keymap_by_name: Keymaps. |
|
|
3267 * rl_get_keymap_name: Keymaps. |
|
|
3268 * rl_getc: Character Input. |
|
|
3269 * rl_getc_function: Readline Variables. |
|
|
3270 * rl_gnu_readline_p: Readline Variables. |
|
|
3271 * rl_ignore_completion_duplicates: Completion Variables. |
|
|
3272 * rl_ignore_some_completions_function: Completion Variables. |
|
|
3273 * rl_inhibit_completion: Completion Variables. |
|
|
3274 * rl_initialize: Utility Functions. |
|
|
3275 * rl_insert_completions: Completion Functions. |
|
|
3276 * rl_insert_text: Modifying Text. |
|
|
3277 * rl_instream: Readline Variables. |
|
|
3278 * rl_invoking_keyseqs: Associating Function Names and Bindings. |
|
|
3279 * rl_invoking_keyseqs_in_map: Associating Function Names and Bindings. |
|
|
3280 * rl_kill_text: Modifying Text. |
|
|
3281 * rl_last_func: Readline Variables. |
|
|
3282 * rl_library_version: Readline Variables. |
|
|
3283 * rl_line_buffer: Readline Variables. |
|
|
3284 * rl_list_funmap_names: Associating Function Names and Bindings. |
|
|
3285 * rl_make_bare_keymap: Keymaps. |
|
|
3286 * rl_make_keymap: Keymaps. |
|
|
3287 * rl_mark: Readline Variables. |
|
|
3288 * rl_message: Redisplay. |
|
|
3289 * rl_modifying: Allowing Undoing. |
|
|
3290 * rl_named_function: Associating Function Names and Bindings. |
|
|
3291 * rl_num_chars_to_read: Readline Variables. |
|
|
3292 * rl_numeric_arg: Readline Variables. |
|
|
3293 * rl_on_new_line: Redisplay. |
|
|
3294 * rl_on_new_line_with_prompt: Redisplay. |
|
|
3295 * rl_outstream: Readline Variables. |
|
|
3296 * rl_parse_and_bind: Binding Keys. |
|
|
3297 * rl_pending_input: Readline Variables. |
|
|
3298 * rl_point: Readline Variables. |
|
|
3299 * rl_possible_completions: Completion Functions. |
|
|
3300 * rl_pre_input_hook: Readline Variables. |
|
|
3301 * rl_prep_term_function: Readline Variables. |
|
|
3302 * rl_prep_terminal: Terminal Management. |
|
|
3303 * rl_prompt: Readline Variables. |
|
|
3304 * rl_read_init_file: Binding Keys. |
|
|
3305 * rl_read_key: Character Input. |
|
|
3306 * rl_readline_name: Readline Variables. |
|
|
3307 * rl_readline_state: Readline Variables. |
|
|
3308 * rl_redisplay: Redisplay. |
|
|
3309 * rl_redisplay_function: Readline Variables. |
|
|
3310 * rl_reset_after_signal: Readline Signal Handling. |
|
|
3311 * rl_reset_line_state: Redisplay. |
|
|
3312 * rl_reset_terminal: Terminal Management. |
|
|
3313 * rl_resize_terminal: Readline Signal Handling. |
|
|
3314 * rl_restore_prompt: Redisplay. |
|
|
3315 * rl_save_prompt: Redisplay. |
|
|
3316 * rl_set_key: Binding Keys. |
|
|
3317 * rl_set_keymap: Keymaps. |
|
|
3318 * rl_set_screen_size: Readline Signal Handling. |
|
|
3319 * rl_set_signals: Readline Signal Handling. |
|
|
3320 * rl_special_prefixes: Completion Variables. |
|
|
3321 * rl_startup_hook: Readline Variables. |
|
|
3322 * rl_stuff_char: Character Input. |
|
|
3323 * rl_terminal_name: Readline Variables. |
|
|
3324 * rl_tty_set_default_bindings: Terminal Management. |
|
|
3325 * rl_unbind_command_in_map: Binding Keys. |
|
|
3326 * rl_unbind_function_in_map: Binding Keys. |
|
|
3327 * rl_unbind_key: Binding Keys. |
|
|
3328 * rl_unbind_key_in_map: Binding Keys. |
|
|
3329 * rl_username_completion_function: Completion Functions. |
|
|
3330 * self-insert (a, b, A, 1, !, ...): Commands For Text. |
|
|
3331 * set-mark (C-@): Miscellaneous Commands. |
|
|
3332 * show-all-if-ambiguous: Readline Init File Syntax. |
|
|
3333 * start-kbd-macro (C-x (): Keyboard Macros. |
|
|
3334 * transpose-chars (C-t): Commands For Text. |
|
|
3335 * transpose-words (M-t): Commands For Text. |
|
|
3336 * undo (C-_ or C-x C-u): Miscellaneous Commands. |
|
|
3337 * universal-argument (): Numeric Arguments. |
|
|
3338 * unix-line-discard (C-u): Commands For Killing. |
|
|
3339 * unix-word-rubout (C-w): Commands For Killing. |
|
|
3340 * upcase-word (M-u): Commands For Text. |
|
|
3341 * visible-stats: Readline Init File Syntax. |
|
|
3342 * yank (C-y): Commands For Killing. |
|
|
3343 * yank-last-arg (M-. or M-_): Commands For History. |
|
|
3344 * yank-nth-arg (M-C-y): Commands For History. |
|
|
3345 * yank-pop (M-y): Commands For Killing. |
|
|
3346 |
|
|
3347 |
|
|
3348 |
|
|
3349 Tag Table: |
|
|
3350 Node: Top1164 |
|
|
3351 Node: Command Line Editing1763 |
|
|
3352 Node: Introduction and Notation2414 |
|
|
3353 Node: Readline Interaction4032 |
|
|
3354 Node: Readline Bare Essentials5219 |
|
|
3355 Node: Readline Movement Commands7000 |
|
|
3356 Node: Readline Killing Commands7957 |
|
|
3357 Node: Readline Arguments9867 |
|
|
3358 Node: Searching10903 |
|
|
3359 Node: Readline Init File12859 |
|
|
3360 Node: Readline Init File Syntax13920 |
|
|
3361 Node: Conditional Init Constructs23536 |
|
|
3362 Node: Sample Init File25975 |
|
|
3363 Node: Bindable Readline Commands29145 |
|
|
3364 Node: Commands For Moving30195 |
|
|
3365 Node: Commands For History31044 |
|
|
3366 Node: Commands For Text33826 |
|
|
3367 Node: Commands For Killing35831 |
|
|
3368 Node: Numeric Arguments37804 |
|
|
3369 Node: Commands For Completion38932 |
|
|
3370 Node: Keyboard Macros40421 |
|
|
3371 Node: Miscellaneous Commands40980 |
|
|
3372 Node: Readline vi Mode43796 |
|
|
3373 Node: Programming with GNU Readline45549 |
|
|
3374 Node: Basic Behavior46517 |
|
|
3375 Node: Custom Functions49930 |
|
|
3376 Node: Readline Typedefs50908 |
|
|
3377 Node: Function Writing52537 |
|
|
3378 Node: Readline Variables53621 |
|
|
3379 Node: Readline Convenience Functions62417 |
|
|
3380 Node: Function Naming63272 |
|
|
3381 Node: Keymaps64524 |
|
|
3382 Node: Binding Keys66280 |
|
|
3383 Node: Associating Function Names and Bindings69206 |
|
|
3384 Node: Allowing Undoing71451 |
|
|
3385 Node: Redisplay73986 |
|
|
3386 Node: Modifying Text76536 |
|
|
3387 Node: Character Input77451 |
|
|
3388 Node: Terminal Management78661 |
|
|
3389 Node: Utility Functions79830 |
|
|
3390 Node: Alternate Interface81893 |
|
|
3391 Node: Readline Signal Handling85289 |
|
|
3392 Node: Custom Completers90545 |
|
|
3393 Node: How Completing Works91260 |
|
|
3394 Node: Completion Functions94258 |
|
|
3395 Node: Completion Variables97317 |
|
|
3396 Node: A Short Completion Example106674 |
|
|
3397 Node: Concept Index119199 |
|
|
3398 Node: Function and Variable Index119953 |
|
|
3399 |
|
|
3400 End Tag Table |
