Commit | Line | Data |
---|---|---|
a44161c3 EZ |
1 | <HTML> |
2 | <HEAD> | |
3 | <!-- This HTML file has been created by texi2html 1.52 | |
f9267e15 | 4 | from /usr/homes/chet/src/bash/readline-src/doc/rlman.texinfo on 1 March 2000 --> |
a44161c3 EZ |
5 | |
6 | <TITLE>GNU Readline Library</TITLE> | |
7 | </HEAD> | |
8 | <BODY> | |
9 | <H1>GNU Readline Library</H1> | |
f9267e15 EZ |
10 | <H2>Edition 4.1, for <CODE>Readline Library</CODE> Version 4.1.</H2> |
11 | <H2>January 2000</H2> | |
a44161c3 EZ |
12 | <ADDRESS>Brian Fox, Free Software Foundation</ADDRESS> |
13 | <ADDRESS>Chet Ramey, Case Western Reserve University</ADDRESS> | |
14 | <P> | |
15 | <P><HR><P> | |
16 | <H1>Table of Contents</H1> | |
17 | <UL> | |
18 | <LI><A NAME="TOC1" HREF="readline.html#SEC1">Command Line Editing</A> | |
19 | <UL> | |
20 | <LI><A NAME="TOC2" HREF="readline.html#SEC2">Introduction to Line Editing</A> | |
21 | <LI><A NAME="TOC3" HREF="readline.html#SEC3">Readline Interaction</A> | |
22 | <UL> | |
23 | <LI><A NAME="TOC4" HREF="readline.html#SEC4">Readline Bare Essentials</A> | |
24 | <LI><A NAME="TOC5" HREF="readline.html#SEC5">Readline Movement Commands</A> | |
25 | <LI><A NAME="TOC6" HREF="readline.html#SEC6">Readline Killing Commands</A> | |
26 | <LI><A NAME="TOC7" HREF="readline.html#SEC7">Readline Arguments</A> | |
27 | <LI><A NAME="TOC8" HREF="readline.html#SEC8">Searching for Commands in the History</A> | |
28 | </UL> | |
29 | <LI><A NAME="TOC9" HREF="readline.html#SEC9">Readline Init File</A> | |
30 | <UL> | |
31 | <LI><A NAME="TOC10" HREF="readline.html#SEC10">Readline Init File Syntax</A> | |
32 | <LI><A NAME="TOC11" HREF="readline.html#SEC11">Conditional Init Constructs</A> | |
33 | <LI><A NAME="TOC12" HREF="readline.html#SEC12">Sample Init File</A> | |
34 | </UL> | |
35 | <LI><A NAME="TOC13" HREF="readline.html#SEC13">Bindable Readline Commands</A> | |
36 | <UL> | |
37 | <LI><A NAME="TOC14" HREF="readline.html#SEC14">Commands For Moving</A> | |
38 | <LI><A NAME="TOC15" HREF="readline.html#SEC15">Commands For Manipulating The History</A> | |
39 | <LI><A NAME="TOC16" HREF="readline.html#SEC16">Commands For Changing Text</A> | |
40 | <LI><A NAME="TOC17" HREF="readline.html#SEC17">Killing And Yanking</A> | |
41 | <LI><A NAME="TOC18" HREF="readline.html#SEC18">Specifying Numeric Arguments</A> | |
42 | <LI><A NAME="TOC19" HREF="readline.html#SEC19">Letting Readline Type For You</A> | |
43 | <LI><A NAME="TOC20" HREF="readline.html#SEC20">Keyboard Macros</A> | |
44 | <LI><A NAME="TOC21" HREF="readline.html#SEC21">Some Miscellaneous Commands</A> | |
45 | </UL> | |
46 | <LI><A NAME="TOC22" HREF="readline.html#SEC22">Readline vi Mode</A> | |
47 | </UL> | |
48 | <LI><A NAME="TOC23" HREF="readline.html#SEC23">Programming with GNU Readline</A> | |
49 | <UL> | |
50 | <LI><A NAME="TOC24" HREF="readline.html#SEC24">Basic Behavior</A> | |
51 | <LI><A NAME="TOC25" HREF="readline.html#SEC25">Custom Functions</A> | |
52 | <UL> | |
53 | <LI><A NAME="TOC26" HREF="readline.html#SEC26">The Function Type</A> | |
54 | <LI><A NAME="TOC27" HREF="readline.html#SEC27">Writing a New Function</A> | |
55 | </UL> | |
56 | <LI><A NAME="TOC28" HREF="readline.html#SEC28">Readline Variables</A> | |
57 | <LI><A NAME="TOC29" HREF="readline.html#SEC29">Readline Convenience Functions</A> | |
58 | <UL> | |
59 | <LI><A NAME="TOC30" HREF="readline.html#SEC30">Naming a Function</A> | |
60 | <LI><A NAME="TOC31" HREF="readline.html#SEC31">Selecting a Keymap</A> | |
61 | <LI><A NAME="TOC32" HREF="readline.html#SEC32">Binding Keys</A> | |
62 | <LI><A NAME="TOC33" HREF="readline.html#SEC33">Associating Function Names and Bindings</A> | |
63 | <LI><A NAME="TOC34" HREF="readline.html#SEC34">Allowing Undoing</A> | |
64 | <LI><A NAME="TOC35" HREF="readline.html#SEC35">Redisplay</A> | |
65 | <LI><A NAME="TOC36" HREF="readline.html#SEC36">Modifying Text</A> | |
66 | <LI><A NAME="TOC37" HREF="readline.html#SEC37">Utility Functions</A> | |
67 | <LI><A NAME="TOC38" HREF="readline.html#SEC38">Alternate Interface</A> | |
68 | <LI><A NAME="TOC39" HREF="readline.html#SEC39">An Example</A> | |
69 | </UL> | |
70 | <LI><A NAME="TOC40" HREF="readline.html#SEC40">Readline Signal Handling</A> | |
71 | <LI><A NAME="TOC41" HREF="readline.html#SEC41">Custom Completers</A> | |
72 | <UL> | |
73 | <LI><A NAME="TOC42" HREF="readline.html#SEC42">How Completing Works</A> | |
74 | <LI><A NAME="TOC43" HREF="readline.html#SEC43">Completion Functions</A> | |
75 | <LI><A NAME="TOC44" HREF="readline.html#SEC44">Completion Variables</A> | |
76 | <LI><A NAME="TOC45" HREF="readline.html#SEC45">A Short Completion Example</A> | |
77 | </UL> | |
78 | </UL> | |
79 | <LI><A NAME="TOC46" HREF="readline.html#SEC46">Concept Index</A> | |
80 | <LI><A NAME="TOC47" HREF="readline.html#SEC47">Function and Variable Index</A> | |
81 | </UL> | |
82 | <P><HR><P> | |
83 | ||
84 | <P> | |
85 | This document describes the GNU Readline Library, a utility which aids | |
86 | in the consistency of user interface across discrete programs that need | |
87 | to provide a command line interface. | |
88 | ||
89 | </P> | |
90 | <P> | |
91 | Published by the Free Software Foundation <BR> | |
f9267e15 EZ |
92 | 59 Temple Place, Suite 330, <BR> |
93 | Boston, MA 02111 USA | |
a44161c3 EZ |
94 | |
95 | </P> | |
96 | <P> | |
97 | Permission is granted to make and distribute verbatim copies of | |
98 | this manual provided the copyright notice and this permission notice | |
99 | are preserved on all copies. | |
100 | ||
101 | </P> | |
102 | <P> | |
103 | Permission is granted to copy and distribute modified versions of this | |
104 | manual under the conditions for verbatim copying, provided that the entire | |
105 | resulting derived work is distributed under the terms of a permission | |
106 | notice identical to this one. | |
107 | ||
108 | </P> | |
109 | <P> | |
110 | Permission is granted to copy and distribute translations of this manual | |
111 | into another language, under the above conditions for modified versions, | |
112 | except that this permission notice may be stated in a translation approved | |
113 | by the Free Software Foundation. | |
114 | ||
115 | </P> | |
116 | <P> | |
117 | Copyright (C) 1988-1999 Free Software Foundation, Inc. | |
118 | ||
119 | </P> | |
120 | ||
121 | ||
122 | ||
123 | <H1><A NAME="SEC1" HREF="readline.html#TOC1">Command Line Editing</A></H1> | |
124 | ||
125 | <P> | |
126 | This chapter describes the basic features of the GNU | |
127 | command line editing interface. | |
128 | ||
129 | </P> | |
130 | ||
131 | <UL> | |
132 | <LI><A HREF="readline.html#SEC2">Introduction and Notation</A>: Notation used in this text. | |
133 | <LI><A HREF="readline.html#SEC3">Readline Interaction</A>: The minimum set of commands for editing a line. | |
134 | <LI><A HREF="readline.html#SEC9">Readline Init File</A>: Customizing Readline from a user's view. | |
135 | <LI><A HREF="readline.html#SEC13">Bindable Readline Commands</A>: A description of most of the Readline commands | |
136 | available for binding | |
137 | <LI><A HREF="readline.html#SEC22">Readline vi Mode</A>: A short description of how to make Readline | |
138 | behave like the vi editor. | |
139 | </UL> | |
140 | ||
141 | ||
142 | ||
143 | <H2><A NAME="SEC2" HREF="readline.html#TOC2">Introduction to Line Editing</A></H2> | |
144 | ||
145 | <P> | |
146 | The following paragraphs describe the notation used to represent | |
147 | keystrokes. | |
148 | ||
149 | </P> | |
150 | <P> | |
151 | The text <KBD>C-k</KBD> is read as `Control-K' and describes the character | |
152 | produced when the <KBD>k</KBD> key is pressed while the Control key | |
153 | is depressed. | |
154 | ||
155 | </P> | |
156 | <P> | |
157 | The text <KBD>M-k</KBD> is read as `Meta-K' and describes the character | |
f9267e15 EZ |
158 | produced when the Meta key (if you have one) is depressed, and the <KBD>k</KBD> |
159 | key is pressed. | |
160 | The Meta key is labeled <KBD>ALT</KBD> on many keyboards. | |
161 | On keyboards with two keys labeled <KBD>ALT</KBD> (usually to either side of | |
162 | the space bar), the <KBD>ALT</KBD> on the left side is generally set to | |
163 | work as a Meta key. | |
164 | The <KBD>ALT</KBD> key on the right may also be configured to work as a | |
165 | Meta key or may be configured as some other modifier, such as a | |
166 | Compose key for typing accented characters. | |
167 | ||
168 | </P> | |
169 | <P> | |
170 | If you do not have a Meta or <KBD>ALT</KBD> key, or another key working as | |
171 | a Meta key, the identical keystroke can be generated by typing <KBD>ESC</KBD> | |
172 | <I>first</I>, and then typing <KBD>k</KBD>. | |
a44161c3 EZ |
173 | Either process is known as <EM>metafying</EM> the <KBD>k</KBD> key. |
174 | ||
175 | </P> | |
176 | <P> | |
177 | The text <KBD>M-C-k</KBD> is read as `Meta-Control-k' and describes the | |
178 | character produced by <EM>metafying</EM> <KBD>C-k</KBD>. | |
179 | ||
180 | </P> | |
181 | <P> | |
182 | In addition, several keys have their own names. Specifically, | |
183 | <KBD>DEL</KBD>, <KBD>ESC</KBD>, <KBD>LFD</KBD>, <KBD>SPC</KBD>, <KBD>RET</KBD>, and <KBD>TAB</KBD> all | |
184 | stand for themselves when seen in this text, or in an init file | |
185 | (see section <A HREF="readline.html#SEC9">Readline Init File</A>). | |
f9267e15 EZ |
186 | If your keyboard lacks a <KBD>LFD</KBD> key, typing <KBD>C-j</KBD> will |
187 | produce the desired character. | |
188 | The <KBD>RET</KBD> key may be labeled <KBD>Return</KBD> or <KBD>Enter</KBD> on | |
189 | some keyboards. | |
a44161c3 EZ |
190 | |
191 | </P> | |
192 | ||
193 | ||
194 | <H2><A NAME="SEC3" HREF="readline.html#TOC3">Readline Interaction</A></H2> | |
195 | <P> | |
196 | <A NAME="IDX1"></A> | |
197 | ||
198 | </P> | |
199 | <P> | |
200 | Often during an interactive session you type in a long line of text, | |
201 | only to notice that the first word on the line is misspelled. The | |
202 | Readline library gives you a set of commands for manipulating the text | |
203 | as you type it in, allowing you to just fix your typo, and not forcing | |
204 | you to retype the majority of the line. Using these editing commands, | |
205 | you move the cursor to the place that needs correction, and delete or | |
206 | insert the text of the corrections. Then, when you are satisfied with | |
207 | the line, you simply press <KBD>RETURN</KBD>. You do not have to be at the | |
208 | end of the line to press <KBD>RETURN</KBD>; the entire line is accepted | |
209 | regardless of the location of the cursor within the line. | |
210 | ||
211 | </P> | |
212 | ||
213 | <UL> | |
214 | <LI><A HREF="readline.html#SEC4">Readline Bare Essentials</A>: The least you need to know about Readline. | |
215 | <LI><A HREF="readline.html#SEC5">Readline Movement Commands</A>: Moving about the input line. | |
216 | <LI><A HREF="readline.html#SEC6">Readline Killing Commands</A>: How to delete text, and how to get it back! | |
217 | <LI><A HREF="readline.html#SEC7">Readline Arguments</A>: Giving numeric arguments to commands. | |
218 | <LI><A HREF="readline.html#SEC8">Searching</A>: Searching through previous lines. | |
219 | </UL> | |
220 | ||
221 | ||
222 | ||
223 | <H3><A NAME="SEC4" HREF="readline.html#TOC4">Readline Bare Essentials</A></H3> | |
224 | <P> | |
225 | <A NAME="IDX2"></A> | |
226 | <A NAME="IDX3"></A> | |
227 | <A NAME="IDX4"></A> | |
228 | ||
229 | </P> | |
230 | <P> | |
231 | In order to enter characters into the line, simply type them. The typed | |
232 | character appears where the cursor was, and then the cursor moves one | |
233 | space to the right. If you mistype a character, you can use your | |
234 | erase character to back up and delete the mistyped character. | |
235 | ||
236 | </P> | |
237 | <P> | |
f9267e15 EZ |
238 | Sometimes you may mistype a character, and |
239 | not notice the error until you have typed several other characters. In | |
a44161c3 EZ |
240 | that case, you can type <KBD>C-b</KBD> to move the cursor to the left, and then |
241 | correct your mistake. Afterwards, you can move the cursor to the right | |
242 | with <KBD>C-f</KBD>. | |
243 | ||
244 | </P> | |
245 | <P> | |
246 | When you add text in the middle of a line, you will notice that characters | |
247 | to the right of the cursor are `pushed over' to make room for the text | |
248 | that you have inserted. Likewise, when you delete text behind the cursor, | |
249 | characters to the right of the cursor are `pulled back' to fill in the | |
f9267e15 | 250 | blank space created by the removal of the text. A list of the bare |
a44161c3 EZ |
251 | essentials for editing the text of an input line follows. |
252 | ||
253 | </P> | |
254 | <DL COMPACT> | |
255 | ||
256 | <DT><KBD>C-b</KBD> | |
257 | <DD> | |
258 | Move back one character. | |
259 | <DT><KBD>C-f</KBD> | |
260 | <DD> | |
261 | Move forward one character. | |
f9267e15 | 262 | <DT><KBD>DEL</KBD> or <KBD>Backspace</KBD> |
a44161c3 EZ |
263 | <DD> |
264 | Delete the character to the left of the cursor. | |
265 | <DT><KBD>C-d</KBD> | |
266 | <DD> | |
267 | Delete the character underneath the cursor. | |
268 | <DT>Printing characters | |
269 | <DD> | |
270 | Insert the character into the line at the cursor. | |
f9267e15 | 271 | <DT><KBD>C-_</KBD> or <KBD>C-x C-u</KBD> |
a44161c3 EZ |
272 | <DD> |
273 | Undo the last editing command. You can undo all the way back to an | |
274 | empty line. | |
275 | </DL> | |
276 | ||
f9267e15 EZ |
277 | <P> |
278 | (Depending on your configuration, the <KBD>Backspace</KBD> key be set to | |
279 | delete the character to the left of the cursor and the <KBD>DEL</KBD> key set | |
280 | to delete the character underneath the cursor, like <KBD>C-d</KBD>, rather | |
281 | than the character to the left of the cursor.) | |
282 | ||
283 | </P> | |
a44161c3 EZ |
284 | |
285 | ||
286 | <H3><A NAME="SEC5" HREF="readline.html#TOC5">Readline Movement Commands</A></H3> | |
287 | ||
288 | <P> | |
f9267e15 | 289 | The above table describes the most basic keystrokes that you need |
a44161c3 EZ |
290 | in order to do editing of the input line. For your convenience, many |
291 | other commands have been added in addition to <KBD>C-b</KBD>, <KBD>C-f</KBD>, | |
292 | <KBD>C-d</KBD>, and <KBD>DEL</KBD>. Here are some commands for moving more rapidly | |
293 | about the line. | |
294 | ||
295 | </P> | |
296 | <DL COMPACT> | |
297 | ||
298 | <DT><KBD>C-a</KBD> | |
299 | <DD> | |
300 | Move to the start of the line. | |
301 | <DT><KBD>C-e</KBD> | |
302 | <DD> | |
303 | Move to the end of the line. | |
304 | <DT><KBD>M-f</KBD> | |
305 | <DD> | |
306 | Move forward a word, where a word is composed of letters and digits. | |
307 | <DT><KBD>M-b</KBD> | |
308 | <DD> | |
309 | Move backward a word. | |
310 | <DT><KBD>C-l</KBD> | |
311 | <DD> | |
312 | Clear the screen, reprinting the current line at the top. | |
313 | </DL> | |
314 | ||
315 | <P> | |
316 | Notice how <KBD>C-f</KBD> moves forward a character, while <KBD>M-f</KBD> moves | |
317 | forward a word. It is a loose convention that control keystrokes | |
318 | operate on characters while meta keystrokes operate on words. | |
319 | ||
320 | </P> | |
321 | ||
322 | ||
323 | <H3><A NAME="SEC6" HREF="readline.html#TOC6">Readline Killing Commands</A></H3> | |
324 | ||
325 | <P> | |
326 | <A NAME="IDX5"></A> | |
327 | <A NAME="IDX6"></A> | |
328 | ||
329 | </P> | |
330 | <P> | |
331 | <EM>Killing</EM> text means to delete the text from the line, but to save | |
332 | it away for later use, usually by <EM>yanking</EM> (re-inserting) | |
333 | it back into the line. | |
f9267e15 EZ |
334 | (`Cut' and `paste' are more recent jargon for `kill' and `yank'.) |
335 | ||
336 | </P> | |
337 | <P> | |
a44161c3 EZ |
338 | If the description for a command says that it `kills' text, then you can |
339 | be sure that you can get the text back in a different (or the same) | |
340 | place later. | |
341 | ||
342 | </P> | |
343 | <P> | |
344 | When you use a kill command, the text is saved in a <EM>kill-ring</EM>. | |
345 | Any number of consecutive kills save all of the killed text together, so | |
346 | that when you yank it back, you get it all. The kill | |
347 | ring is not line specific; the text that you killed on a previously | |
348 | typed line is available to be yanked back later, when you are typing | |
349 | another line. | |
350 | <A NAME="IDX7"></A> | |
351 | ||
352 | </P> | |
353 | <P> | |
354 | Here is the list of commands for killing text. | |
355 | ||
356 | </P> | |
357 | <DL COMPACT> | |
358 | ||
359 | <DT><KBD>C-k</KBD> | |
360 | <DD> | |
361 | Kill the text from the current cursor position to the end of the line. | |
362 | ||
363 | <DT><KBD>M-d</KBD> | |
364 | <DD> | |
f9267e15 | 365 | Kill from the cursor to the end of the current word, or, if between |
a44161c3 | 366 | words, to the end of the next word. |
f9267e15 | 367 | Word boundaries are the same as those used by <KBD>M-f</KBD>. |
a44161c3 EZ |
368 | |
369 | <DT><KBD>M-DEL</KBD> | |
370 | <DD> | |
f9267e15 | 371 | Kill from the cursor the start of the previous word, or, if between |
a44161c3 | 372 | words, to the start of the previous word. |
f9267e15 | 373 | Word boundaries are the same as those used by <KBD>M-b</KBD>. |
a44161c3 EZ |
374 | |
375 | <DT><KBD>C-w</KBD> | |
376 | <DD> | |
377 | Kill from the cursor to the previous whitespace. This is different than | |
378 | <KBD>M-DEL</KBD> because the word boundaries differ. | |
379 | ||
380 | </DL> | |
381 | ||
382 | <P> | |
383 | Here is how to <EM>yank</EM> the text back into the line. Yanking | |
384 | means to copy the most-recently-killed text from the kill buffer. | |
385 | ||
386 | </P> | |
387 | <DL COMPACT> | |
388 | ||
389 | <DT><KBD>C-y</KBD> | |
390 | <DD> | |
391 | Yank the most recently killed text back into the buffer at the cursor. | |
392 | ||
393 | <DT><KBD>M-y</KBD> | |
394 | <DD> | |
395 | Rotate the kill-ring, and yank the new top. You can only do this if | |
396 | the prior command is <KBD>C-y</KBD> or <KBD>M-y</KBD>. | |
397 | </DL> | |
398 | ||
399 | ||
400 | ||
401 | <H3><A NAME="SEC7" HREF="readline.html#TOC7">Readline Arguments</A></H3> | |
402 | ||
403 | <P> | |
404 | You can pass numeric arguments to Readline commands. Sometimes the | |
405 | argument acts as a repeat count, other times it is the <I>sign</I> of the | |
406 | argument that is significant. If you pass a negative argument to a | |
407 | command which normally acts in a forward direction, that command will | |
408 | act in a backward direction. For example, to kill text back to the | |
409 | start of the line, you might type <SAMP>`M-- C-k'</SAMP>. | |
410 | ||
411 | </P> | |
412 | <P> | |
413 | The general way to pass numeric arguments to a command is to type meta | |
414 | digits before the command. If the first `digit' typed is a minus | |
f9267e15 | 415 | sign (<SAMP>`-'</SAMP>), then the sign of the argument will be negative. Once |
a44161c3 EZ |
416 | you have typed one meta digit to get the argument started, you can type |
417 | the remainder of the digits, and then the command. For example, to give | |
418 | the <KBD>C-d</KBD> command an argument of 10, you could type <SAMP>`M-1 0 C-d'</SAMP>. | |
419 | ||
420 | </P> | |
421 | ||
422 | ||
423 | <H3><A NAME="SEC8" HREF="readline.html#TOC8">Searching for Commands in the History</A></H3> | |
424 | ||
425 | <P> | |
426 | Readline provides commands for searching through the command history | |
427 | for lines containing a specified string. | |
428 | There are two search modes: <VAR>incremental</VAR> and <VAR>non-incremental</VAR>. | |
429 | ||
430 | </P> | |
431 | <P> | |
432 | Incremental searches begin before the user has finished typing the | |
433 | search string. | |
434 | As each character of the search string is typed, Readline displays | |
435 | the next entry from the history matching the string typed so far. | |
436 | An incremental search requires only as many characters as needed to | |
437 | find the desired history entry. | |
f9267e15 EZ |
438 | To search backward in the history for a particular string, type |
439 | <KBD>C-r</KBD>. Typing <KBD>C-s</KBD> searches forward through the history. | |
440 | The characters present in the value of the <CODE>isearch-terminators</CODE> variable | |
a44161c3 EZ |
441 | are used to terminate an incremental search. |
442 | If that variable has not been assigned a value, the <KBD>ESC</KBD> and | |
443 | <KBD>C-J</KBD> characters will terminate an incremental search. | |
444 | <KBD>C-g</KBD> will abort an incremental search and restore the original line. | |
445 | When the search is terminated, the history entry containing the | |
446 | search string becomes the current line. | |
f9267e15 EZ |
447 | |
448 | </P> | |
449 | <P> | |
450 | To find other matching entries in the history list, type <KBD>C-r</KBD> or | |
451 | <KBD>C-s</KBD> as appropriate. | |
a44161c3 EZ |
452 | This will search backward or forward in the history for the next |
453 | entry matching the search string typed so far. | |
454 | Any other key sequence bound to a Readline command will terminate | |
455 | the search and execute that command. | |
456 | For instance, a <KBD>RET</KBD> will terminate the search and accept | |
457 | the line, thereby executing the command from the history list. | |
458 | ||
459 | </P> | |
460 | <P> | |
461 | Non-incremental searches read the entire search string before starting | |
462 | to search for matching history lines. The search string may be | |
463 | typed by the user or be part of the contents of the current line. | |
464 | ||
465 | </P> | |
466 | ||
467 | ||
468 | <H2><A NAME="SEC9" HREF="readline.html#TOC9">Readline Init File</A></H2> | |
469 | <P> | |
470 | <A NAME="IDX8"></A> | |
471 | ||
472 | </P> | |
473 | <P> | |
f9267e15 | 474 | Although the Readline library comes with a set of Emacs-like |
a44161c3 EZ |
475 | keybindings installed by default, it is possible to use a different set |
476 | of keybindings. | |
477 | Any user can customize programs that use Readline by putting | |
f9267e15 | 478 | commands in an <EM>inputrc</EM> file, conventionally in his home directory. |
a44161c3 EZ |
479 | The name of this |
480 | file is taken from the value of the environment variable <CODE>INPUTRC</CODE>. If | |
481 | that variable is unset, the default is <TT>`~/.inputrc'</TT>. | |
482 | ||
483 | </P> | |
484 | <P> | |
485 | When a program which uses the Readline library starts up, the | |
486 | init file is read, and the key bindings are set. | |
487 | ||
488 | </P> | |
489 | <P> | |
490 | In addition, the <CODE>C-x C-r</CODE> command re-reads this init file, thus | |
491 | incorporating any changes that you might have made to it. | |
492 | ||
493 | </P> | |
494 | ||
495 | <UL> | |
496 | <LI><A HREF="readline.html#SEC10">Readline Init File Syntax</A>: Syntax for the commands in the inputrc file. | |
497 | ||
498 | <LI><A HREF="readline.html#SEC11">Conditional Init Constructs</A>: Conditional key bindings in the inputrc file. | |
499 | ||
500 | <LI><A HREF="readline.html#SEC12">Sample Init File</A>: An example inputrc file. | |
501 | </UL> | |
502 | ||
503 | ||
504 | ||
505 | <H3><A NAME="SEC10" HREF="readline.html#TOC10">Readline Init File Syntax</A></H3> | |
506 | ||
507 | <P> | |
508 | There are only a few basic constructs allowed in the | |
509 | Readline init file. Blank lines are ignored. | |
510 | Lines beginning with a <SAMP>`#'</SAMP> are comments. | |
511 | Lines beginning with a <SAMP>`$'</SAMP> indicate conditional | |
512 | constructs (see section <A HREF="readline.html#SEC11">Conditional Init Constructs</A>). Other lines | |
513 | denote variable settings and key bindings. | |
514 | ||
515 | </P> | |
516 | <DL COMPACT> | |
517 | ||
518 | <DT>Variable Settings | |
519 | <DD> | |
520 | You can modify the run-time behavior of Readline by | |
521 | altering the values of variables in Readline | |
522 | using the <CODE>set</CODE> command within the init file. Here is how to | |
523 | change from the default Emacs-like key binding to use | |
524 | <CODE>vi</CODE> line editing commands: | |
525 | ||
526 | ||
527 | <PRE> | |
528 | set editing-mode vi | |
529 | </PRE> | |
530 | ||
531 | A great deal of run-time behavior is changeable with the following | |
532 | variables. | |
533 | ||
534 | <DL COMPACT> | |
535 | ||
536 | <DT><CODE>bell-style</CODE> | |
537 | <DD> | |
538 | <A NAME="IDX9"></A> | |
539 | Controls what happens when Readline wants to ring the terminal bell. | |
540 | If set to <SAMP>`none'</SAMP>, Readline never rings the bell. If set to | |
541 | <SAMP>`visible'</SAMP>, Readline uses a visible bell if one is available. | |
542 | If set to <SAMP>`audible'</SAMP> (the default), Readline attempts to ring | |
543 | the terminal's bell. | |
544 | ||
545 | <DT><CODE>comment-begin</CODE> | |
546 | <DD> | |
547 | <A NAME="IDX10"></A> | |
548 | The string to insert at the beginning of the line when the | |
549 | <CODE>insert-comment</CODE> command is executed. The default value | |
550 | is <CODE>"#"</CODE>. | |
551 | ||
552 | <DT><CODE>completion-ignore-case</CODE> | |
553 | <DD> | |
554 | If set to <SAMP>`on'</SAMP>, Readline performs filename matching and completion | |
555 | in a case-insensitive fashion. | |
556 | The default value is <SAMP>`off'</SAMP>. | |
557 | ||
558 | <DT><CODE>completion-query-items</CODE> | |
559 | <DD> | |
560 | <A NAME="IDX11"></A> | |
561 | The number of possible completions that determines when the user is | |
562 | asked whether he wants to see the list of possibilities. If the | |
563 | number of possible completions is greater than this value, | |
564 | Readline will ask the user whether or not he wishes to view | |
565 | them; otherwise, they are simply listed. The default limit is | |
566 | <CODE>100</CODE>. | |
567 | ||
568 | <DT><CODE>convert-meta</CODE> | |
569 | <DD> | |
570 | <A NAME="IDX12"></A> | |
571 | If set to <SAMP>`on'</SAMP>, Readline will convert characters with the | |
572 | eighth bit set to an ASCII key sequence by stripping the eighth | |
f9267e15 | 573 | bit and prefixing an <KBD>ESC</KBD> character, converting them to a |
a44161c3 EZ |
574 | meta-prefixed key sequence. The default value is <SAMP>`on'</SAMP>. |
575 | ||
576 | <DT><CODE>disable-completion</CODE> | |
577 | <DD> | |
578 | <A NAME="IDX13"></A> | |
579 | If set to <SAMP>`On'</SAMP>, Readline will inhibit word completion. | |
580 | Completion characters will be inserted into the line as if they had | |
581 | been mapped to <CODE>self-insert</CODE>. The default is <SAMP>`off'</SAMP>. | |
582 | ||
583 | <DT><CODE>editing-mode</CODE> | |
584 | <DD> | |
585 | <A NAME="IDX14"></A> | |
586 | The <CODE>editing-mode</CODE> variable controls which default set of | |
587 | key bindings is used. By default, Readline starts up in Emacs editing | |
588 | mode, where the keystrokes are most similar to Emacs. This variable can be | |
589 | set to either <SAMP>`emacs'</SAMP> or <SAMP>`vi'</SAMP>. | |
590 | ||
591 | <DT><CODE>enable-keypad</CODE> | |
592 | <DD> | |
593 | <A NAME="IDX15"></A> | |
594 | When set to <SAMP>`on'</SAMP>, Readline will try to enable the application | |
595 | keypad when it is called. Some systems need this to enable the | |
596 | arrow keys. The default is <SAMP>`off'</SAMP>. | |
597 | ||
598 | <DT><CODE>expand-tilde</CODE> | |
599 | <DD> | |
600 | <A NAME="IDX16"></A> | |
601 | If set to <SAMP>`on'</SAMP>, tilde expansion is performed when Readline | |
602 | attempts word completion. The default is <SAMP>`off'</SAMP>. | |
603 | ||
604 | <DT><CODE>horizontal-scroll-mode</CODE> | |
605 | <DD> | |
606 | <A NAME="IDX17"></A> | |
607 | This variable can be set to either <SAMP>`on'</SAMP> or <SAMP>`off'</SAMP>. Setting it | |
608 | to <SAMP>`on'</SAMP> means that the text of the lines being edited will scroll | |
609 | horizontally on a single screen line when they are longer than the width | |
610 | of the screen, instead of wrapping onto a new screen line. By default, | |
611 | this variable is set to <SAMP>`off'</SAMP>. | |
612 | ||
613 | <DT><CODE>input-meta</CODE> | |
614 | <DD> | |
615 | <A NAME="IDX18"></A> | |
616 | <A NAME="IDX19"></A> | |
617 | If set to <SAMP>`on'</SAMP>, Readline will enable eight-bit input (it | |
618 | will not strip the eighth bit from the characters it reads), | |
619 | regardless of what the terminal claims it can support. The | |
620 | default value is <SAMP>`off'</SAMP>. The name <CODE>meta-flag</CODE> is a | |
621 | synonym for this variable. | |
622 | ||
623 | <DT><CODE>isearch-terminators</CODE> | |
624 | <DD> | |
625 | <A NAME="IDX20"></A> | |
626 | The string of characters that should terminate an incremental search without | |
627 | subsequently executing the character as a command (see section <A HREF="readline.html#SEC8">Searching for Commands in the History</A>). | |
628 | If this variable has not been given a value, the characters <KBD>ESC</KBD> and | |
629 | <KBD>C-J</KBD> will terminate an incremental search. | |
630 | ||
631 | <DT><CODE>keymap</CODE> | |
632 | <DD> | |
633 | <A NAME="IDX21"></A> | |
634 | Sets Readline's idea of the current keymap for key binding commands. | |
635 | Acceptable <CODE>keymap</CODE> names are | |
636 | <CODE>emacs</CODE>, | |
637 | <CODE>emacs-standard</CODE>, | |
638 | <CODE>emacs-meta</CODE>, | |
639 | <CODE>emacs-ctlx</CODE>, | |
640 | <CODE>vi</CODE>, | |
641 | <CODE>vi-command</CODE>, and | |
642 | <CODE>vi-insert</CODE>. | |
643 | <CODE>vi</CODE> is equivalent to <CODE>vi-command</CODE>; <CODE>emacs</CODE> is | |
644 | equivalent to <CODE>emacs-standard</CODE>. The default value is <CODE>emacs</CODE>. | |
645 | The value of the <CODE>editing-mode</CODE> variable also affects the | |
646 | default keymap. | |
647 | ||
648 | <DT><CODE>mark-directories</CODE> | |
649 | <DD> | |
650 | If set to <SAMP>`on'</SAMP>, completed directory names have a slash | |
651 | appended. The default is <SAMP>`on'</SAMP>. | |
652 | ||
653 | <DT><CODE>mark-modified-lines</CODE> | |
654 | <DD> | |
655 | <A NAME="IDX22"></A> | |
656 | This variable, when set to <SAMP>`on'</SAMP>, causes Readline to display an | |
657 | asterisk (<SAMP>`*'</SAMP>) at the start of history lines which have been modified. | |
658 | This variable is <SAMP>`off'</SAMP> by default. | |
659 | ||
660 | <DT><CODE>output-meta</CODE> | |
661 | <DD> | |
662 | <A NAME="IDX23"></A> | |
663 | If set to <SAMP>`on'</SAMP>, Readline will display characters with the | |
664 | eighth bit set directly rather than as a meta-prefixed escape | |
665 | sequence. The default is <SAMP>`off'</SAMP>. | |
666 | ||
667 | <DT><CODE>print-completions-horizontally</CODE> | |
668 | <DD> | |
669 | If set to <SAMP>`on'</SAMP>, Readline will display completions with matches | |
670 | sorted horizontally in alphabetical order, rather than down the screen. | |
671 | The default is <SAMP>`off'</SAMP>. | |
672 | ||
673 | <DT><CODE>show-all-if-ambiguous</CODE> | |
674 | <DD> | |
675 | <A NAME="IDX24"></A> | |
676 | This alters the default behavior of the completion functions. If | |
677 | set to <SAMP>`on'</SAMP>, | |
678 | words which have more than one possible completion cause the | |
679 | matches to be listed immediately instead of ringing the bell. | |
680 | The default value is <SAMP>`off'</SAMP>. | |
681 | ||
682 | <DT><CODE>visible-stats</CODE> | |
683 | <DD> | |
684 | <A NAME="IDX25"></A> | |
685 | If set to <SAMP>`on'</SAMP>, a character denoting a file's type | |
686 | is appended to the filename when listing possible | |
687 | completions. The default is <SAMP>`off'</SAMP>. | |
688 | ||
689 | </DL> | |
690 | ||
691 | <DT>Key Bindings | |
692 | <DD> | |
693 | The syntax for controlling key bindings in the init file is | |
f9267e15 | 694 | simple. First you need to find the name of the command that you |
a44161c3 EZ |
695 | want to change. The following sections contain tables of the command |
696 | name, the default keybinding, if any, and a short description of what | |
697 | the command does. | |
698 | ||
699 | Once you know the name of the command, simply place the name of the key | |
700 | you wish to bind the command to, a colon, and then the name of the | |
701 | command on a line in the init file. The name of the key | |
702 | can be expressed in different ways, depending on which is most | |
703 | comfortable for you. | |
704 | ||
705 | <DL COMPACT> | |
706 | ||
707 | <DT><VAR>keyname</VAR>: <VAR>function-name</VAR> or <VAR>macro</VAR> | |
708 | <DD> | |
709 | <VAR>keyname</VAR> is the name of a key spelled out in English. For example: | |
710 | ||
711 | <PRE> | |
712 | Control-u: universal-argument | |
713 | Meta-Rubout: backward-kill-word | |
714 | Control-o: "> output" | |
715 | </PRE> | |
716 | ||
717 | In the above example, <KBD>C-u</KBD> is bound to the function | |
718 | <CODE>universal-argument</CODE>, and <KBD>C-o</KBD> is bound to run the macro | |
719 | expressed on the right hand side (that is, to insert the text | |
720 | <SAMP>`> output'</SAMP> into the line). | |
721 | ||
722 | <DT>"<VAR>keyseq</VAR>": <VAR>function-name</VAR> or <VAR>macro</VAR> | |
723 | <DD> | |
724 | <VAR>keyseq</VAR> differs from <VAR>keyname</VAR> above in that strings | |
725 | denoting an entire key sequence can be specified, by placing | |
726 | the key sequence in double quotes. Some GNU Emacs style key | |
727 | escapes can be used, as in the following example, but the | |
728 | special character names are not recognized. | |
729 | ||
730 | ||
731 | <PRE> | |
732 | "\C-u": universal-argument | |
733 | "\C-x\C-r": re-read-init-file | |
734 | "\e[11~": "Function Key 1" | |
735 | </PRE> | |
736 | ||
737 | In the above example, <KBD>C-u</KBD> is bound to the function | |
738 | <CODE>universal-argument</CODE> (just as it was in the first example), | |
739 | <SAMP>`<KBD>C-x</KBD> <KBD>C-r</KBD>'</SAMP> is bound to the function <CODE>re-read-init-file</CODE>, | |
740 | and <SAMP>`<KBD>ESC</KBD> <KBD>[</KBD> <KBD>1</KBD> <KBD>1</KBD> <KBD>~</KBD>'</SAMP> is bound to insert | |
741 | the text <SAMP>`Function Key 1'</SAMP>. | |
742 | ||
743 | </DL> | |
744 | ||
745 | The following GNU Emacs style escape sequences are available when | |
746 | specifying key sequences: | |
747 | ||
748 | <DL COMPACT> | |
749 | ||
750 | <DT><CODE><KBD>\C-</KBD></CODE> | |
751 | <DD> | |
752 | control prefix | |
753 | <DT><CODE><KBD>\M-</KBD></CODE> | |
754 | <DD> | |
755 | meta prefix | |
756 | <DT><CODE><KBD>\e</KBD></CODE> | |
757 | <DD> | |
758 | an escape character | |
759 | <DT><CODE><KBD>\\</KBD></CODE> | |
760 | <DD> | |
761 | backslash | |
762 | <DT><CODE><KBD>\"</KBD></CODE> | |
763 | <DD> | |
f9267e15 | 764 | <KBD>"</KBD>, a double quotation mark |
a44161c3 EZ |
765 | <DT><CODE><KBD>\'</KBD></CODE> |
766 | <DD> | |
f9267e15 | 767 | <KBD>'</KBD>, a single quote or apostrophe |
a44161c3 EZ |
768 | </DL> |
769 | ||
770 | In addition to the GNU Emacs style escape sequences, a second | |
771 | set of backslash escapes is available: | |
772 | ||
773 | <DL COMPACT> | |
774 | ||
775 | <DT><CODE>\a</CODE> | |
776 | <DD> | |
777 | alert (bell) | |
778 | <DT><CODE>\b</CODE> | |
779 | <DD> | |
780 | backspace | |
781 | <DT><CODE>\d</CODE> | |
782 | <DD> | |
783 | delete | |
784 | <DT><CODE>\f</CODE> | |
785 | <DD> | |
786 | form feed | |
787 | <DT><CODE>\n</CODE> | |
788 | <DD> | |
789 | newline | |
790 | <DT><CODE>\r</CODE> | |
791 | <DD> | |
792 | carriage return | |
793 | <DT><CODE>\t</CODE> | |
794 | <DD> | |
795 | horizontal tab | |
796 | <DT><CODE>\v</CODE> | |
797 | <DD> | |
798 | vertical tab | |
799 | <DT><CODE>\<VAR>nnn</VAR></CODE> | |
800 | <DD> | |
f9267e15 | 801 | the character whose <CODE>ASCII</CODE> code is the octal value <VAR>nnn</VAR> |
a44161c3 EZ |
802 | (one to three digits) |
803 | <DT><CODE>\x<VAR>nnn</VAR></CODE> | |
804 | <DD> | |
f9267e15 | 805 | the character whose <CODE>ASCII</CODE> code is the hexadecimal value <VAR>nnn</VAR> |
a44161c3 EZ |
806 | (one to three digits) |
807 | </DL> | |
808 | ||
809 | When entering the text of a macro, single or double quotes must | |
810 | be used to indicate a macro definition. | |
811 | Unquoted text is assumed to be a function name. | |
812 | In the macro body, the backslash escapes described above are expanded. | |
813 | Backslash will quote any other character in the macro text, | |
814 | including <SAMP>`"'</SAMP> and <SAMP>`''</SAMP>. | |
815 | For example, the following binding will make <SAMP>`C-x \'</SAMP> | |
816 | insert a single <SAMP>`\'</SAMP> into the line: | |
817 | ||
818 | <PRE> | |
819 | "\C-x\\": "\\" | |
820 | </PRE> | |
821 | ||
822 | </DL> | |
823 | ||
824 | ||
825 | ||
826 | <H3><A NAME="SEC11" HREF="readline.html#TOC11">Conditional Init Constructs</A></H3> | |
827 | ||
828 | <P> | |
829 | Readline implements a facility similar in spirit to the conditional | |
830 | compilation features of the C preprocessor which allows key | |
831 | bindings and variable settings to be performed as the result | |
832 | of tests. There are four parser directives used. | |
833 | ||
834 | </P> | |
835 | <DL COMPACT> | |
836 | ||
837 | <DT><CODE>$if</CODE> | |
838 | <DD> | |
839 | The <CODE>$if</CODE> construct allows bindings to be made based on the | |
840 | editing mode, the terminal being used, or the application using | |
841 | Readline. The text of the test extends to the end of the line; | |
842 | no characters are required to isolate it. | |
843 | ||
844 | <DL COMPACT> | |
845 | ||
846 | <DT><CODE>mode</CODE> | |
847 | <DD> | |
848 | The <CODE>mode=</CODE> form of the <CODE>$if</CODE> directive is used to test | |
849 | whether Readline is in <CODE>emacs</CODE> or <CODE>vi</CODE> mode. | |
850 | This may be used in conjunction | |
851 | with the <SAMP>`set keymap'</SAMP> command, for instance, to set bindings in | |
852 | the <CODE>emacs-standard</CODE> and <CODE>emacs-ctlx</CODE> keymaps only if | |
853 | Readline is starting out in <CODE>emacs</CODE> mode. | |
854 | ||
855 | <DT><CODE>term</CODE> | |
856 | <DD> | |
857 | The <CODE>term=</CODE> form may be used to include terminal-specific | |
858 | key bindings, perhaps to bind the key sequences output by the | |
859 | terminal's function keys. The word on the right side of the | |
860 | <SAMP>`='</SAMP> is tested against both the full name of the terminal and | |
861 | the portion of the terminal name before the first <SAMP>`-'</SAMP>. This | |
862 | allows <CODE>sun</CODE> to match both <CODE>sun</CODE> and <CODE>sun-cmd</CODE>, | |
863 | for instance. | |
864 | ||
865 | <DT><CODE>application</CODE> | |
866 | <DD> | |
867 | The <VAR>application</VAR> construct is used to include | |
868 | application-specific settings. Each program using the Readline | |
869 | library sets the <VAR>application name</VAR>, and you can test for it. | |
870 | This could be used to bind key sequences to functions useful for | |
871 | a specific program. For instance, the following command adds a | |
872 | key sequence that quotes the current or previous word in Bash: | |
873 | ||
874 | <PRE> | |
875 | $if Bash | |
876 | # Quote the current or previous word | |
877 | "\C-xq": "\eb\"\ef\"" | |
878 | $endif | |
879 | </PRE> | |
880 | ||
881 | </DL> | |
882 | ||
883 | <DT><CODE>$endif</CODE> | |
884 | <DD> | |
885 | This command, as seen in the previous example, terminates an | |
886 | <CODE>$if</CODE> command. | |
887 | ||
888 | <DT><CODE>$else</CODE> | |
889 | <DD> | |
890 | Commands in this branch of the <CODE>$if</CODE> directive are executed if | |
891 | the test fails. | |
892 | ||
893 | <DT><CODE>$include</CODE> | |
894 | <DD> | |
895 | This directive takes a single filename as an argument and reads commands | |
896 | and bindings from that file. | |
897 | ||
898 | <PRE> | |
899 | $include /etc/inputrc | |
900 | </PRE> | |
901 | ||
902 | </DL> | |
903 | ||
904 | ||
905 | ||
906 | <H3><A NAME="SEC12" HREF="readline.html#TOC12">Sample Init File</A></H3> | |
907 | ||
908 | <P> | |
909 | Here is an example of an inputrc file. This illustrates key | |
910 | binding, variable assignment, and conditional syntax. | |
911 | ||
912 | </P> | |
913 | ||
914 | <PRE> | |
915 | # This file controls the behaviour of line input editing for | |
916 | # programs that use the Gnu Readline library. Existing programs | |
917 | # include FTP, Bash, and Gdb. | |
918 | # | |
919 | # You can re-read the inputrc file with C-x C-r. | |
920 | # Lines beginning with '#' are comments. | |
921 | # | |
922 | # First, include any systemwide bindings and variable assignments from | |
923 | # /etc/Inputrc | |
924 | $include /etc/Inputrc | |
925 | ||
926 | # | |
927 | # Set various bindings for emacs mode. | |
928 | ||
929 | set editing-mode emacs | |
930 | ||
931 | $if mode=emacs | |
932 | ||
933 | Meta-Control-h: backward-kill-word Text after the function name is ignored | |
934 | ||
935 | # | |
936 | # Arrow keys in keypad mode | |
937 | # | |
938 | #"\M-OD": backward-char | |
939 | #"\M-OC": forward-char | |
940 | #"\M-OA": previous-history | |
941 | #"\M-OB": next-history | |
942 | # | |
943 | # Arrow keys in ANSI mode | |
944 | # | |
945 | "\M-[D": backward-char | |
946 | "\M-[C": forward-char | |
947 | "\M-[A": previous-history | |
948 | "\M-[B": next-history | |
949 | # | |
950 | # Arrow keys in 8 bit keypad mode | |
951 | # | |
952 | #"\M-\C-OD": backward-char | |
953 | #"\M-\C-OC": forward-char | |
954 | #"\M-\C-OA": previous-history | |
955 | #"\M-\C-OB": next-history | |
956 | # | |
957 | # Arrow keys in 8 bit ANSI mode | |
958 | # | |
959 | #"\M-\C-[D": backward-char | |
960 | #"\M-\C-[C": forward-char | |
961 | #"\M-\C-[A": previous-history | |
962 | #"\M-\C-[B": next-history | |
963 | ||
964 | C-q: quoted-insert | |
965 | ||
966 | $endif | |
967 | ||
968 | # An old-style binding. This happens to be the default. | |
969 | TAB: complete | |
970 | ||
971 | # Macros that are convenient for shell interaction | |
972 | $if Bash | |
973 | # edit the path | |
974 | "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" | |
975 | # prepare to type a quoted word -- insert open and close double quotes | |
976 | # and move to just after the open quote | |
977 | "\C-x\"": "\"\"\C-b" | |
978 | # insert a backslash (testing backslash escapes in sequences and macros) | |
979 | "\C-x\\": "\\" | |
980 | # Quote the current or previous word | |
981 | "\C-xq": "\eb\"\ef\"" | |
982 | # Add a binding to refresh the line, which is unbound | |
983 | "\C-xr": redraw-current-line | |
984 | # Edit variable on current line. | |
985 | "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" | |
986 | $endif | |
987 | ||
988 | # use a visible bell if one is available | |
989 | set bell-style visible | |
990 | ||
991 | # don't strip characters to 7 bits when reading | |
992 | set input-meta on | |
993 | ||
994 | # allow iso-latin1 characters to be inserted rather than converted to | |
995 | # prefix-meta sequences | |
996 | set convert-meta off | |
997 | ||
998 | # display characters with the eighth bit set directly rather than | |
999 | # as meta-prefixed characters | |
1000 | set output-meta on | |
1001 | ||
1002 | # if there are more than 150 possible completions for a word, ask the | |
1003 | # user if he wants to see all of them | |
1004 | set completion-query-items 150 | |
1005 | ||
1006 | # For FTP | |
1007 | $if Ftp | |
1008 | "\C-xg": "get \M-?" | |
1009 | "\C-xt": "put \M-?" | |
1010 | "\M-.": yank-last-arg | |
1011 | $endif | |
1012 | </PRE> | |
1013 | ||
1014 | ||
1015 | ||
1016 | <H2><A NAME="SEC13" HREF="readline.html#TOC13">Bindable Readline Commands</A></H2> | |
1017 | ||
1018 | ||
1019 | <UL> | |
1020 | <LI><A HREF="readline.html#SEC14">Commands For Moving</A>: Moving about the line. | |
1021 | <LI><A HREF="readline.html#SEC15">Commands For History</A>: Getting at previous lines. | |
1022 | <LI><A HREF="readline.html#SEC16">Commands For Text</A>: Commands for changing text. | |
1023 | <LI><A HREF="readline.html#SEC17">Commands For Killing</A>: Commands for killing and yanking. | |
1024 | <LI><A HREF="readline.html#SEC18">Numeric Arguments</A>: Specifying numeric arguments, repeat counts. | |
1025 | <LI><A HREF="readline.html#SEC19">Commands For Completion</A>: Getting Readline to do the typing for you. | |
1026 | <LI><A HREF="readline.html#SEC20">Keyboard Macros</A>: Saving and re-executing typed characters | |
1027 | <LI><A HREF="readline.html#SEC21">Miscellaneous Commands</A>: Other miscellaneous commands. | |
1028 | </UL> | |
1029 | ||
1030 | <P> | |
1031 | This section describes Readline commands that may be bound to key | |
1032 | sequences. | |
1033 | ||
f9267e15 EZ |
1034 | </P> |
1035 | <P> | |
1036 | Command names without an accompanying key sequence are unbound by default. | |
1037 | In the following descriptions, <VAR>point</VAR> refers to the current cursor | |
1038 | position, and <VAR>mark</VAR> refers to a cursor position saved by the | |
1039 | <CODE>set-mark</CODE> command. | |
1040 | The text between the point and mark is referred to as the <VAR>region</VAR>. | |
1041 | ||
a44161c3 EZ |
1042 | </P> |
1043 | ||
1044 | ||
1045 | <H3><A NAME="SEC14" HREF="readline.html#TOC14">Commands For Moving</A></H3> | |
1046 | <DL COMPACT> | |
1047 | ||
1048 | <DT><CODE>beginning-of-line (C-a)</CODE> | |
1049 | <DD> | |
1050 | <A NAME="IDX26"></A> | |
1051 | Move to the start of the current line. | |
1052 | ||
1053 | <DT><CODE>end-of-line (C-e)</CODE> | |
1054 | <DD> | |
1055 | <A NAME="IDX27"></A> | |
1056 | Move to the end of the line. | |
1057 | ||
1058 | <DT><CODE>forward-char (C-f)</CODE> | |
1059 | <DD> | |
1060 | <A NAME="IDX28"></A> | |
1061 | Move forward a character. | |
1062 | ||
1063 | <DT><CODE>backward-char (C-b)</CODE> | |
1064 | <DD> | |
1065 | <A NAME="IDX29"></A> | |
1066 | Move back a character. | |
1067 | ||
1068 | <DT><CODE>forward-word (M-f)</CODE> | |
1069 | <DD> | |
1070 | <A NAME="IDX30"></A> | |
1071 | Move forward to the end of the next word. Words are composed of | |
1072 | letters and digits. | |
1073 | ||
1074 | <DT><CODE>backward-word (M-b)</CODE> | |
1075 | <DD> | |
1076 | <A NAME="IDX31"></A> | |
f9267e15 | 1077 | Move back to the start of the current or previous word. Words are |
a44161c3 EZ |
1078 | composed of letters and digits. |
1079 | ||
1080 | <DT><CODE>clear-screen (C-l)</CODE> | |
1081 | <DD> | |
1082 | <A NAME="IDX32"></A> | |
1083 | Clear the screen and redraw the current line, | |
1084 | leaving the current line at the top of the screen. | |
1085 | ||
1086 | <DT><CODE>redraw-current-line ()</CODE> | |
1087 | <DD> | |
1088 | <A NAME="IDX33"></A> | |
1089 | Refresh the current line. By default, this is unbound. | |
1090 | ||
1091 | </DL> | |
1092 | ||
1093 | ||
1094 | ||
1095 | <H3><A NAME="SEC15" HREF="readline.html#TOC15">Commands For Manipulating The History</A></H3> | |
1096 | ||
1097 | <DL COMPACT> | |
1098 | ||
1099 | <DT><CODE>accept-line (Newline, Return)</CODE> | |
1100 | <DD> | |
1101 | <A NAME="IDX34"></A> | |
1102 | Accept the line regardless of where the cursor is. If this line is | |
1103 | non-empty, add it to the history list. If this line was a history | |
1104 | line, then restore the history line to its original state. | |
1105 | ||
1106 | <DT><CODE>previous-history (C-p)</CODE> | |
1107 | <DD> | |
1108 | <A NAME="IDX35"></A> | |
1109 | Move `up' through the history list. | |
1110 | ||
1111 | <DT><CODE>next-history (C-n)</CODE> | |
1112 | <DD> | |
1113 | <A NAME="IDX36"></A> | |
1114 | Move `down' through the history list. | |
1115 | ||
1116 | <DT><CODE>beginning-of-history (M-<)</CODE> | |
1117 | <DD> | |
1118 | <A NAME="IDX37"></A> | |
1119 | Move to the first line in the history. | |
1120 | ||
1121 | <DT><CODE>end-of-history (M->)</CODE> | |
1122 | <DD> | |
1123 | <A NAME="IDX38"></A> | |
1124 | Move to the end of the input history, i.e., the line currently | |
1125 | being entered. | |
1126 | ||
1127 | <DT><CODE>reverse-search-history (C-r)</CODE> | |
1128 | <DD> | |
1129 | <A NAME="IDX39"></A> | |
1130 | Search backward starting at the current line and moving `up' through | |
1131 | the history as necessary. This is an incremental search. | |
1132 | ||
1133 | <DT><CODE>forward-search-history (C-s)</CODE> | |
1134 | <DD> | |
1135 | <A NAME="IDX40"></A> | |
1136 | Search forward starting at the current line and moving `down' through | |
1137 | the the history as necessary. This is an incremental search. | |
1138 | ||
1139 | <DT><CODE>non-incremental-reverse-search-history (M-p)</CODE> | |
1140 | <DD> | |
1141 | <A NAME="IDX41"></A> | |
1142 | Search backward starting at the current line and moving `up' | |
1143 | through the history as necessary using a non-incremental search | |
1144 | for a string supplied by the user. | |
1145 | ||
1146 | <DT><CODE>non-incremental-forward-search-history (M-n)</CODE> | |
1147 | <DD> | |
1148 | <A NAME="IDX42"></A> | |
1149 | Search forward starting at the current line and moving `down' | |
1150 | through the the history as necessary using a non-incremental search | |
1151 | for a string supplied by the user. | |
1152 | ||
1153 | <DT><CODE>history-search-forward ()</CODE> | |
1154 | <DD> | |
1155 | <A NAME="IDX43"></A> | |
1156 | Search forward through the history for the string of characters | |
f9267e15 EZ |
1157 | between the start of the current line and the point. |
1158 | This is a non-incremental search. | |
1159 | By default, this command is unbound. | |
a44161c3 EZ |
1160 | |
1161 | <DT><CODE>history-search-backward ()</CODE> | |
1162 | <DD> | |
1163 | <A NAME="IDX44"></A> | |
1164 | Search backward through the history for the string of characters | |
1165 | between the start of the current line and the point. This | |
1166 | is a non-incremental search. By default, this command is unbound. | |
1167 | ||
1168 | <DT><CODE>yank-nth-arg (M-C-y)</CODE> | |
1169 | <DD> | |
1170 | <A NAME="IDX45"></A> | |
1171 | Insert the first argument to the previous command (usually | |
1172 | the second word on the previous line). With an argument <VAR>n</VAR>, | |
1173 | insert the <VAR>n</VAR>th word from the previous command (the words | |
1174 | in the previous command begin with word 0). A negative argument | |
1175 | inserts the <VAR>n</VAR>th word from the end of the previous command. | |
1176 | ||
1177 | <DT><CODE>yank-last-arg (M-., M-_)</CODE> | |
1178 | <DD> | |
1179 | <A NAME="IDX46"></A> | |
1180 | Insert last argument to the previous command (the last word of the | |
1181 | previous history entry). With an | |
1182 | argument, behave exactly like <CODE>yank-nth-arg</CODE>. | |
1183 | Successive calls to <CODE>yank-last-arg</CODE> move back through the history | |
1184 | list, inserting the last argument of each line in turn. | |
1185 | ||
1186 | </DL> | |
1187 | ||
1188 | ||
1189 | ||
1190 | <H3><A NAME="SEC16" HREF="readline.html#TOC16">Commands For Changing Text</A></H3> | |
1191 | ||
1192 | <DL COMPACT> | |
1193 | ||
1194 | <DT><CODE>delete-char (C-d)</CODE> | |
1195 | <DD> | |
1196 | <A NAME="IDX47"></A> | |
1197 | Delete the character under the cursor. If the cursor is at the | |
1198 | beginning of the line, there are no characters in the line, and | |
1199 | the last character typed was not bound to <CODE>delete-char</CODE>, then | |
1200 | return <CODE>EOF</CODE>. | |
1201 | ||
1202 | <DT><CODE>backward-delete-char (Rubout)</CODE> | |
1203 | <DD> | |
1204 | <A NAME="IDX48"></A> | |
1205 | Delete the character behind the cursor. A numeric argument means | |
1206 | to kill the characters instead of deleting them. | |
1207 | ||
1208 | <DT><CODE>forward-backward-delete-char ()</CODE> | |
1209 | <DD> | |
1210 | <A NAME="IDX49"></A> | |
1211 | Delete the character under the cursor, unless the cursor is at the | |
1212 | end of the line, in which case the character behind the cursor is | |
1213 | deleted. By default, this is not bound to a key. | |
1214 | ||
1215 | <DT><CODE>quoted-insert (C-q, C-v)</CODE> | |
1216 | <DD> | |
1217 | <A NAME="IDX50"></A> | |
1218 | Add the next character typed to the line verbatim. This is | |
1219 | how to insert key sequences like <KBD>C-q</KBD>, for example. | |
1220 | ||
1221 | <DT><CODE>tab-insert (M-TAB)</CODE> | |
1222 | <DD> | |
1223 | <A NAME="IDX51"></A> | |
1224 | Insert a tab character. | |
1225 | ||
1226 | <DT><CODE>self-insert (a, b, A, 1, !, ...)</CODE> | |
1227 | <DD> | |
1228 | <A NAME="IDX52"></A> | |
1229 | Insert yourself. | |
1230 | ||
1231 | <DT><CODE>transpose-chars (C-t)</CODE> | |
1232 | <DD> | |
1233 | <A NAME="IDX53"></A> | |
1234 | Drag the character before the cursor forward over | |
1235 | the character at the cursor, moving the | |
1236 | cursor forward as well. If the insertion point | |
1237 | is at the end of the line, then this | |
1238 | transposes the last two characters of the line. | |
f9267e15 | 1239 | Negative arguments have no effect. |
a44161c3 EZ |
1240 | |
1241 | <DT><CODE>transpose-words (M-t)</CODE> | |
1242 | <DD> | |
1243 | <A NAME="IDX54"></A> | |
f9267e15 EZ |
1244 | Drag the word before point past the word after point, |
1245 | moving point past that word as well. | |
a44161c3 EZ |
1246 | |
1247 | <DT><CODE>upcase-word (M-u)</CODE> | |
1248 | <DD> | |
1249 | <A NAME="IDX55"></A> | |
1250 | Uppercase the current (or following) word. With a negative argument, | |
1251 | uppercase the previous word, but do not move the cursor. | |
1252 | ||
1253 | <DT><CODE>downcase-word (M-l)</CODE> | |
1254 | <DD> | |
1255 | <A NAME="IDX56"></A> | |
1256 | Lowercase the current (or following) word. With a negative argument, | |
1257 | lowercase the previous word, but do not move the cursor. | |
1258 | ||
1259 | <DT><CODE>capitalize-word (M-c)</CODE> | |
1260 | <DD> | |
1261 | <A NAME="IDX57"></A> | |
1262 | Capitalize the current (or following) word. With a negative argument, | |
1263 | capitalize the previous word, but do not move the cursor. | |
1264 | ||
1265 | </DL> | |
1266 | ||
1267 | ||
1268 | ||
1269 | <H3><A NAME="SEC17" HREF="readline.html#TOC17">Killing And Yanking</A></H3> | |
1270 | ||
1271 | <DL COMPACT> | |
1272 | ||
1273 | <DT><CODE>kill-line (C-k)</CODE> | |
1274 | <DD> | |
1275 | <A NAME="IDX58"></A> | |
f9267e15 | 1276 | Kill the text from point to the end of the line. |
a44161c3 EZ |
1277 | |
1278 | <DT><CODE>backward-kill-line (C-x Rubout)</CODE> | |
1279 | <DD> | |
1280 | <A NAME="IDX59"></A> | |
1281 | Kill backward to the beginning of the line. | |
1282 | ||
1283 | <DT><CODE>unix-line-discard (C-u)</CODE> | |
1284 | <DD> | |
1285 | <A NAME="IDX60"></A> | |
1286 | Kill backward from the cursor to the beginning of the current line. | |
a44161c3 EZ |
1287 | |
1288 | <DT><CODE>kill-whole-line ()</CODE> | |
1289 | <DD> | |
1290 | <A NAME="IDX61"></A> | |
f9267e15 EZ |
1291 | Kill all characters on the current line, no matter point is. |
1292 | By default, this is unbound. | |
a44161c3 EZ |
1293 | |
1294 | <DT><CODE>kill-word (M-d)</CODE> | |
1295 | <DD> | |
1296 | <A NAME="IDX62"></A> | |
f9267e15 EZ |
1297 | Kill from point to the end of the current word, or if between |
1298 | words, to the end of the next word. | |
1299 | Word boundaries are the same as <CODE>forward-word</CODE>. | |
a44161c3 EZ |
1300 | |
1301 | <DT><CODE>backward-kill-word (M-DEL)</CODE> | |
1302 | <DD> | |
1303 | <A NAME="IDX63"></A> | |
f9267e15 EZ |
1304 | Kill the word behind point. |
1305 | Word boundaries are the same as <CODE>backward-word</CODE>. | |
a44161c3 EZ |
1306 | |
1307 | <DT><CODE>unix-word-rubout (C-w)</CODE> | |
1308 | <DD> | |
1309 | <A NAME="IDX64"></A> | |
f9267e15 EZ |
1310 | Kill the word behind point, using white space as a word boundary. |
1311 | The killed text is saved on the kill-ring. | |
a44161c3 EZ |
1312 | |
1313 | <DT><CODE>delete-horizontal-space ()</CODE> | |
1314 | <DD> | |
1315 | <A NAME="IDX65"></A> | |
1316 | Delete all spaces and tabs around point. By default, this is unbound. | |
1317 | ||
1318 | <DT><CODE>kill-region ()</CODE> | |
1319 | <DD> | |
1320 | <A NAME="IDX66"></A> | |
f9267e15 | 1321 | Kill the text in the current region. |
a44161c3 EZ |
1322 | By default, this command is unbound. |
1323 | ||
1324 | <DT><CODE>copy-region-as-kill ()</CODE> | |
1325 | <DD> | |
1326 | <A NAME="IDX67"></A> | |
1327 | Copy the text in the region to the kill buffer, so it can be yanked | |
1328 | right away. By default, this command is unbound. | |
1329 | ||
1330 | <DT><CODE>copy-backward-word ()</CODE> | |
1331 | <DD> | |
1332 | <A NAME="IDX68"></A> | |
1333 | Copy the word before point to the kill buffer. | |
1334 | The word boundaries are the same as <CODE>backward-word</CODE>. | |
1335 | By default, this command is unbound. | |
1336 | ||
1337 | <DT><CODE>copy-forward-word ()</CODE> | |
1338 | <DD> | |
1339 | <A NAME="IDX69"></A> | |
1340 | Copy the word following point to the kill buffer. | |
1341 | The word boundaries are the same as <CODE>forward-word</CODE>. | |
1342 | By default, this command is unbound. | |
1343 | ||
1344 | <DT><CODE>yank (C-y)</CODE> | |
1345 | <DD> | |
1346 | <A NAME="IDX70"></A> | |
1347 | Yank the top of the kill ring into the buffer at the current | |
1348 | cursor position. | |
1349 | ||
1350 | <DT><CODE>yank-pop (M-y)</CODE> | |
1351 | <DD> | |
1352 | <A NAME="IDX71"></A> | |
1353 | Rotate the kill-ring, and yank the new top. You can only do this if | |
1354 | the prior command is yank or yank-pop. | |
1355 | </DL> | |
1356 | ||
1357 | ||
1358 | ||
1359 | <H3><A NAME="SEC18" HREF="readline.html#TOC18">Specifying Numeric Arguments</A></H3> | |
1360 | <DL COMPACT> | |
1361 | ||
1362 | <DT><CODE>digit-argument (M-0, M-1, ... M--)</CODE> | |
1363 | <DD> | |
1364 | <A NAME="IDX72"></A> | |
1365 | Add this digit to the argument already accumulating, or start a new | |
1366 | argument. <KBD>M--</KBD> starts a negative argument. | |
1367 | ||
1368 | <DT><CODE>universal-argument ()</CODE> | |
1369 | <DD> | |
1370 | <A NAME="IDX73"></A> | |
1371 | This is another way to specify an argument. | |
1372 | If this command is followed by one or more digits, optionally with a | |
1373 | leading minus sign, those digits define the argument. | |
1374 | If the command is followed by digits, executing <CODE>universal-argument</CODE> | |
1375 | again ends the numeric argument, but is otherwise ignored. | |
1376 | As a special case, if this command is immediately followed by a | |
1377 | character that is neither a digit or minus sign, the argument count | |
1378 | for the next command is multiplied by four. | |
1379 | The argument count is initially one, so executing this function the | |
1380 | first time makes the argument count four, a second time makes the | |
1381 | argument count sixteen, and so on. | |
1382 | By default, this is not bound to a key. | |
1383 | </DL> | |
1384 | ||
1385 | ||
1386 | ||
1387 | <H3><A NAME="SEC19" HREF="readline.html#TOC19">Letting Readline Type For You</A></H3> | |
1388 | ||
1389 | <DL COMPACT> | |
1390 | ||
1391 | <DT><CODE>complete (TAB)</CODE> | |
1392 | <DD> | |
1393 | <A NAME="IDX74"></A> | |
1394 | Attempt to do completion on the text before the cursor. This is | |
1395 | application-specific. Generally, if you are typing a filename | |
1396 | argument, you can do filename completion; if you are typing a command, | |
1397 | you can do command completion; if you are typing in a symbol to GDB, you | |
1398 | can do symbol name completion; if you are typing in a variable to Bash, | |
1399 | you can do variable name completion, and so on. | |
1400 | ||
1401 | <DT><CODE>possible-completions (M-?)</CODE> | |
1402 | <DD> | |
1403 | <A NAME="IDX75"></A> | |
1404 | List the possible completions of the text before the cursor. | |
1405 | ||
1406 | <DT><CODE>insert-completions (M-*)</CODE> | |
1407 | <DD> | |
1408 | <A NAME="IDX76"></A> | |
1409 | Insert all completions of the text before point that would have | |
1410 | been generated by <CODE>possible-completions</CODE>. | |
1411 | ||
1412 | <DT><CODE>menu-complete ()</CODE> | |
1413 | <DD> | |
1414 | <A NAME="IDX77"></A> | |
1415 | Similar to <CODE>complete</CODE>, but replaces the word to be completed | |
1416 | with a single match from the list of possible completions. | |
1417 | Repeated execution of <CODE>menu-complete</CODE> steps through the list | |
1418 | of possible completions, inserting each match in turn. | |
1419 | At the end of the list of completions, the bell is rung and the | |
1420 | original text is restored. | |
1421 | An argument of <VAR>n</VAR> moves <VAR>n</VAR> positions forward in the list | |
1422 | of matches; a negative argument may be used to move backward | |
1423 | through the list. | |
1424 | This command is intended to be bound to <CODE>TAB</CODE>, but is unbound | |
1425 | by default. | |
1426 | ||
1427 | <DT><CODE>delete-char-or-list ()</CODE> | |
1428 | <DD> | |
1429 | <A NAME="IDX78"></A> | |
1430 | Deletes the character under the cursor if not at the beginning or | |
1431 | end of the line (like <CODE>delete-char</CODE>). | |
1432 | If at the end of the line, behaves identically to | |
1433 | <CODE>possible-completions</CODE>. | |
1434 | This command is unbound by default. | |
1435 | ||
1436 | </DL> | |
1437 | ||
1438 | ||
1439 | ||
1440 | <H3><A NAME="SEC20" HREF="readline.html#TOC20">Keyboard Macros</A></H3> | |
1441 | <DL COMPACT> | |
1442 | ||
1443 | <DT><CODE>start-kbd-macro (C-x ()</CODE> | |
1444 | <DD> | |
1445 | <A NAME="IDX79"></A> | |
1446 | Begin saving the characters typed into the current keyboard macro. | |
1447 | ||
1448 | <DT><CODE>end-kbd-macro (C-x ))</CODE> | |
1449 | <DD> | |
1450 | <A NAME="IDX80"></A> | |
1451 | Stop saving the characters typed into the current keyboard macro | |
1452 | and save the definition. | |
1453 | ||
1454 | <DT><CODE>call-last-kbd-macro (C-x e)</CODE> | |
1455 | <DD> | |
1456 | <A NAME="IDX81"></A> | |
1457 | Re-execute the last keyboard macro defined, by making the characters | |
1458 | in the macro appear as if typed at the keyboard. | |
1459 | ||
1460 | </DL> | |
1461 | ||
1462 | ||
1463 | ||
1464 | <H3><A NAME="SEC21" HREF="readline.html#TOC21">Some Miscellaneous Commands</A></H3> | |
1465 | <DL COMPACT> | |
1466 | ||
1467 | <DT><CODE>re-read-init-file (C-x C-r)</CODE> | |
1468 | <DD> | |
1469 | <A NAME="IDX82"></A> | |
f9267e15 | 1470 | Read in the contents of the <VAR>inputrc</VAR> file, and incorporate |
a44161c3 EZ |
1471 | any bindings or variable assignments found there. |
1472 | ||
1473 | <DT><CODE>abort (C-g)</CODE> | |
1474 | <DD> | |
1475 | <A NAME="IDX83"></A> | |
1476 | Abort the current editing command and | |
1477 | ring the terminal's bell (subject to the setting of | |
1478 | <CODE>bell-style</CODE>). | |
1479 | ||
1480 | <DT><CODE>do-uppercase-version (M-a, M-b, M-<VAR>x</VAR>, ...)</CODE> | |
1481 | <DD> | |
1482 | <A NAME="IDX84"></A> | |
1483 | If the metafied character <VAR>x</VAR> is lowercase, run the command | |
1484 | that is bound to the corresponding uppercase character. | |
1485 | ||
1486 | <DT><CODE>prefix-meta (ESC)</CODE> | |
1487 | <DD> | |
1488 | <A NAME="IDX85"></A> | |
1489 | Make the next character typed be metafied. This is for keyboards | |
1490 | without a meta key. Typing <SAMP>`ESC f'</SAMP> is equivalent to typing | |
1491 | <SAMP>`M-f'</SAMP>. | |
1492 | ||
1493 | <DT><CODE>undo (C-_, C-x C-u)</CODE> | |
1494 | <DD> | |
1495 | <A NAME="IDX86"></A> | |
1496 | Incremental undo, separately remembered for each line. | |
1497 | ||
1498 | <DT><CODE>revert-line (M-r)</CODE> | |
1499 | <DD> | |
1500 | <A NAME="IDX87"></A> | |
1501 | Undo all changes made to this line. This is like executing the <CODE>undo</CODE> | |
1502 | command enough times to get back to the beginning. | |
1503 | ||
1504 | <DT><CODE>tilde-expand (M-~)</CODE> | |
1505 | <DD> | |
1506 | <A NAME="IDX88"></A> | |
1507 | Perform tilde expansion on the current word. | |
1508 | ||
1509 | <DT><CODE>set-mark (C-@)</CODE> | |
1510 | <DD> | |
1511 | <A NAME="IDX89"></A> | |
1512 | Set the mark to the current point. If a | |
1513 | numeric argument is supplied, the mark is set to that position. | |
1514 | ||
1515 | <DT><CODE>exchange-point-and-mark (C-x C-x)</CODE> | |
1516 | <DD> | |
1517 | <A NAME="IDX90"></A> | |
1518 | Swap the point with the mark. The current cursor position is set to | |
1519 | the saved position, and the old cursor position is saved as the mark. | |
1520 | ||
1521 | <DT><CODE>character-search (C-])</CODE> | |
1522 | <DD> | |
1523 | <A NAME="IDX91"></A> | |
1524 | A character is read and point is moved to the next occurrence of that | |
1525 | character. A negative count searches for previous occurrences. | |
1526 | ||
1527 | <DT><CODE>character-search-backward (M-C-])</CODE> | |
1528 | <DD> | |
1529 | <A NAME="IDX92"></A> | |
1530 | A character is read and point is moved to the previous occurrence | |
1531 | of that character. A negative count searches for subsequent | |
1532 | occurrences. | |
1533 | ||
1534 | <DT><CODE>insert-comment (M-#)</CODE> | |
1535 | <DD> | |
1536 | <A NAME="IDX93"></A> | |
1537 | The value of the <CODE>comment-begin</CODE> | |
1538 | variable is inserted at the beginning of the current line, | |
1539 | and the line is accepted as if a newline had been typed. | |
1540 | ||
1541 | <DT><CODE>dump-functions ()</CODE> | |
1542 | <DD> | |
1543 | <A NAME="IDX94"></A> | |
1544 | Print all of the functions and their key bindings to the | |
1545 | Readline output stream. If a numeric argument is supplied, | |
1546 | the output is formatted in such a way that it can be made part | |
1547 | of an <VAR>inputrc</VAR> file. This command is unbound by default. | |
1548 | ||
1549 | <DT><CODE>dump-variables ()</CODE> | |
1550 | <DD> | |
1551 | <A NAME="IDX95"></A> | |
1552 | Print all of the settable variables and their values to the | |
1553 | Readline output stream. If a numeric argument is supplied, | |
1554 | the output is formatted in such a way that it can be made part | |
1555 | of an <VAR>inputrc</VAR> file. This command is unbound by default. | |
1556 | ||
1557 | <DT><CODE>dump-macros ()</CODE> | |
1558 | <DD> | |
1559 | <A NAME="IDX96"></A> | |
1560 | Print all of the Readline key sequences bound to macros and the | |
1561 | strings they ouput. If a numeric argument is supplied, | |
1562 | the output is formatted in such a way that it can be made part | |
1563 | of an <VAR>inputrc</VAR> file. This command is unbound by default. | |
1564 | ||
1565 | </DL> | |
1566 | ||
1567 | ||
1568 | ||
1569 | <H2><A NAME="SEC22" HREF="readline.html#TOC22">Readline vi Mode</A></H2> | |
1570 | ||
1571 | <P> | |
1572 | While the Readline library does not have a full set of <CODE>vi</CODE> | |
1573 | editing functions, it does contain enough to allow simple editing | |
1574 | of the line. The Readline <CODE>vi</CODE> mode behaves as specified in | |
1575 | the POSIX 1003.2 standard. | |
1576 | ||
1577 | </P> | |
1578 | <P> | |
1579 | In order to switch interactively between <CODE>emacs</CODE> and <CODE>vi</CODE> | |
1580 | editing modes, use the command M-C-j (toggle-editing-mode). | |
1581 | The Readline default is <CODE>emacs</CODE> mode. | |
1582 | ||
1583 | </P> | |
1584 | <P> | |
1585 | When you enter a line in <CODE>vi</CODE> mode, you are already placed in | |
1586 | `insertion' mode, as if you had typed an <SAMP>`i'</SAMP>. Pressing <KBD>ESC</KBD> | |
1587 | switches you into `command' mode, where you can edit the text of the | |
1588 | line with the standard <CODE>vi</CODE> movement keys, move to previous | |
1589 | history lines with <SAMP>`k'</SAMP> and subsequent lines with <SAMP>`j'</SAMP>, and | |
1590 | so forth. | |
1591 | ||
1592 | </P> | |
1593 | ||
1594 | ||
1595 | ||
1596 | <H1><A NAME="SEC23" HREF="readline.html#TOC23">Programming with GNU Readline</A></H1> | |
1597 | ||
1598 | <P> | |
1599 | This chapter describes the interface between the GNU Readline Library and | |
1600 | other programs. If you are a programmer, and you wish to include the | |
1601 | features found in GNU Readline | |
1602 | such as completion, line editing, and interactive history manipulation | |
1603 | in your own programs, this section is for you. | |
1604 | ||
1605 | </P> | |
1606 | ||
1607 | <UL> | |
1608 | <LI><A HREF="readline.html#SEC24">Basic Behavior</A>: Using the default behavior of Readline. | |
1609 | <LI><A HREF="readline.html#SEC25">Custom Functions</A>: Adding your own functions to Readline. | |
1610 | <LI><A HREF="readline.html#SEC28">Readline Variables</A>: Variables accessible to custom | |
1611 | functions. | |
1612 | <LI><A HREF="readline.html#SEC29">Readline Convenience Functions</A>: Functions which Readline supplies to | |
1613 | aid in writing your own custom | |
1614 | functions. | |
1615 | <LI><A HREF="readline.html#SEC40">Readline Signal Handling</A>: How Readline behaves when it receives signals. | |
1616 | <LI><A HREF="readline.html#SEC41">Custom Completers</A>: Supplanting or supplementing Readline's | |
1617 | completion functions. | |
1618 | </UL> | |
1619 | ||
1620 | ||
1621 | ||
1622 | <H2><A NAME="SEC24" HREF="readline.html#TOC24">Basic Behavior</A></H2> | |
1623 | ||
1624 | <P> | |
1625 | Many programs provide a command line interface, such as <CODE>mail</CODE>, | |
1626 | <CODE>ftp</CODE>, and <CODE>sh</CODE>. For such programs, the default behaviour of | |
1627 | Readline is sufficient. This section describes how to use Readline in | |
1628 | the simplest way possible, perhaps to replace calls in your code to | |
1629 | <CODE>gets()</CODE> or <CODE>fgets ()</CODE>. | |
1630 | ||
1631 | </P> | |
1632 | <P> | |
1633 | <A NAME="IDX97"></A> | |
1634 | <A NAME="IDX98"></A> | |
1635 | The function <CODE>readline ()</CODE> prints a prompt and then reads and returns | |
1636 | a single line of text from the user. The line <CODE>readline</CODE> | |
1637 | returns is allocated with <CODE>malloc ()</CODE>; you should <CODE>free ()</CODE> | |
1638 | the line when you are done with it. The declaration for <CODE>readline</CODE> | |
1639 | in ANSI C is | |
1640 | ||
1641 | </P> | |
1642 | ||
1643 | <PRE> | |
1644 | <CODE>char *readline (char *<VAR>prompt</VAR>);</CODE> | |
1645 | </PRE> | |
1646 | ||
1647 | <P> | |
1648 | So, one might say | |
1649 | ||
1650 | <PRE> | |
1651 | <CODE>char *line = readline ("Enter a line: ");</CODE> | |
1652 | </PRE> | |
1653 | ||
1654 | <P> | |
1655 | in order to read a line of text from the user. | |
1656 | The line returned has the final newline removed, so only the | |
1657 | text remains. | |
1658 | ||
1659 | </P> | |
1660 | <P> | |
1661 | If <CODE>readline</CODE> encounters an <CODE>EOF</CODE> while reading the line, and the | |
1662 | line is empty at that point, then <CODE>(char *)NULL</CODE> is returned. | |
1663 | Otherwise, the line is ended just as if a newline had been typed. | |
1664 | ||
1665 | </P> | |
1666 | <P> | |
1667 | If you want the user to be able to get at the line later, (with | |
1668 | <KBD>C-p</KBD> for example), you must call <CODE>add_history ()</CODE> to save the | |
1669 | line away in a <EM>history</EM> list of such lines. | |
1670 | ||
1671 | </P> | |
1672 | ||
1673 | <PRE> | |
1674 | <CODE>add_history (line)</CODE>; | |
1675 | </PRE> | |
1676 | ||
1677 | <P> | |
1678 | For full details on the GNU History Library, see the associated manual. | |
1679 | ||
1680 | </P> | |
1681 | <P> | |
1682 | It is preferable to avoid saving empty lines on the history list, since | |
1683 | users rarely have a burning need to reuse a blank line. Here is | |
1684 | a function which usefully replaces the standard <CODE>gets ()</CODE> library | |
1685 | function, and has the advantage of no static buffer to overflow: | |
1686 | ||
1687 | </P> | |
1688 | ||
1689 | <PRE> | |
1690 | /* A static variable for holding the line. */ | |
1691 | static char *line_read = (char *)NULL; | |
1692 | ||
1693 | /* Read a string, and return a pointer to it. Returns NULL on EOF. */ | |
1694 | char * | |
1695 | rl_gets () | |
1696 | { | |
1697 | /* If the buffer has already been allocated, return the memory | |
1698 | to the free pool. */ | |
1699 | if (line_read) | |
1700 | { | |
1701 | free (line_read); | |
1702 | line_read = (char *)NULL; | |
1703 | } | |
1704 | ||
1705 | /* Get a line from the user. */ | |
1706 | line_read = readline (""); | |
1707 | ||
1708 | /* If the line has any text in it, save it on the history. */ | |
1709 | if (line_read && *line_read) | |
1710 | add_history (line_read); | |
1711 | ||
1712 | return (line_read); | |
1713 | } | |
1714 | </PRE> | |
1715 | ||
1716 | <P> | |
1717 | This function gives the user the default behaviour of <KBD>TAB</KBD> | |
1718 | completion: completion on file names. If you do not want Readline to | |
1719 | complete on filenames, you can change the binding of the <KBD>TAB</KBD> key | |
1720 | with <CODE>rl_bind_key ()</CODE>. | |
1721 | ||
1722 | </P> | |
1723 | ||
1724 | <PRE> | |
1725 | <CODE>int rl_bind_key (int <VAR>key</VAR>, int (*<VAR>function</VAR>)());</CODE> | |
1726 | </PRE> | |
1727 | ||
1728 | <P> | |
1729 | <CODE>rl_bind_key ()</CODE> takes two arguments: <VAR>key</VAR> is the character that | |
1730 | you want to bind, and <VAR>function</VAR> is the address of the function to | |
1731 | call when <VAR>key</VAR> is pressed. Binding <KBD>TAB</KBD> to <CODE>rl_insert ()</CODE> | |
1732 | makes <KBD>TAB</KBD> insert itself. | |
1733 | <CODE>rl_bind_key ()</CODE> returns non-zero if <VAR>key</VAR> is not a valid | |
1734 | ASCII character code (between 0 and 255). | |
1735 | ||
1736 | </P> | |
1737 | <P> | |
1738 | Thus, to disable the default <KBD>TAB</KBD> behavior, the following suffices: | |
1739 | ||
1740 | <PRE> | |
1741 | <CODE>rl_bind_key ('\t', rl_insert);</CODE> | |
1742 | </PRE> | |
1743 | ||
1744 | <P> | |
1745 | This code should be executed once at the start of your program; you | |
1746 | might write a function called <CODE>initialize_readline ()</CODE> which | |
1747 | performs this and other desired initializations, such as installing | |
1748 | custom completers (see section <A HREF="readline.html#SEC41">Custom Completers</A>). | |
1749 | ||
1750 | </P> | |
1751 | ||
1752 | ||
1753 | <H2><A NAME="SEC25" HREF="readline.html#TOC25">Custom Functions</A></H2> | |
1754 | ||
1755 | <P> | |
1756 | Readline provides many functions for manipulating the text of | |
1757 | the line, but it isn't possible to anticipate the needs of all | |
1758 | programs. This section describes the various functions and variables | |
1759 | defined within the Readline library which allow a user program to add | |
1760 | customized functionality to Readline. | |
1761 | ||
f9267e15 EZ |
1762 | </P> |
1763 | <P> | |
1764 | Before declaring any functions that customize Readline's behavior, or | |
1765 | using any functionality Readline provides in other code, an | |
1766 | application writer should include the file <CODE><readline/readline.h></CODE> | |
1767 | in any file that uses Readline's features. Since some of the definitions | |
1768 | in <CODE>readline.h</CODE> use the <CODE>stdio</CODE> library, the file | |
1769 | <CODE><stdio.h></CODE> should be included before <CODE>readline.h</CODE>. | |
1770 | ||
a44161c3 EZ |
1771 | </P> |
1772 | ||
1773 | <UL> | |
1774 | <LI><A HREF="readline.html#SEC26">The Function Type</A>: C declarations to make code readable. | |
1775 | <LI><A HREF="readline.html#SEC27">Function Writing</A>: Variables and calling conventions. | |
1776 | </UL> | |
1777 | ||
1778 | ||
1779 | ||
1780 | <H3><A NAME="SEC26" HREF="readline.html#TOC26">The Function Type</A></H3> | |
1781 | ||
1782 | <P> | |
1783 | For readabilty, we declare a new type of object, called | |
1784 | <EM>Function</EM>. A <CODE>Function</CODE> is a C function which | |
1785 | returns an <CODE>int</CODE>. The type declaration for <CODE>Function</CODE> is: | |
1786 | ||
1787 | </P> | |
1788 | <P> | |
1789 | <CODE>typedef int Function ();</CODE> | |
1790 | ||
1791 | </P> | |
1792 | <P> | |
1793 | The reason for declaring this new type is to make it easier to write | |
1794 | code describing pointers to C functions. Let us say we had a variable | |
1795 | called <VAR>func</VAR> which was a pointer to a function. Instead of the | |
1796 | classic C declaration | |
1797 | ||
1798 | </P> | |
1799 | <P> | |
1800 | <CODE>int (*)()func;</CODE> | |
1801 | ||
1802 | </P> | |
1803 | <P> | |
1804 | we may write | |
1805 | ||
1806 | </P> | |
1807 | <P> | |
1808 | <CODE>Function *func;</CODE> | |
1809 | ||
1810 | </P> | |
1811 | <P> | |
1812 | Similarly, there are | |
1813 | ||
1814 | </P> | |
1815 | ||
1816 | <PRE> | |
1817 | typedef void VFunction (); | |
1818 | typedef char *CPFunction (); and | |
1819 | typedef char **CPPFunction (); | |
1820 | </PRE> | |
1821 | ||
1822 | <P> | |
1823 | for functions returning no value, <CODE>pointer to char</CODE>, and | |
1824 | <CODE>pointer to pointer to char</CODE>, respectively. | |
1825 | ||
1826 | </P> | |
1827 | ||
1828 | ||
1829 | <H3><A NAME="SEC27" HREF="readline.html#TOC27">Writing a New Function</A></H3> | |
1830 | ||
1831 | <P> | |
1832 | In order to write new functions for Readline, you need to know the | |
1833 | calling conventions for keyboard-invoked functions, and the names of the | |
1834 | variables that describe the current state of the line read so far. | |
1835 | ||
1836 | </P> | |
1837 | <P> | |
1838 | The calling sequence for a command <CODE>foo</CODE> looks like | |
1839 | ||
1840 | </P> | |
1841 | ||
1842 | <PRE> | |
1843 | <CODE>foo (int count, int key)</CODE> | |
1844 | </PRE> | |
1845 | ||
1846 | <P> | |
1847 | where <VAR>count</VAR> is the numeric argument (or 1 if defaulted) and | |
1848 | <VAR>key</VAR> is the key that invoked this function. | |
1849 | ||
1850 | </P> | |
1851 | <P> | |
1852 | It is completely up to the function as to what should be done with the | |
1853 | numeric argument. Some functions use it as a repeat count, some | |
1854 | as a flag, and others to choose alternate behavior (refreshing the current | |
1855 | line as opposed to refreshing the screen, for example). Some choose to | |
1856 | ignore it. In general, if a | |
1857 | function uses the numeric argument as a repeat count, it should be able | |
1858 | to do something useful with both negative and positive arguments. | |
1859 | At the very least, it should be aware that it can be passed a | |
1860 | negative argument. | |
1861 | ||
1862 | </P> | |
1863 | ||
1864 | ||
1865 | <H2><A NAME="SEC28" HREF="readline.html#TOC28">Readline Variables</A></H2> | |
1866 | ||
1867 | <P> | |
1868 | These variables are available to function writers. | |
1869 | ||
1870 | </P> | |
1871 | <P> | |
1872 | <DL> | |
1873 | <DT><U>Variable:</U> char * <B>rl_line_buffer</B> | |
1874 | <DD><A NAME="IDX99"></A> | |
1875 | This is the line gathered so far. You are welcome to modify the | |
f9267e15 EZ |
1876 | contents of the line, but see section <A HREF="readline.html#SEC34">Allowing Undoing</A>. The |
1877 | function <CODE>rl_extend_line_buffer</CODE> is available to increase | |
1878 | the memory allocated to <CODE>rl_line_buffer</CODE>. | |
a44161c3 EZ |
1879 | </DL> |
1880 | ||
1881 | </P> | |
1882 | <P> | |
1883 | <DL> | |
1884 | <DT><U>Variable:</U> int <B>rl_point</B> | |
1885 | <DD><A NAME="IDX100"></A> | |
1886 | The offset of the current cursor position in <CODE>rl_line_buffer</CODE> | |
1887 | (the <EM>point</EM>). | |
1888 | </DL> | |
1889 | ||
1890 | </P> | |
1891 | <P> | |
1892 | <DL> | |
1893 | <DT><U>Variable:</U> int <B>rl_end</B> | |
1894 | <DD><A NAME="IDX101"></A> | |
1895 | The number of characters present in <CODE>rl_line_buffer</CODE>. When | |
1896 | <CODE>rl_point</CODE> is at the end of the line, <CODE>rl_point</CODE> and | |
1897 | <CODE>rl_end</CODE> are equal. | |
1898 | </DL> | |
1899 | ||
1900 | </P> | |
1901 | <P> | |
1902 | <DL> | |
1903 | <DT><U>Variable:</U> int <B>rl_mark</B> | |
1904 | <DD><A NAME="IDX102"></A> | |
1905 | The mark (saved position) in the current line. If set, the mark | |
1906 | and point define a <EM>region</EM>. | |
1907 | </DL> | |
1908 | ||
1909 | </P> | |
1910 | <P> | |
1911 | <DL> | |
1912 | <DT><U>Variable:</U> int <B>rl_done</B> | |
1913 | <DD><A NAME="IDX103"></A> | |
1914 | Setting this to a non-zero value causes Readline to return the current | |
1915 | line immediately. | |
1916 | </DL> | |
1917 | ||
1918 | </P> | |
1919 | <P> | |
1920 | <DL> | |
1921 | <DT><U>Variable:</U> int <B>rl_pending_input</B> | |
1922 | <DD><A NAME="IDX104"></A> | |
1923 | Setting this to a value makes it the next keystroke read. This is a | |
1924 | way to stuff a single character into the input stream. | |
1925 | </DL> | |
1926 | ||
1927 | </P> | |
1928 | <P> | |
1929 | <DL> | |
1930 | <DT><U>Variable:</U> int <B>rl_erase_empty_line</B> | |
1931 | <DD><A NAME="IDX105"></A> | |
1932 | Setting this to a non-zero value causes Readline to completely erase | |
1933 | the current line, including any prompt, any time a newline is typed as | |
1934 | the only character on an otherwise-empty line. The cursor is moved to | |
1935 | the beginning of the newly-blank line. | |
1936 | </DL> | |
1937 | ||
1938 | </P> | |
1939 | <P> | |
1940 | <DL> | |
1941 | <DT><U>Variable:</U> char * <B>rl_prompt</B> | |
1942 | <DD><A NAME="IDX106"></A> | |
1943 | The prompt Readline uses. This is set from the argument to | |
1944 | <CODE>readline ()</CODE>, and should not be assigned to directly. | |
1945 | </DL> | |
1946 | ||
1947 | </P> | |
1948 | <P> | |
1949 | <DL> | |
f9267e15 | 1950 | <DT><U>Variable:</U> int <B>rl_already_prompted</B> |
a44161c3 | 1951 | <DD><A NAME="IDX107"></A> |
f9267e15 EZ |
1952 | If an application wishes to display the prompt itself, rather than have |
1953 | Readline do it the first time <CODE>readline()</CODE> is called, it should set | |
1954 | this variable to a non-zero value after displaying the prompt. | |
1955 | The prompt must also be passed as the argument to <CODE>readline()</CODE> so | |
1956 | the redisplay functions can update the display properly. | |
1957 | The calling application is responsible for managing the value; Readline | |
1958 | never sets it. | |
1959 | </DL> | |
1960 | ||
1961 | </P> | |
1962 | <P> | |
1963 | <DL> | |
1964 | <DT><U>Variable:</U> char * <B>rl_library_version</B> | |
1965 | <DD><A NAME="IDX108"></A> | |
a44161c3 EZ |
1966 | The version number of this revision of the library. |
1967 | </DL> | |
1968 | ||
1969 | </P> | |
1970 | <P> | |
1971 | <DL> | |
1972 | <DT><U>Variable:</U> char * <B>rl_terminal_name</B> | |
f9267e15 | 1973 | <DD><A NAME="IDX109"></A> |
a44161c3 EZ |
1974 | The terminal type, used for initialization. |
1975 | </DL> | |
1976 | ||
1977 | </P> | |
1978 | <P> | |
1979 | <DL> | |
1980 | <DT><U>Variable:</U> char * <B>rl_readline_name</B> | |
f9267e15 | 1981 | <DD><A NAME="IDX110"></A> |
a44161c3 EZ |
1982 | This variable is set to a unique name by each application using Readline. |
1983 | The value allows conditional parsing of the inputrc file | |
1984 | (see section <A HREF="readline.html#SEC11">Conditional Init Constructs</A>). | |
1985 | </DL> | |
1986 | ||
1987 | </P> | |
1988 | <P> | |
1989 | <DL> | |
1990 | <DT><U>Variable:</U> FILE * <B>rl_instream</B> | |
f9267e15 | 1991 | <DD><A NAME="IDX111"></A> |
a44161c3 EZ |
1992 | The stdio stream from which Readline reads input. |
1993 | </DL> | |
1994 | ||
1995 | </P> | |
1996 | <P> | |
1997 | <DL> | |
1998 | <DT><U>Variable:</U> FILE * <B>rl_outstream</B> | |
f9267e15 | 1999 | <DD><A NAME="IDX112"></A> |
a44161c3 EZ |
2000 | The stdio stream to which Readline performs output. |
2001 | </DL> | |
2002 | ||
2003 | </P> | |
2004 | <P> | |
2005 | <DL> | |
2006 | <DT><U>Variable:</U> Function * <B>rl_startup_hook</B> | |
f9267e15 | 2007 | <DD><A NAME="IDX113"></A> |
a44161c3 EZ |
2008 | If non-zero, this is the address of a function to call just |
2009 | before <CODE>readline</CODE> prints the first prompt. | |
2010 | </DL> | |
2011 | ||
2012 | </P> | |
2013 | <P> | |
2014 | <DL> | |
2015 | <DT><U>Variable:</U> Function * <B>rl_pre_input_hook</B> | |
f9267e15 | 2016 | <DD><A NAME="IDX114"></A> |
a44161c3 EZ |
2017 | If non-zero, this is the address of a function to call after |
2018 | the first prompt has been printed and just before <CODE>readline</CODE> | |
2019 | starts reading input characters. | |
2020 | </DL> | |
2021 | ||
2022 | </P> | |
2023 | <P> | |
2024 | <DL> | |
2025 | <DT><U>Variable:</U> Function * <B>rl_event_hook</B> | |
f9267e15 | 2026 | <DD><A NAME="IDX115"></A> |
a44161c3 EZ |
2027 | If non-zero, this is the address of a function to call periodically |
2028 | when readline is waiting for terminal input. | |
2029 | </DL> | |
2030 | ||
2031 | </P> | |
2032 | <P> | |
2033 | <DL> | |
2034 | <DT><U>Variable:</U> Function * <B>rl_getc_function</B> | |
f9267e15 | 2035 | <DD><A NAME="IDX116"></A> |
a44161c3 EZ |
2036 | If non-zero, <CODE>readline</CODE> will call indirectly through this pointer |
2037 | to get a character from the input stream. By default, it is set to | |
2038 | <CODE>rl_getc</CODE>, the default <CODE>readline</CODE> character input function | |
2039 | (see section <A HREF="readline.html#SEC37">Utility Functions</A>). | |
2040 | </DL> | |
2041 | ||
2042 | </P> | |
2043 | <P> | |
2044 | <DL> | |
2045 | <DT><U>Variable:</U> VFunction * <B>rl_redisplay_function</B> | |
f9267e15 | 2046 | <DD><A NAME="IDX117"></A> |
a44161c3 EZ |
2047 | If non-zero, <CODE>readline</CODE> will call indirectly through this pointer |
2048 | to update the display with the current contents of the editing buffer. | |
2049 | By default, it is set to <CODE>rl_redisplay</CODE>, the default <CODE>readline</CODE> | |
2050 | redisplay function (see section <A HREF="readline.html#SEC35">Redisplay</A>). | |
2051 | </DL> | |
2052 | ||
2053 | </P> | |
2054 | <P> | |
2055 | <DL> | |
2056 | <DT><U>Variable:</U> Keymap <B>rl_executing_keymap</B> | |
f9267e15 | 2057 | <DD><A NAME="IDX118"></A> |
a44161c3 EZ |
2058 | This variable is set to the keymap (see section <A HREF="readline.html#SEC31">Selecting a Keymap</A>) in which the |
2059 | currently executing readline function was found. | |
2060 | </DL> | |
2061 | ||
2062 | </P> | |
2063 | <P> | |
2064 | <DL> | |
2065 | <DT><U>Variable:</U> Keymap <B>rl_binding_keymap</B> | |
f9267e15 | 2066 | <DD><A NAME="IDX119"></A> |
a44161c3 EZ |
2067 | This variable is set to the keymap (see section <A HREF="readline.html#SEC31">Selecting a Keymap</A>) in which the |
2068 | last key binding occurred. | |
2069 | </DL> | |
2070 | ||
2071 | </P> | |
2072 | ||
2073 | ||
2074 | <H2><A NAME="SEC29" HREF="readline.html#TOC29">Readline Convenience Functions</A></H2> | |
2075 | ||
2076 | ||
2077 | <UL> | |
2078 | <LI><A HREF="readline.html#SEC30">Function Naming</A>: How to give a function you write a name. | |
2079 | <LI><A HREF="readline.html#SEC31">Keymaps</A>: Making keymaps. | |
2080 | <LI><A HREF="readline.html#SEC32">Binding Keys</A>: Changing Keymaps. | |
2081 | <LI><A HREF="readline.html#SEC33">Associating Function Names and Bindings</A>: Translate function names to | |
2082 | key sequences. | |
2083 | <LI><A HREF="readline.html#SEC34">Allowing Undoing</A>: How to make your functions undoable. | |
2084 | <LI><A HREF="readline.html#SEC35">Redisplay</A>: Functions to control line display. | |
2085 | <LI><A HREF="readline.html#SEC36">Modifying Text</A>: Functions to modify <CODE>rl_line_buffer</CODE>. | |
2086 | <LI><A HREF="readline.html#SEC37">Utility Functions</A>: Generally useful functions and hooks. | |
2087 | <LI><A HREF="readline.html#SEC38">Alternate Interface</A>: Using Readline in a `callback' fashion. | |
2088 | </UL> | |
2089 | ||
2090 | ||
2091 | ||
2092 | <H3><A NAME="SEC30" HREF="readline.html#TOC30">Naming a Function</A></H3> | |
2093 | ||
2094 | <P> | |
2095 | The user can dynamically change the bindings of keys while using | |
2096 | Readline. This is done by representing the function with a descriptive | |
2097 | name. The user is able to type the descriptive name when referring to | |
2098 | the function. Thus, in an init file, one might find | |
2099 | ||
2100 | </P> | |
2101 | ||
2102 | <PRE> | |
2103 | Meta-Rubout: backward-kill-word | |
2104 | </PRE> | |
2105 | ||
2106 | <P> | |
2107 | This binds the keystroke <KBD>Meta-Rubout</KBD> to the function | |
2108 | <EM>descriptively</EM> named <CODE>backward-kill-word</CODE>. You, as the | |
2109 | programmer, should bind the functions you write to descriptive names as | |
2110 | well. Readline provides a function for doing that: | |
2111 | ||
2112 | </P> | |
2113 | <P> | |
2114 | <DL> | |
2115 | <DT><U>Function:</U> int <B>rl_add_defun</B> <I>(char *name, Function *function, int key)</I> | |
f9267e15 | 2116 | <DD><A NAME="IDX120"></A> |
a44161c3 EZ |
2117 | Add <VAR>name</VAR> to the list of named functions. Make <VAR>function</VAR> be |
2118 | the function that gets called. If <VAR>key</VAR> is not -1, then bind it to | |
2119 | <VAR>function</VAR> using <CODE>rl_bind_key ()</CODE>. | |
2120 | </DL> | |
2121 | ||
2122 | </P> | |
2123 | <P> | |
2124 | Using this function alone is sufficient for most applications. It is | |
2125 | the recommended way to add a few functions to the default functions that | |
2126 | Readline has built in. If you need to do something other | |
2127 | than adding a function to Readline, you may need to use the | |
2128 | underlying functions described below. | |
2129 | ||
2130 | </P> | |
2131 | ||
2132 | ||
2133 | <H3><A NAME="SEC31" HREF="readline.html#TOC31">Selecting a Keymap</A></H3> | |
2134 | ||
2135 | <P> | |
2136 | Key bindings take place on a <EM>keymap</EM>. The keymap is the | |
2137 | association between the keys that the user types and the functions that | |
2138 | get run. You can make your own keymaps, copy existing keymaps, and tell | |
2139 | Readline which keymap to use. | |
2140 | ||
2141 | </P> | |
2142 | <P> | |
2143 | <DL> | |
2144 | <DT><U>Function:</U> Keymap <B>rl_make_bare_keymap</B> <I>()</I> | |
f9267e15 | 2145 | <DD><A NAME="IDX121"></A> |
a44161c3 EZ |
2146 | Returns a new, empty keymap. The space for the keymap is allocated with |
2147 | <CODE>malloc ()</CODE>; you should <CODE>free ()</CODE> it when you are done. | |
2148 | </DL> | |
2149 | ||
2150 | </P> | |
2151 | <P> | |
2152 | <DL> | |
2153 | <DT><U>Function:</U> Keymap <B>rl_copy_keymap</B> <I>(Keymap map)</I> | |
f9267e15 | 2154 | <DD><A NAME="IDX122"></A> |
a44161c3 EZ |
2155 | Return a new keymap which is a copy of <VAR>map</VAR>. |
2156 | </DL> | |
2157 | ||
2158 | </P> | |
2159 | <P> | |
2160 | <DL> | |
2161 | <DT><U>Function:</U> Keymap <B>rl_make_keymap</B> <I>()</I> | |
f9267e15 | 2162 | <DD><A NAME="IDX123"></A> |
a44161c3 EZ |
2163 | Return a new keymap with the printing characters bound to rl_insert, |
2164 | the lowercase Meta characters bound to run their equivalents, and | |
2165 | the Meta digits bound to produce numeric arguments. | |
2166 | </DL> | |
2167 | ||
2168 | </P> | |
2169 | <P> | |
2170 | <DL> | |
2171 | <DT><U>Function:</U> void <B>rl_discard_keymap</B> <I>(Keymap keymap)</I> | |
f9267e15 | 2172 | <DD><A NAME="IDX124"></A> |
a44161c3 EZ |
2173 | Free the storage associated with <VAR>keymap</VAR>. |
2174 | </DL> | |
2175 | ||
2176 | </P> | |
2177 | <P> | |
2178 | Readline has several internal keymaps. These functions allow you to | |
2179 | change which keymap is active. | |
2180 | ||
2181 | </P> | |
2182 | <P> | |
2183 | <DL> | |
2184 | <DT><U>Function:</U> Keymap <B>rl_get_keymap</B> <I>()</I> | |
f9267e15 | 2185 | <DD><A NAME="IDX125"></A> |
a44161c3 EZ |
2186 | Returns the currently active keymap. |
2187 | </DL> | |
2188 | ||
2189 | </P> | |
2190 | <P> | |
2191 | <DL> | |
2192 | <DT><U>Function:</U> void <B>rl_set_keymap</B> <I>(Keymap keymap)</I> | |
f9267e15 | 2193 | <DD><A NAME="IDX126"></A> |
a44161c3 EZ |
2194 | Makes <VAR>keymap</VAR> the currently active keymap. |
2195 | </DL> | |
2196 | ||
2197 | </P> | |
2198 | <P> | |
2199 | <DL> | |
2200 | <DT><U>Function:</U> Keymap <B>rl_get_keymap_by_name</B> <I>(char *name)</I> | |
f9267e15 | 2201 | <DD><A NAME="IDX127"></A> |
a44161c3 EZ |
2202 | Return the keymap matching <VAR>name</VAR>. <VAR>name</VAR> is one which would |
2203 | be supplied in a <CODE>set keymap</CODE> inputrc line (see section <A HREF="readline.html#SEC9">Readline Init File</A>). | |
2204 | </DL> | |
2205 | ||
2206 | </P> | |
2207 | <P> | |
2208 | <DL> | |
2209 | <DT><U>Function:</U> char * <B>rl_get_keymap_name</B> <I>(Keymap keymap)</I> | |
f9267e15 | 2210 | <DD><A NAME="IDX128"></A> |
a44161c3 EZ |
2211 | Return the name matching <VAR>keymap</VAR>. <VAR>name</VAR> is one which would |
2212 | be supplied in a <CODE>set keymap</CODE> inputrc line (see section <A HREF="readline.html#SEC9">Readline Init File</A>). | |
2213 | </DL> | |
2214 | ||
2215 | </P> | |
2216 | ||
2217 | ||
2218 | <H3><A NAME="SEC32" HREF="readline.html#TOC32">Binding Keys</A></H3> | |
2219 | ||
2220 | <P> | |
2221 | You associate keys with functions through the keymap. Readline has | |
2222 | several internal keymaps: <CODE>emacs_standard_keymap</CODE>, | |
2223 | <CODE>emacs_meta_keymap</CODE>, <CODE>emacs_ctlx_keymap</CODE>, | |
2224 | <CODE>vi_movement_keymap</CODE>, and <CODE>vi_insertion_keymap</CODE>. | |
2225 | <CODE>emacs_standard_keymap</CODE> is the default, and the examples in | |
2226 | this manual assume that. | |
2227 | ||
f9267e15 EZ |
2228 | </P> |
2229 | <P> | |
2230 | Since <CODE>readline</CODE> installs a set of default key bindings the first | |
2231 | time it is called, there is always the danger that a custom binding | |
2232 | installed before the first call to <CODE>readline</CODE> will be overridden. | |
2233 | An alternate mechanism is to install custom key bindings in an | |
2234 | initialization function assigned to the <CODE>rl_startup_hook</CODE> variable | |
2235 | (see section <A HREF="readline.html#SEC28">Readline Variables</A>). | |
2236 | ||
a44161c3 EZ |
2237 | </P> |
2238 | <P> | |
2239 | These functions manage key bindings. | |
2240 | ||
2241 | </P> | |
2242 | <P> | |
2243 | <DL> | |
2244 | <DT><U>Function:</U> int <B>rl_bind_key</B> <I>(int key, Function *function)</I> | |
f9267e15 | 2245 | <DD><A NAME="IDX129"></A> |
a44161c3 EZ |
2246 | Binds <VAR>key</VAR> to <VAR>function</VAR> in the currently active keymap. |
2247 | Returns non-zero in the case of an invalid <VAR>key</VAR>. | |
2248 | </DL> | |
2249 | ||
2250 | </P> | |
2251 | <P> | |
2252 | <DL> | |
2253 | <DT><U>Function:</U> int <B>rl_bind_key_in_map</B> <I>(int key, Function *function, Keymap map)</I> | |
f9267e15 | 2254 | <DD><A NAME="IDX130"></A> |
a44161c3 EZ |
2255 | Bind <VAR>key</VAR> to <VAR>function</VAR> in <VAR>map</VAR>. Returns non-zero in the case |
2256 | of an invalid <VAR>key</VAR>. | |
2257 | </DL> | |
2258 | ||
2259 | </P> | |
2260 | <P> | |
2261 | <DL> | |
2262 | <DT><U>Function:</U> int <B>rl_unbind_key</B> <I>(int key)</I> | |
f9267e15 | 2263 | <DD><A NAME="IDX131"></A> |
a44161c3 EZ |
2264 | Bind <VAR>key</VAR> to the null function in the currently active keymap. |
2265 | Returns non-zero in case of error. | |
2266 | </DL> | |
2267 | ||
2268 | </P> | |
2269 | <P> | |
2270 | <DL> | |
2271 | <DT><U>Function:</U> int <B>rl_unbind_key_in_map</B> <I>(int key, Keymap map)</I> | |
f9267e15 | 2272 | <DD><A NAME="IDX132"></A> |
a44161c3 EZ |
2273 | Bind <VAR>key</VAR> to the null function in <VAR>map</VAR>. |
2274 | Returns non-zero in case of error. | |
2275 | </DL> | |
2276 | ||
2277 | </P> | |
2278 | <P> | |
2279 | <DL> | |
2280 | <DT><U>Function:</U> int <B>rl_unbind_function_in_map</B> <I>(Function *function, Keymap map)</I> | |
f9267e15 | 2281 | <DD><A NAME="IDX133"></A> |
a44161c3 EZ |
2282 | Unbind all keys that execute <VAR>function</VAR> in <VAR>map</VAR>. |
2283 | </DL> | |
2284 | ||
2285 | </P> | |
2286 | <P> | |
2287 | <DL> | |
2288 | <DT><U>Function:</U> int <B>rl_unbind_command_in_map</B> <I>(char *command, Keymap map)</I> | |
f9267e15 | 2289 | <DD><A NAME="IDX134"></A> |
a44161c3 EZ |
2290 | Unbind all keys that are bound to <VAR>command</VAR> in <VAR>map</VAR>. |
2291 | </DL> | |
2292 | ||
2293 | </P> | |
2294 | <P> | |
2295 | <DL> | |
2296 | <DT><U>Function:</U> int <B>rl_generic_bind</B> <I>(int type, char *keyseq, char *data, Keymap map)</I> | |
f9267e15 | 2297 | <DD><A NAME="IDX135"></A> |
a44161c3 EZ |
2298 | Bind the key sequence represented by the string <VAR>keyseq</VAR> to the arbitrary |
2299 | pointer <VAR>data</VAR>. <VAR>type</VAR> says what kind of data is pointed to by | |
2300 | <VAR>data</VAR>; this can be a function (<CODE>ISFUNC</CODE>), a macro | |
2301 | (<CODE>ISMACR</CODE>), or a keymap (<CODE>ISKMAP</CODE>). This makes new keymaps as | |
2302 | necessary. The initial keymap in which to do bindings is <VAR>map</VAR>. | |
2303 | </DL> | |
2304 | ||
2305 | </P> | |
2306 | <P> | |
2307 | <DL> | |
2308 | <DT><U>Function:</U> int <B>rl_parse_and_bind</B> <I>(char *line)</I> | |
f9267e15 | 2309 | <DD><A NAME="IDX136"></A> |
a44161c3 EZ |
2310 | Parse <VAR>line</VAR> as if it had been read from the <CODE>inputrc</CODE> file and |
2311 | perform any key bindings and variable assignments found | |
2312 | (see section <A HREF="readline.html#SEC9">Readline Init File</A>). | |
2313 | </DL> | |
2314 | ||
2315 | </P> | |
2316 | <P> | |
2317 | <DL> | |
2318 | <DT><U>Function:</U> int <B>rl_read_init_file</B> <I>(char *filename)</I> | |
f9267e15 | 2319 | <DD><A NAME="IDX137"></A> |
a44161c3 EZ |
2320 | Read keybindings and variable assignments from <VAR>filename</VAR> |
2321 | (see section <A HREF="readline.html#SEC9">Readline Init File</A>). | |
2322 | </DL> | |
2323 | ||
2324 | </P> | |
2325 | ||
2326 | ||
2327 | <H3><A NAME="SEC33" HREF="readline.html#TOC33">Associating Function Names and Bindings</A></H3> | |
2328 | ||
2329 | <P> | |
2330 | These functions allow you to find out what keys invoke named functions | |
2331 | and the functions invoked by a particular key sequence. | |
2332 | ||
2333 | </P> | |
2334 | <P> | |
2335 | <DL> | |
2336 | <DT><U>Function:</U> Function * <B>rl_named_function</B> <I>(char *name)</I> | |
f9267e15 | 2337 | <DD><A NAME="IDX138"></A> |
a44161c3 EZ |
2338 | Return the function with name <VAR>name</VAR>. |
2339 | </DL> | |
2340 | ||
2341 | </P> | |
2342 | <P> | |
2343 | <DL> | |
2344 | <DT><U>Function:</U> Function * <B>rl_function_of_keyseq</B> <I>(char *keyseq, Keymap map, int *type)</I> | |
f9267e15 | 2345 | <DD><A NAME="IDX139"></A> |
a44161c3 EZ |
2346 | Return the function invoked by <VAR>keyseq</VAR> in keymap <VAR>map</VAR>. |
2347 | If <VAR>map</VAR> is NULL, the current keymap is used. If <VAR>type</VAR> is | |
2348 | not NULL, the type of the object is returned in it (one of <CODE>ISFUNC</CODE>, | |
2349 | <CODE>ISKMAP</CODE>, or <CODE>ISMACR</CODE>). | |
2350 | </DL> | |
2351 | ||
2352 | </P> | |
2353 | <P> | |
2354 | <DL> | |
2355 | <DT><U>Function:</U> char ** <B>rl_invoking_keyseqs</B> <I>(Function *function)</I> | |
f9267e15 | 2356 | <DD><A NAME="IDX140"></A> |
a44161c3 EZ |
2357 | Return an array of strings representing the key sequences used to |
2358 | invoke <VAR>function</VAR> in the current keymap. | |
2359 | </DL> | |
2360 | ||
2361 | </P> | |
2362 | <P> | |
2363 | <DL> | |
2364 | <DT><U>Function:</U> char ** <B>rl_invoking_keyseqs_in_map</B> <I>(Function *function, Keymap map)</I> | |
f9267e15 | 2365 | <DD><A NAME="IDX141"></A> |
a44161c3 EZ |
2366 | Return an array of strings representing the key sequences used to |
2367 | invoke <VAR>function</VAR> in the keymap <VAR>map</VAR>. | |
2368 | </DL> | |
2369 | ||
2370 | </P> | |
2371 | <P> | |
2372 | <DL> | |
2373 | <DT><U>Function:</U> void <B>rl_function_dumper</B> <I>(int readable)</I> | |
f9267e15 | 2374 | <DD><A NAME="IDX142"></A> |
a44161c3 EZ |
2375 | Print the readline function names and the key sequences currently |
2376 | bound to them to <CODE>rl_outstream</CODE>. If <VAR>readable</VAR> is non-zero, | |
2377 | the list is formatted in such a way that it can be made part of an | |
2378 | <CODE>inputrc</CODE> file and re-read. | |
2379 | </DL> | |
2380 | ||
2381 | </P> | |
2382 | <P> | |
2383 | <DL> | |
2384 | <DT><U>Function:</U> void <B>rl_list_funmap_names</B> <I>()</I> | |
f9267e15 | 2385 | <DD><A NAME="IDX143"></A> |
a44161c3 EZ |
2386 | Print the names of all bindable Readline functions to <CODE>rl_outstream</CODE>. |
2387 | </DL> | |
2388 | ||
f9267e15 EZ |
2389 | </P> |
2390 | <P> | |
2391 | <DL> | |
2392 | <DT><U>Function:</U> char ** <B>rl_funmap_names</B> <I>()</I> | |
2393 | <DD><A NAME="IDX144"></A> | |
2394 | Return a NULL terminated array of known function names. The array is | |
2395 | sorted. The array itself is allocated, but not the strings inside. You | |
2396 | should free () the array when you done, but not the pointrs. | |
2397 | </DL> | |
2398 | ||
a44161c3 EZ |
2399 | </P> |
2400 | ||
2401 | ||
2402 | <H3><A NAME="SEC34" HREF="readline.html#TOC34">Allowing Undoing</A></H3> | |
2403 | ||
2404 | <P> | |
2405 | Supporting the undo command is a painless thing, and makes your | |
2406 | functions much more useful. It is certainly easy to try | |
2407 | something if you know you can undo it. I could use an undo function for | |
2408 | the stock market. | |
2409 | ||
2410 | </P> | |
2411 | <P> | |
2412 | If your function simply inserts text once, or deletes text once, and | |
2413 | uses <CODE>rl_insert_text ()</CODE> or <CODE>rl_delete_text ()</CODE> to do it, then | |
2414 | undoing is already done for you automatically. | |
2415 | ||
2416 | </P> | |
2417 | <P> | |
2418 | If you do multiple insertions or multiple deletions, or any combination | |
2419 | of these operations, you should group them together into one operation. | |
2420 | This is done with <CODE>rl_begin_undo_group ()</CODE> and | |
2421 | <CODE>rl_end_undo_group ()</CODE>. | |
2422 | ||
2423 | </P> | |
2424 | <P> | |
2425 | The types of events that can be undone are: | |
2426 | ||
2427 | </P> | |
2428 | ||
2429 | <PRE> | |
2430 | enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END }; | |
2431 | </PRE> | |
2432 | ||
2433 | <P> | |
2434 | Notice that <CODE>UNDO_DELETE</CODE> means to insert some text, and | |
2435 | <CODE>UNDO_INSERT</CODE> means to delete some text. That is, the undo code | |
2436 | tells undo what to undo, not how to undo it. <CODE>UNDO_BEGIN</CODE> and | |
2437 | <CODE>UNDO_END</CODE> are tags added by <CODE>rl_begin_undo_group ()</CODE> and | |
2438 | <CODE>rl_end_undo_group ()</CODE>. | |
2439 | ||
2440 | </P> | |
2441 | <P> | |
2442 | <DL> | |
2443 | <DT><U>Function:</U> int <B>rl_begin_undo_group</B> <I>()</I> | |
f9267e15 | 2444 | <DD><A NAME="IDX145"></A> |
a44161c3 EZ |
2445 | Begins saving undo information in a group construct. The undo |
2446 | information usually comes from calls to <CODE>rl_insert_text ()</CODE> and | |
2447 | <CODE>rl_delete_text ()</CODE>, but could be the result of calls to | |
2448 | <CODE>rl_add_undo ()</CODE>. | |
2449 | </DL> | |
2450 | ||
2451 | </P> | |
2452 | <P> | |
2453 | <DL> | |
2454 | <DT><U>Function:</U> int <B>rl_end_undo_group</B> <I>()</I> | |
f9267e15 | 2455 | <DD><A NAME="IDX146"></A> |
a44161c3 EZ |
2456 | Closes the current undo group started with <CODE>rl_begin_undo_group |
2457 | ()</CODE>. There should be one call to <CODE>rl_end_undo_group ()</CODE> | |
2458 | for each call to <CODE>rl_begin_undo_group ()</CODE>. | |
2459 | </DL> | |
2460 | ||
2461 | </P> | |
2462 | <P> | |
2463 | <DL> | |
2464 | <DT><U>Function:</U> void <B>rl_add_undo</B> <I>(enum undo_code what, int start, int end, char *text)</I> | |
f9267e15 | 2465 | <DD><A NAME="IDX147"></A> |
a44161c3 EZ |
2466 | Remember how to undo an event (according to <VAR>what</VAR>). The affected |
2467 | text runs from <VAR>start</VAR> to <VAR>end</VAR>, and encompasses <VAR>text</VAR>. | |
2468 | </DL> | |
2469 | ||
2470 | </P> | |
2471 | <P> | |
2472 | <DL> | |
2473 | <DT><U>Function:</U> void <B>free_undo_list</B> <I>()</I> | |
f9267e15 | 2474 | <DD><A NAME="IDX148"></A> |
a44161c3 EZ |
2475 | Free the existing undo list. |
2476 | </DL> | |
2477 | ||
2478 | </P> | |
2479 | <P> | |
2480 | <DL> | |
2481 | <DT><U>Function:</U> int <B>rl_do_undo</B> <I>()</I> | |
f9267e15 | 2482 | <DD><A NAME="IDX149"></A> |
a44161c3 EZ |
2483 | Undo the first thing on the undo list. Returns <CODE>0</CODE> if there was |
2484 | nothing to undo, non-zero if something was undone. | |
2485 | </DL> | |
2486 | ||
2487 | </P> | |
2488 | <P> | |
2489 | Finally, if you neither insert nor delete text, but directly modify the | |
2490 | existing text (e.g., change its case), call <CODE>rl_modifying ()</CODE> | |
2491 | once, just before you modify the text. You must supply the indices of | |
2492 | the text range that you are going to modify. | |
2493 | ||
2494 | </P> | |
2495 | <P> | |
2496 | <DL> | |
2497 | <DT><U>Function:</U> int <B>rl_modifying</B> <I>(int start, int end)</I> | |
f9267e15 | 2498 | <DD><A NAME="IDX150"></A> |
a44161c3 EZ |
2499 | Tell Readline to save the text between <VAR>start</VAR> and <VAR>end</VAR> as a |
2500 | single undo unit. It is assumed that you will subsequently modify | |
2501 | that text. | |
2502 | </DL> | |
2503 | ||
2504 | </P> | |
2505 | ||
2506 | ||
2507 | <H3><A NAME="SEC35" HREF="readline.html#TOC35">Redisplay</A></H3> | |
2508 | ||
2509 | <P> | |
2510 | <DL> | |
2511 | <DT><U>Function:</U> void <B>rl_redisplay</B> <I>()</I> | |
f9267e15 | 2512 | <DD><A NAME="IDX151"></A> |
a44161c3 EZ |
2513 | Change what's displayed on the screen to reflect the current contents |
2514 | of <CODE>rl_line_buffer</CODE>. | |
2515 | </DL> | |
2516 | ||
2517 | </P> | |
2518 | <P> | |
2519 | <DL> | |
2520 | <DT><U>Function:</U> int <B>rl_forced_update_display</B> <I>()</I> | |
f9267e15 | 2521 | <DD><A NAME="IDX152"></A> |
a44161c3 EZ |
2522 | Force the line to be updated and redisplayed, whether or not |
2523 | Readline thinks the screen display is correct. | |
2524 | </DL> | |
2525 | ||
2526 | </P> | |
2527 | <P> | |
2528 | <DL> | |
2529 | <DT><U>Function:</U> int <B>rl_on_new_line</B> <I>()</I> | |
f9267e15 EZ |
2530 | <DD><A NAME="IDX153"></A> |
2531 | Tell the update functions that we have moved onto a new (empty) line, | |
a44161c3 EZ |
2532 | usually after ouputting a newline. |
2533 | </DL> | |
2534 | ||
f9267e15 EZ |
2535 | </P> |
2536 | <P> | |
2537 | <DL> | |
2538 | <DT><U>Function:</U> int <B>rl_on_new_line_with_prompt</B> <I>()</I> | |
2539 | <DD><A NAME="IDX154"></A> | |
2540 | Tell the update functions that we have moved onto a new line, with | |
2541 | <VAR>rl_prompt</VAR> already displayed. | |
2542 | This could be used by applications that want to output the prompt string | |
2543 | themselves, but still need Readline to know the prompt string length for | |
2544 | redisplay. | |
2545 | It should be used after setting <VAR>rl_already_prompted</VAR>. | |
2546 | </DL> | |
2547 | ||
a44161c3 EZ |
2548 | </P> |
2549 | <P> | |
2550 | <DL> | |
2551 | <DT><U>Function:</U> int <B>rl_reset_line_state</B> <I>()</I> | |
f9267e15 | 2552 | <DD><A NAME="IDX155"></A> |
a44161c3 EZ |
2553 | Reset the display state to a clean state and redisplay the current line |
2554 | starting on a new line. | |
2555 | </DL> | |
2556 | ||
2557 | </P> | |
2558 | <P> | |
2559 | <DL> | |
2560 | <DT><U>Function:</U> int <B>rl_message</B> <I>(va_alist)</I> | |
f9267e15 | 2561 | <DD><A NAME="IDX156"></A> |
a44161c3 EZ |
2562 | The arguments are a string as would be supplied to <CODE>printf</CODE>. The |
2563 | resulting string is displayed in the <EM>echo area</EM>. The echo area | |
2564 | is also used to display numeric arguments and search strings. | |
2565 | </DL> | |
2566 | ||
2567 | </P> | |
2568 | <P> | |
2569 | <DL> | |
2570 | <DT><U>Function:</U> int <B>rl_clear_message</B> <I>()</I> | |
f9267e15 | 2571 | <DD><A NAME="IDX157"></A> |
a44161c3 EZ |
2572 | Clear the message in the echo area. |
2573 | </DL> | |
2574 | ||
2575 | </P> | |
2576 | <P> | |
2577 | <DL> | |
2578 | <DT><U>Function:</U> void <B>rl_save_prompt</B> <I>()</I> | |
f9267e15 | 2579 | <DD><A NAME="IDX158"></A> |
a44161c3 EZ |
2580 | Save the local Readline prompt display state in preparation for |
2581 | displaying a new message in the message area with <CODE>rl_message</CODE>. | |
2582 | </DL> | |
2583 | ||
2584 | </P> | |
2585 | <P> | |
2586 | <DL> | |
2587 | <DT><U>Function:</U> void <B>rl_restore_prompt</B> <I>()</I> | |
f9267e15 | 2588 | <DD><A NAME="IDX159"></A> |
a44161c3 EZ |
2589 | Restore the local Readline prompt display state saved by the most |
2590 | recent call to <CODE>rl_save_prompt</CODE>. | |
2591 | </DL> | |
2592 | ||
2593 | </P> | |
2594 | ||
2595 | ||
2596 | <H3><A NAME="SEC36" HREF="readline.html#TOC36">Modifying Text</A></H3> | |
2597 | ||
2598 | <P> | |
2599 | <DL> | |
2600 | <DT><U>Function:</U> int <B>rl_insert_text</B> <I>(char *text)</I> | |
f9267e15 | 2601 | <DD><A NAME="IDX160"></A> |
a44161c3 EZ |
2602 | Insert <VAR>text</VAR> into the line at the current cursor position. |
2603 | </DL> | |
2604 | ||
2605 | </P> | |
2606 | <P> | |
2607 | <DL> | |
2608 | <DT><U>Function:</U> int <B>rl_delete_text</B> <I>(int start, int end)</I> | |
f9267e15 | 2609 | <DD><A NAME="IDX161"></A> |
a44161c3 EZ |
2610 | Delete the text between <VAR>start</VAR> and <VAR>end</VAR> in the current line. |
2611 | </DL> | |
2612 | ||
2613 | </P> | |
2614 | <P> | |
2615 | <DL> | |
2616 | <DT><U>Function:</U> char * <B>rl_copy_text</B> <I>(int start, int end)</I> | |
f9267e15 | 2617 | <DD><A NAME="IDX162"></A> |
a44161c3 EZ |
2618 | Return a copy of the text between <VAR>start</VAR> and <VAR>end</VAR> in |
2619 | the current line. | |
2620 | </DL> | |
2621 | ||
2622 | </P> | |
2623 | <P> | |
2624 | <DL> | |
2625 | <DT><U>Function:</U> int <B>rl_kill_text</B> <I>(int start, int end)</I> | |
f9267e15 | 2626 | <DD><A NAME="IDX163"></A> |
a44161c3 EZ |
2627 | Copy the text between <VAR>start</VAR> and <VAR>end</VAR> in the current line |
2628 | to the kill ring, appending or prepending to the last kill if the | |
2629 | last command was a kill command. The text is deleted. | |
2630 | If <VAR>start</VAR> is less than <VAR>end</VAR>, | |
2631 | the text is appended, otherwise prepended. If the last command was | |
2632 | not a kill, a new kill ring slot is used. | |
2633 | </DL> | |
2634 | ||
2635 | </P> | |
2636 | ||
2637 | ||
2638 | <H3><A NAME="SEC37" HREF="readline.html#TOC37">Utility Functions</A></H3> | |
2639 | ||
2640 | <P> | |
2641 | <DL> | |
2642 | <DT><U>Function:</U> int <B>rl_read_key</B> <I>()</I> | |
f9267e15 | 2643 | <DD><A NAME="IDX164"></A> |
a44161c3 EZ |
2644 | Return the next character available. This handles input inserted into |
2645 | the input stream via <VAR>pending input</VAR> (see section <A HREF="readline.html#SEC28">Readline Variables</A>) | |
2646 | and <CODE>rl_stuff_char ()</CODE>, macros, and characters read from the keyboard. | |
2647 | </DL> | |
2648 | ||
2649 | </P> | |
2650 | <P> | |
2651 | <DL> | |
2652 | <DT><U>Function:</U> int <B>rl_getc</B> <I>(FILE *)</I> | |
f9267e15 | 2653 | <DD><A NAME="IDX165"></A> |
a44161c3 EZ |
2654 | Return the next character available from the keyboard. |
2655 | </DL> | |
2656 | ||
2657 | </P> | |
2658 | <P> | |
2659 | <DL> | |
2660 | <DT><U>Function:</U> int <B>rl_stuff_char</B> <I>(int c)</I> | |
f9267e15 | 2661 | <DD><A NAME="IDX166"></A> |
a44161c3 EZ |
2662 | Insert <VAR>c</VAR> into the Readline input stream. It will be "read" |
2663 | before Readline attempts to read characters from the terminal with | |
2664 | <CODE>rl_read_key ()</CODE>. | |
2665 | </DL> | |
2666 | ||
2667 | </P> | |
2668 | <P> | |
2669 | <DL> | |
f9267e15 EZ |
2670 | <DT><U>Function:</U> int <B>rl_extend_line_buffer</B> <I>(int len)</I> |
2671 | <DD><A NAME="IDX167"></A> | |
a44161c3 EZ |
2672 | Ensure that <CODE>rl_line_buffer</CODE> has enough space to hold <VAR>len</VAR> |
2673 | characters, possibly reallocating it if necessary. | |
2674 | </DL> | |
2675 | ||
2676 | </P> | |
2677 | <P> | |
2678 | <DL> | |
2679 | <DT><U>Function:</U> int <B>rl_initialize</B> <I>()</I> | |
f9267e15 | 2680 | <DD><A NAME="IDX168"></A> |
a44161c3 EZ |
2681 | Initialize or re-initialize Readline's internal state. |
2682 | </DL> | |
2683 | ||
2684 | </P> | |
2685 | <P> | |
2686 | <DL> | |
2687 | <DT><U>Function:</U> int <B>rl_reset_terminal</B> <I>(char *terminal_name)</I> | |
f9267e15 | 2688 | <DD><A NAME="IDX169"></A> |
a44161c3 EZ |
2689 | Reinitialize Readline's idea of the terminal settings using |
2690 | <VAR>terminal_name</VAR> as the terminal type (e.g., <CODE>vt100</CODE>). | |
f9267e15 EZ |
2691 | If <VAR>terminal_name</VAR> is NULL, the value of the <CODE>TERM</CODE> |
2692 | environment variable is used. | |
a44161c3 EZ |
2693 | </DL> |
2694 | ||
2695 | </P> | |
2696 | <P> | |
2697 | <DL> | |
2698 | <DT><U>Function:</U> int <B>alphabetic</B> <I>(int c)</I> | |
f9267e15 | 2699 | <DD><A NAME="IDX170"></A> |
a44161c3 EZ |
2700 | Return 1 if <VAR>c</VAR> is an alphabetic character. |
2701 | </DL> | |
2702 | ||
2703 | </P> | |
2704 | <P> | |
2705 | <DL> | |
2706 | <DT><U>Function:</U> int <B>numeric</B> <I>(int c)</I> | |
f9267e15 | 2707 | <DD><A NAME="IDX171"></A> |
a44161c3 EZ |
2708 | Return 1 if <VAR>c</VAR> is a numeric character. |
2709 | </DL> | |
2710 | ||
2711 | </P> | |
2712 | <P> | |
2713 | <DL> | |
2714 | <DT><U>Function:</U> int <B>ding</B> <I>()</I> | |
f9267e15 | 2715 | <DD><A NAME="IDX172"></A> |
a44161c3 EZ |
2716 | Ring the terminal bell, obeying the setting of <CODE>bell-style</CODE>. |
2717 | </DL> | |
2718 | ||
2719 | </P> | |
2720 | <P> | |
2721 | <DL> | |
2722 | <DT><U>Function:</U> void <B>rl_display_match_list</B> <I>(char **matches, int len, int max)</I> | |
f9267e15 | 2723 | <DD><A NAME="IDX173"></A> |
a44161c3 EZ |
2724 | A convenience function for displaying a list of strings in |
2725 | columnar format on Readline's output stream. <CODE>matches</CODE> is the list | |
2726 | of strings, in argv format, such as a list of completion matches. | |
2727 | <CODE>len</CODE> is the number of strings in <CODE>matches</CODE>, and <CODE>max</CODE> | |
2728 | is the length of the longest string in <CODE>matches</CODE>. This function uses | |
2729 | the setting of <CODE>print-completions-horizontally</CODE> to select how the | |
2730 | matches are displayed (see section <A HREF="readline.html#SEC10">Readline Init File Syntax</A>). | |
2731 | </DL> | |
2732 | ||
2733 | </P> | |
2734 | <P> | |
2735 | The following are implemented as macros, defined in <CODE>chartypes.h</CODE>. | |
2736 | ||
2737 | </P> | |
2738 | <P> | |
2739 | <DL> | |
2740 | <DT><U>Function:</U> int <B>uppercase_p</B> <I>(int c)</I> | |
f9267e15 | 2741 | <DD><A NAME="IDX174"></A> |
a44161c3 EZ |
2742 | Return 1 if <VAR>c</VAR> is an uppercase alphabetic character. |
2743 | </DL> | |
2744 | ||
2745 | </P> | |
2746 | <P> | |
2747 | <DL> | |
2748 | <DT><U>Function:</U> int <B>lowercase_p</B> <I>(int c)</I> | |
f9267e15 | 2749 | <DD><A NAME="IDX175"></A> |
a44161c3 EZ |
2750 | Return 1 if <VAR>c</VAR> is a lowercase alphabetic character. |
2751 | </DL> | |
2752 | ||
2753 | </P> | |
2754 | <P> | |
2755 | <DL> | |
2756 | <DT><U>Function:</U> int <B>digit_p</B> <I>(int c)</I> | |
f9267e15 | 2757 | <DD><A NAME="IDX176"></A> |
a44161c3 EZ |
2758 | Return 1 if <VAR>c</VAR> is a numeric character. |
2759 | </DL> | |
2760 | ||
2761 | </P> | |
2762 | <P> | |
2763 | <DL> | |
2764 | <DT><U>Function:</U> int <B>to_upper</B> <I>(int c)</I> | |
f9267e15 | 2765 | <DD><A NAME="IDX177"></A> |
a44161c3 EZ |
2766 | If <VAR>c</VAR> is a lowercase alphabetic character, return the corresponding |
2767 | uppercase character. | |
2768 | </DL> | |
2769 | ||
2770 | </P> | |
2771 | <P> | |
2772 | <DL> | |
2773 | <DT><U>Function:</U> int <B>to_lower</B> <I>(int c)</I> | |
f9267e15 | 2774 | <DD><A NAME="IDX178"></A> |
a44161c3 EZ |
2775 | If <VAR>c</VAR> is an uppercase alphabetic character, return the corresponding |
2776 | lowercase character. | |
2777 | </DL> | |
2778 | ||
2779 | </P> | |
2780 | <P> | |
2781 | <DL> | |
2782 | <DT><U>Function:</U> int <B>digit_value</B> <I>(int c)</I> | |
f9267e15 | 2783 | <DD><A NAME="IDX179"></A> |
a44161c3 EZ |
2784 | If <VAR>c</VAR> is a number, return the value it represents. |
2785 | </DL> | |
2786 | ||
2787 | </P> | |
2788 | ||
2789 | ||
2790 | <H3><A NAME="SEC38" HREF="readline.html#TOC38">Alternate Interface</A></H3> | |
2791 | ||
2792 | <P> | |
2793 | An alternate interface is available to plain <CODE>readline()</CODE>. Some | |
2794 | applications need to interleave keyboard I/O with file, device, or | |
2795 | window system I/O, typically by using a main loop to <CODE>select()</CODE> | |
2796 | on various file descriptors. To accomodate this need, readline can | |
2797 | also be invoked as a `callback' function from an event loop. There | |
2798 | are functions available to make this easy. | |
2799 | ||
2800 | </P> | |
2801 | <P> | |
2802 | <DL> | |
2803 | <DT><U>Function:</U> void <B>rl_callback_handler_install</B> <I>(char *prompt, Vfunction *lhandler)</I> | |
f9267e15 | 2804 | <DD><A NAME="IDX180"></A> |
a44161c3 EZ |
2805 | Set up the terminal for readline I/O and display the initial |
2806 | expanded value of <VAR>prompt</VAR>. Save the value of <VAR>lhandler</VAR> to | |
2807 | use as a callback when a complete line of input has been entered. | |
2808 | </DL> | |
2809 | ||
2810 | </P> | |
2811 | <P> | |
2812 | <DL> | |
2813 | <DT><U>Function:</U> void <B>rl_callback_read_char</B> <I>()</I> | |
f9267e15 | 2814 | <DD><A NAME="IDX181"></A> |
a44161c3 EZ |
2815 | Whenever an application determines that keyboard input is available, it |
2816 | should call <CODE>rl_callback_read_char()</CODE>, which will read the next | |
2817 | character from the current input source. If that character completes the | |
2818 | line, <CODE>rl_callback_read_char</CODE> will invoke the <VAR>lhandler</VAR> | |
2819 | function saved by <CODE>rl_callback_handler_install</CODE> to process the | |
2820 | line. <CODE>EOF</CODE> is indicated by calling <VAR>lhandler</VAR> with a | |
2821 | <CODE>NULL</CODE> line. | |
2822 | </DL> | |
2823 | ||
2824 | </P> | |
2825 | <P> | |
2826 | <DL> | |
2827 | <DT><U>Function:</U> void <B>rl_callback_handler_remove</B> <I>()</I> | |
f9267e15 | 2828 | <DD><A NAME="IDX182"></A> |
a44161c3 EZ |
2829 | Restore the terminal to its initial state and remove the line handler. |
2830 | This may be called from within a callback as well as independently. | |
2831 | </DL> | |
2832 | ||
2833 | </P> | |
2834 | ||
2835 | ||
2836 | <H3><A NAME="SEC39" HREF="readline.html#TOC39">An Example</A></H3> | |
2837 | ||
2838 | <P> | |
2839 | Here is a function which changes lowercase characters to their uppercase | |
2840 | equivalents, and uppercase characters to lowercase. If | |
2841 | this function was bound to <SAMP>`M-c'</SAMP>, then typing <SAMP>`M-c'</SAMP> would | |
2842 | change the case of the character under point. Typing <SAMP>`M-1 0 M-c'</SAMP> | |
2843 | would change the case of the following 10 characters, leaving the cursor on | |
2844 | the last character changed. | |
2845 | ||
2846 | </P> | |
2847 | ||
2848 | <PRE> | |
2849 | /* Invert the case of the COUNT following characters. */ | |
2850 | int | |
2851 | invert_case_line (count, key) | |
2852 | int count, key; | |
2853 | { | |
2854 | register int start, end, i; | |
2855 | ||
2856 | start = rl_point; | |
2857 | ||
2858 | if (rl_point >= rl_end) | |
2859 | return (0); | |
2860 | ||
2861 | if (count < 0) | |
2862 | { | |
2863 | direction = -1; | |
2864 | count = -count; | |
2865 | } | |
2866 | else | |
2867 | direction = 1; | |
2868 | ||
2869 | /* Find the end of the range to modify. */ | |
2870 | end = start + (count * direction); | |
2871 | ||
2872 | /* Force it to be within range. */ | |
2873 | if (end > rl_end) | |
2874 | end = rl_end; | |
2875 | else if (end < 0) | |
2876 | end = 0; | |
2877 | ||
2878 | if (start == end) | |
2879 | return (0); | |
2880 | ||
2881 | if (start > end) | |
2882 | { | |
2883 | int temp = start; | |
2884 | start = end; | |
2885 | end = temp; | |
2886 | } | |
2887 | ||
2888 | /* Tell readline that we are modifying the line, so it will save | |
2889 | the undo information. */ | |
2890 | rl_modifying (start, end); | |
2891 | ||
2892 | for (i = start; i != end; i++) | |
2893 | { | |
2894 | if (uppercase_p (rl_line_buffer[i])) | |
2895 | rl_line_buffer[i] = to_lower (rl_line_buffer[i]); | |
2896 | else if (lowercase_p (rl_line_buffer[i])) | |
2897 | rl_line_buffer[i] = to_upper (rl_line_buffer[i]); | |
2898 | } | |
2899 | /* Move point to on top of the last character changed. */ | |
2900 | rl_point = (direction == 1) ? end - 1 : start; | |
2901 | return (0); | |
2902 | } | |
2903 | </PRE> | |
2904 | ||
2905 | ||
2906 | ||
2907 | <H2><A NAME="SEC40" HREF="readline.html#TOC40">Readline Signal Handling</A></H2> | |
2908 | ||
2909 | <P> | |
2910 | Signals are asynchronous events sent to a process by the Unix kernel, | |
2911 | sometimes on behalf of another process. They are intended to indicate | |
2912 | exceptional events, like a user pressing the interrupt key on his | |
2913 | terminal, or a network connection being broken. There is a class of | |
2914 | signals that can be sent to the process currently reading input from | |
2915 | the keyboard. Since Readline changes the terminal attributes when it | |
2916 | is called, it needs to perform special processing when a signal is | |
2917 | received to restore the terminal to a sane state, or provide application | |
2918 | writers with functions to do so manually. | |
2919 | ||
2920 | </P> | |
2921 | <P> | |
2922 | Readline contains an internal signal handler that is installed for a | |
2923 | number of signals (<CODE>SIGINT</CODE>, <CODE>SIGQUIT</CODE>, <CODE>SIGTERM</CODE>, | |
2924 | <CODE>SIGALRM</CODE>, <CODE>SIGTSTP</CODE>, <CODE>SIGTTIN</CODE>, and <CODE>SIGTTOU</CODE>). | |
2925 | When one of these signals is received, the signal handler | |
2926 | will reset the terminal attributes to those that were in effect before | |
2927 | <CODE>readline ()</CODE> was called, reset the signal handling to what it was | |
2928 | before <CODE>readline ()</CODE> was called, and resend the signal to the calling | |
2929 | application. | |
2930 | If and when the calling application's signal handler returns, Readline | |
2931 | will reinitialize the terminal and continue to accept input. | |
2932 | When a <CODE>SIGINT</CODE> is received, the Readline signal handler performs | |
2933 | some additional work, which will cause any partially-entered line to be | |
2934 | aborted (see the description of <CODE>rl_free_line_state ()</CODE>). | |
2935 | ||
2936 | </P> | |
2937 | <P> | |
2938 | There is an additional Readline signal handler, for <CODE>SIGWINCH</CODE>, which | |
2939 | the kernel sends to a process whenever the terminal's size changes (for | |
2940 | example, if a user resizes an <CODE>xterm</CODE>). The Readline <CODE>SIGWINCH</CODE> | |
2941 | handler updates Readline's internal screen size state, and then calls any | |
2942 | <CODE>SIGWINCH</CODE> signal handler the calling application has installed. | |
2943 | Readline calls the application's <CODE>SIGWINCH</CODE> signal handler without | |
2944 | resetting the terminal to its original state. If the application's signal | |
2945 | handler does more than update its idea of the terminal size and return (for | |
2946 | example, a <CODE>longjmp</CODE> back to a main processing loop), it <EM>must</EM> | |
2947 | call <CODE>rl_cleanup_after_signal ()</CODE> (described below), to restore the | |
2948 | terminal state. | |
2949 | ||
2950 | </P> | |
2951 | <P> | |
2952 | Readline provides two variables that allow application writers to | |
2953 | control whether or not it will catch certain signals and act on them | |
2954 | when they are received. It is important that applications change the | |
2955 | values of these variables only when calling <CODE>readline ()</CODE>, not in | |
2956 | a signal handler, so Readline's internal signal state is not corrupted. | |
2957 | ||
2958 | </P> | |
2959 | <P> | |
2960 | <DL> | |
2961 | <DT><U>Variable:</U> int <B>rl_catch_signals</B> | |
f9267e15 | 2962 | <DD><A NAME="IDX183"></A> |
a44161c3 EZ |
2963 | If this variable is non-zero, Readline will install signal handlers for |
2964 | <CODE>SIGINT</CODE>, <CODE>SIGQUIT</CODE>, <CODE>SIGTERM</CODE>, <CODE>SIGALRM</CODE>, | |
2965 | <CODE>SIGTSTP</CODE>, <CODE>SIGTTIN</CODE>, and <CODE>SIGTTOU</CODE>. | |
2966 | ||
2967 | </P> | |
2968 | <P> | |
2969 | The default value of <CODE>rl_catch_signals</CODE> is 1. | |
2970 | </DL> | |
2971 | ||
2972 | </P> | |
2973 | <P> | |
2974 | <DL> | |
2975 | <DT><U>Variable:</U> int <B>rl_catch_sigwinch</B> | |
f9267e15 | 2976 | <DD><A NAME="IDX184"></A> |
a44161c3 EZ |
2977 | If this variable is non-zero, Readline will install a signal handler for |
2978 | <CODE>SIGWINCH</CODE>. | |
2979 | ||
2980 | </P> | |
2981 | <P> | |
2982 | The default value of <CODE>rl_catch_sigwinch</CODE> is 1. | |
2983 | </DL> | |
2984 | ||
2985 | </P> | |
2986 | <P> | |
2987 | If an application does not wish to have Readline catch any signals, or | |
2988 | to handle signals other than those Readline catches (<CODE>SIGHUP</CODE>, | |
2989 | for example), | |
2990 | Readline provides convenience functions to do the necessary terminal | |
2991 | and internal state cleanup upon receipt of a signal. | |
2992 | ||
2993 | </P> | |
2994 | <P> | |
2995 | <DL> | |
2996 | <DT><U>Function:</U> void <B>rl_cleanup_after_signal</B> <I>(void)</I> | |
f9267e15 | 2997 | <DD><A NAME="IDX185"></A> |
a44161c3 EZ |
2998 | This function will reset the state of the terminal to what it was before |
2999 | <CODE>readline ()</CODE> was called, and remove the Readline signal handlers for | |
3000 | all signals, depending on the values of <CODE>rl_catch_signals</CODE> and | |
3001 | <CODE>rl_catch_sigwinch</CODE>. | |
3002 | </DL> | |
3003 | ||
3004 | </P> | |
3005 | <P> | |
3006 | <DL> | |
3007 | <DT><U>Function:</U> void <B>rl_free_line_state</B> <I>(void)</I> | |
f9267e15 | 3008 | <DD><A NAME="IDX186"></A> |
a44161c3 EZ |
3009 | This will free any partial state associated with the current input line |
3010 | (undo information, any partial history entry, any partially-entered | |
3011 | keyboard macro, and any partially-entered numeric argument). This | |
3012 | should be called before <CODE>rl_cleanup_after_signal ()</CODE>. The | |
3013 | Readline signal handler for <CODE>SIGINT</CODE> calls this to abort the | |
3014 | current input line. | |
3015 | </DL> | |
3016 | ||
3017 | </P> | |
3018 | <P> | |
3019 | <DL> | |
3020 | <DT><U>Function:</U> void <B>rl_reset_after_signal</B> <I>(void)</I> | |
f9267e15 | 3021 | <DD><A NAME="IDX187"></A> |
a44161c3 EZ |
3022 | This will reinitialize the terminal and reinstall any Readline signal |
3023 | handlers, depending on the values of <CODE>rl_catch_signals</CODE> and | |
3024 | <CODE>rl_catch_sigwinch</CODE>. | |
3025 | </DL> | |
3026 | ||
3027 | </P> | |
3028 | <P> | |
3029 | If an application does not wish Readline to catch <CODE>SIGWINCH</CODE>, it may | |
3030 | call <CODE>rl_resize_terminal ()</CODE> to force Readline to update its idea of | |
3031 | the terminal size when a <CODE>SIGWINCH</CODE> is received. | |
3032 | ||
3033 | </P> | |
3034 | <P> | |
3035 | <DL> | |
3036 | <DT><U>Function:</U> void <B>rl_resize_terminal</B> <I>(void)</I> | |
f9267e15 | 3037 | <DD><A NAME="IDX188"></A> |
a44161c3 EZ |
3038 | Update Readline's internal screen size. |
3039 | </DL> | |
3040 | ||
3041 | </P> | |
3042 | <P> | |
3043 | The following functions install and remove Readline's signal handlers. | |
3044 | ||
3045 | </P> | |
3046 | <P> | |
3047 | <DL> | |
3048 | <DT><U>Function:</U> int <B>rl_set_signals</B> <I>(void)</I> | |
f9267e15 | 3049 | <DD><A NAME="IDX189"></A> |
a44161c3 EZ |
3050 | Install Readline's signal handler for <CODE>SIGINT</CODE>, <CODE>SIGQUIT</CODE>, |
3051 | <CODE>SIGTERM</CODE>, <CODE>SIGALRM</CODE>, <CODE>SIGTSTP</CODE>, <CODE>SIGTTIN</CODE>, | |
3052 | <CODE>SIGTTOU</CODE>, and <CODE>SIGWINCH</CODE>, depending on the values of | |
3053 | <CODE>rl_catch_signals</CODE> and <CODE>rl_catch_sigwinch</CODE>. | |
3054 | </DL> | |
3055 | ||
3056 | </P> | |
3057 | <P> | |
3058 | <DL> | |
3059 | <DT><U>Function:</U> int <B>rl_clear_signals</B> <I>(void)</I> | |
f9267e15 | 3060 | <DD><A NAME="IDX190"></A> |
a44161c3 EZ |
3061 | Remove all of the Readline signal handlers installed by |
3062 | <CODE>rl_set_signals ()</CODE>. | |
3063 | </DL> | |
3064 | ||
3065 | </P> | |
3066 | ||
3067 | ||
3068 | <H2><A NAME="SEC41" HREF="readline.html#TOC41">Custom Completers</A></H2> | |
3069 | ||
3070 | <P> | |
3071 | Typically, a program that reads commands from the user has a way of | |
3072 | disambiguating commands and data. If your program is one of these, then | |
3073 | it can provide completion for commands, data, or both. | |
3074 | The following sections describe how your program and Readline | |
3075 | cooperate to provide this service. | |
3076 | ||
3077 | </P> | |
3078 | ||
3079 | <UL> | |
3080 | <LI><A HREF="readline.html#SEC42">How Completing Works</A>: The logic used to do completion. | |
3081 | <LI><A HREF="readline.html#SEC43">Completion Functions</A>: Functions provided by Readline. | |
3082 | <LI><A HREF="readline.html#SEC44">Completion Variables</A>: Variables which control completion. | |
3083 | <LI><A HREF="readline.html#SEC45">A Short Completion Example</A>: An example of writing completer subroutines. | |
3084 | </UL> | |
3085 | ||
3086 | ||
3087 | ||
3088 | <H3><A NAME="SEC42" HREF="readline.html#TOC42">How Completing Works</A></H3> | |
3089 | ||
3090 | <P> | |
3091 | In order to complete some text, the full list of possible completions | |
3092 | must be available. That is, it is not possible to accurately | |
3093 | expand a partial word without knowing all of the possible words | |
3094 | which make sense in that context. The Readline library provides | |
3095 | the user interface to completion, and two of the most common | |
3096 | completion functions: filename and username. For completing other types | |
3097 | of text, you must write your own completion function. This section | |
3098 | describes exactly what such functions must do, and provides an example. | |
3099 | ||
3100 | </P> | |
3101 | <P> | |
3102 | There are three major functions used to perform completion: | |
3103 | ||
3104 | </P> | |
3105 | ||
3106 | <OL> | |
3107 | <LI> | |
3108 | ||
3109 | The user-interface function <CODE>rl_complete ()</CODE>. This function is | |
3110 | called with the same arguments as other Readline | |
3111 | functions intended for interactive use: <VAR>count</VAR> and | |
3112 | <VAR>invoking_key</VAR>. It isolates the word to be completed and calls | |
3113 | <CODE>completion_matches ()</CODE> to generate a list of possible completions. | |
3114 | It then either lists the possible completions, inserts the possible | |
3115 | completions, or actually performs the | |
3116 | completion, depending on which behavior is desired. | |
3117 | ||
3118 | <LI> | |
3119 | ||
3120 | The internal function <CODE>completion_matches ()</CODE> uses your | |
3121 | <EM>generator</EM> function to generate the list of possible matches, and | |
3122 | then returns the array of these matches. You should place the address | |
3123 | of your generator function in <CODE>rl_completion_entry_function</CODE>. | |
3124 | ||
3125 | <LI> | |
3126 | ||
3127 | The generator function is called repeatedly from | |
3128 | <CODE>completion_matches ()</CODE>, returning a string each time. The | |
3129 | arguments to the generator function are <VAR>text</VAR> and <VAR>state</VAR>. | |
3130 | <VAR>text</VAR> is the partial word to be completed. <VAR>state</VAR> is zero the | |
3131 | first time the function is called, allowing the generator to perform | |
3132 | any necessary initialization, and a positive non-zero integer for | |
3133 | each subsequent call. When the generator function returns | |
3134 | <CODE>(char *)NULL</CODE> this signals <CODE>completion_matches ()</CODE> that there are | |
3135 | no more possibilities left. Usually the generator function computes the | |
3136 | list of possible completions when <VAR>state</VAR> is zero, and returns them | |
3137 | one at a time on subsequent calls. Each string the generator function | |
3138 | returns as a match must be allocated with <CODE>malloc()</CODE>; Readline | |
3139 | frees the strings when it has finished with them. | |
3140 | ||
3141 | </OL> | |
3142 | ||
3143 | <P> | |
3144 | <DL> | |
3145 | <DT><U>Function:</U> int <B>rl_complete</B> <I>(int ignore, int invoking_key)</I> | |
f9267e15 | 3146 | <DD><A NAME="IDX191"></A> |
a44161c3 EZ |
3147 | Complete the word at or before point. You have supplied the function |
3148 | that does the initial simple matching selection algorithm (see | |
3149 | <CODE>completion_matches ()</CODE>). The default is to do filename completion. | |
3150 | </DL> | |
3151 | ||
3152 | </P> | |
3153 | <P> | |
3154 | <DL> | |
3155 | <DT><U>Variable:</U> Function * <B>rl_completion_entry_function</B> | |
f9267e15 | 3156 | <DD><A NAME="IDX192"></A> |
a44161c3 EZ |
3157 | This is a pointer to the generator function for <CODE>completion_matches |
3158 | ()</CODE>. If the value of <CODE>rl_completion_entry_function</CODE> is | |
3159 | <CODE>(Function *)NULL</CODE> then the default filename generator function, | |
3160 | <CODE>filename_completion_function ()</CODE>, is used. | |
3161 | </DL> | |
3162 | ||
3163 | </P> | |
3164 | ||
3165 | ||
3166 | <H3><A NAME="SEC43" HREF="readline.html#TOC43">Completion Functions</A></H3> | |
3167 | ||
3168 | <P> | |
3169 | Here is the complete list of callable completion functions present in | |
3170 | Readline. | |
3171 | ||
3172 | </P> | |
3173 | <P> | |
3174 | <DL> | |
3175 | <DT><U>Function:</U> int <B>rl_complete_internal</B> <I>(int what_to_do)</I> | |
f9267e15 | 3176 | <DD><A NAME="IDX193"></A> |
a44161c3 EZ |
3177 | Complete the word at or before point. <VAR>what_to_do</VAR> says what to do |
3178 | with the completion. A value of <SAMP>`?'</SAMP> means list the possible | |
3179 | completions. <SAMP>`TAB'</SAMP> means do standard completion. <SAMP>`*'</SAMP> means | |
3180 | insert all of the possible completions. <SAMP>`!'</SAMP> means to display | |
3181 | all of the possible completions, if there is more than one, as well as | |
3182 | performing partial completion. | |
3183 | </DL> | |
3184 | ||
3185 | </P> | |
3186 | <P> | |
3187 | <DL> | |
3188 | <DT><U>Function:</U> int <B>rl_complete</B> <I>(int ignore, int invoking_key)</I> | |
f9267e15 | 3189 | <DD><A NAME="IDX194"></A> |
a44161c3 EZ |
3190 | Complete the word at or before point. You have supplied the function |
3191 | that does the initial simple matching selection algorithm (see | |
3192 | <CODE>completion_matches ()</CODE> and <CODE>rl_completion_entry_function</CODE>). | |
3193 | The default is to do filename | |
3194 | completion. This calls <CODE>rl_complete_internal ()</CODE> with an | |
3195 | argument depending on <VAR>invoking_key</VAR>. | |
3196 | </DL> | |
3197 | ||
3198 | </P> | |
3199 | <P> | |
3200 | <DL> | |
3201 | <DT><U>Function:</U> int <B>rl_possible_completions</B> <I>(int count, int invoking_key))</I> | |
f9267e15 | 3202 | <DD><A NAME="IDX195"></A> |
a44161c3 EZ |
3203 | List the possible completions. See description of <CODE>rl_complete |
3204 | ()</CODE>. This calls <CODE>rl_complete_internal ()</CODE> with an argument of | |
3205 | <SAMP>`?'</SAMP>. | |
3206 | </DL> | |
3207 | ||
3208 | </P> | |
3209 | <P> | |
3210 | <DL> | |
3211 | <DT><U>Function:</U> int <B>rl_insert_completions</B> <I>(int count, int invoking_key))</I> | |
f9267e15 | 3212 | <DD><A NAME="IDX196"></A> |
a44161c3 EZ |
3213 | Insert the list of possible completions into the line, deleting the |
3214 | partially-completed word. See description of <CODE>rl_complete ()</CODE>. | |
3215 | This calls <CODE>rl_complete_internal ()</CODE> with an argument of <SAMP>`*'</SAMP>. | |
3216 | </DL> | |
3217 | ||
3218 | </P> | |
3219 | <P> | |
3220 | <DL> | |
3221 | <DT><U>Function:</U> char ** <B>completion_matches</B> <I>(char *text, CPFunction *entry_func)</I> | |
f9267e15 | 3222 | <DD><A NAME="IDX197"></A> |
a44161c3 EZ |
3223 | Returns an array of <CODE>(char *)</CODE> which is a list of completions for |
3224 | <VAR>text</VAR>. If there are no completions, returns <CODE>(char **)NULL</CODE>. | |
3225 | The first entry in the returned array is the substitution for <VAR>text</VAR>. | |
3226 | The remaining entries are the possible completions. The array is | |
3227 | terminated with a <CODE>NULL</CODE> pointer. | |
3228 | ||
3229 | </P> | |
3230 | <P> | |
3231 | <VAR>entry_func</VAR> is a function of two args, and returns a | |
3232 | <CODE>(char *)</CODE>. The first argument is <VAR>text</VAR>. The second is a | |
3233 | state argument; it is zero on the first call, and non-zero on subsequent | |
3234 | calls. <VAR>entry_func</VAR> returns a <CODE>NULL</CODE> pointer to the caller | |
3235 | when there are no more matches. | |
3236 | </DL> | |
3237 | ||
3238 | </P> | |
3239 | <P> | |
3240 | <DL> | |
3241 | <DT><U>Function:</U> char * <B>filename_completion_function</B> <I>(char *text, int state)</I> | |
f9267e15 | 3242 | <DD><A NAME="IDX198"></A> |
a44161c3 EZ |
3243 | A generator function for filename completion in the general case. Note |
3244 | that completion in Bash is a little different because of all | |
3245 | the pathnames that must be followed when looking up completions for a | |
3246 | command. The Bash source is a useful reference for writing custom | |
3247 | completion functions. | |
3248 | </DL> | |
3249 | ||
3250 | </P> | |
3251 | <P> | |
3252 | <DL> | |
3253 | <DT><U>Function:</U> char * <B>username_completion_function</B> <I>(char *text, int state)</I> | |
f9267e15 | 3254 | <DD><A NAME="IDX199"></A> |
a44161c3 EZ |
3255 | A completion generator for usernames. <VAR>text</VAR> contains a partial |
3256 | username preceded by a random character (usually <SAMP>`~'</SAMP>). As with all | |
3257 | completion generators, <VAR>state</VAR> is zero on the first call and non-zero | |
3258 | for subsequent calls. | |
3259 | </DL> | |
3260 | ||
3261 | </P> | |
3262 | ||
3263 | ||
3264 | <H3><A NAME="SEC44" HREF="readline.html#TOC44">Completion Variables</A></H3> | |
3265 | ||
3266 | <P> | |
3267 | <DL> | |
3268 | <DT><U>Variable:</U> Function * <B>rl_completion_entry_function</B> | |
f9267e15 | 3269 | <DD><A NAME="IDX200"></A> |
a44161c3 | 3270 | A pointer to the generator function for <CODE>completion_matches ()</CODE>. |
f9267e15 | 3271 | <CODE>NULL</CODE> means to use <CODE>filename_completion_function ()</CODE>, the default |
a44161c3 EZ |
3272 | filename completer. |
3273 | </DL> | |
3274 | ||
3275 | </P> | |
3276 | <P> | |
3277 | <DL> | |
3278 | <DT><U>Variable:</U> CPPFunction * <B>rl_attempted_completion_function</B> | |
f9267e15 | 3279 | <DD><A NAME="IDX201"></A> |
a44161c3 EZ |
3280 | A pointer to an alternative function to create matches. |
3281 | The function is called with <VAR>text</VAR>, <VAR>start</VAR>, and <VAR>end</VAR>. | |
3282 | <VAR>start</VAR> and <VAR>end</VAR> are indices in <CODE>rl_line_buffer</CODE> saying | |
3283 | what the boundaries of <VAR>text</VAR> are. If this function exists and | |
3284 | returns <CODE>NULL</CODE>, or if this variable is set to <CODE>NULL</CODE>, then | |
3285 | <CODE>rl_complete ()</CODE> will call the value of | |
3286 | <CODE>rl_completion_entry_function</CODE> to generate matches, otherwise the | |
3287 | array of strings returned will be used. | |
3288 | </DL> | |
3289 | ||
3290 | </P> | |
3291 | <P> | |
3292 | <DL> | |
3293 | <DT><U>Variable:</U> CPFunction * <B>rl_filename_quoting_function</B> | |
f9267e15 | 3294 | <DD><A NAME="IDX202"></A> |
a44161c3 EZ |
3295 | A pointer to a function that will quote a filename in an application- |
3296 | specific fashion. This is called if filename completion is being | |
3297 | attempted and one of the characters in <CODE>rl_filename_quote_characters</CODE> | |
3298 | appears in a completed filename. The function is called with | |
3299 | <VAR>text</VAR>, <VAR>match_type</VAR>, and <VAR>quote_pointer</VAR>. The <VAR>text</VAR> | |
3300 | is the filename to be quoted. The <VAR>match_type</VAR> is either | |
3301 | <CODE>SINGLE_MATCH</CODE>, if there is only one completion match, or | |
3302 | <CODE>MULT_MATCH</CODE>. Some functions use this to decide whether or not to | |
3303 | insert a closing quote character. The <VAR>quote_pointer</VAR> is a pointer | |
3304 | to any opening quote character the user typed. Some functions choose | |
3305 | to reset this character. | |
3306 | </DL> | |
3307 | ||
3308 | </P> | |
3309 | <P> | |
3310 | <DL> | |
3311 | <DT><U>Variable:</U> CPFunction * <B>rl_filename_dequoting_function</B> | |
f9267e15 | 3312 | <DD><A NAME="IDX203"></A> |
a44161c3 EZ |
3313 | A pointer to a function that will remove application-specific quoting |
3314 | characters from a filename before completion is attempted, so those | |
3315 | characters do not interfere with matching the text against names in | |
3316 | the filesystem. It is called with <VAR>text</VAR>, the text of the word | |
3317 | to be dequoted, and <VAR>quote_char</VAR>, which is the quoting character | |
3318 | that delimits the filename (usually <SAMP>`''</SAMP> or <SAMP>`"'</SAMP>). If | |
3319 | <VAR>quote_char</VAR> is zero, the filename was not in an embedded string. | |
3320 | </DL> | |
3321 | ||
3322 | </P> | |
3323 | <P> | |
3324 | <DL> | |
3325 | <DT><U>Variable:</U> Function * <B>rl_char_is_quoted_p</B> | |
f9267e15 | 3326 | <DD><A NAME="IDX204"></A> |
a44161c3 EZ |
3327 | A pointer to a function to call that determines whether or not a specific |
3328 | character in the line buffer is quoted, according to whatever quoting | |
3329 | mechanism the program calling readline uses. The function is called with | |
3330 | two arguments: <VAR>text</VAR>, the text of the line, and <VAR>index</VAR>, the | |
3331 | index of the character in the line. It is used to decide whether a | |
3332 | character found in <CODE>rl_completer_word_break_characters</CODE> should be | |
3333 | used to break words for the completer. | |
3334 | </DL> | |
3335 | ||
3336 | </P> | |
3337 | <P> | |
3338 | <DL> | |
3339 | <DT><U>Variable:</U> int <B>rl_completion_query_items</B> | |
f9267e15 | 3340 | <DD><A NAME="IDX205"></A> |
a44161c3 EZ |
3341 | Up to this many items will be displayed in response to a |
3342 | possible-completions call. After that, we ask the user if she is sure | |
3343 | she wants to see them all. The default value is 100. | |
3344 | </DL> | |
3345 | ||
3346 | </P> | |
3347 | <P> | |
3348 | <DL> | |
3349 | <DT><U>Variable:</U> char * <B>rl_basic_word_break_characters</B> | |
f9267e15 | 3350 | <DD><A NAME="IDX206"></A> |
a44161c3 EZ |
3351 | The basic list of characters that signal a break between words for the |
3352 | completer routine. The default value of this variable is the characters | |
3353 | which break words for completion in Bash, i.e., | |
3354 | <CODE>" \t\n\"\\'`@$><=;|&{("</CODE>. | |
3355 | </DL> | |
3356 | ||
3357 | </P> | |
3358 | <P> | |
3359 | <DL> | |
3360 | <DT><U>Variable:</U> char * <B>rl_basic_quote_characters</B> | |
f9267e15 | 3361 | <DD><A NAME="IDX207"></A> |
a44161c3 EZ |
3362 | List of quote characters which can cause a word break. |
3363 | </DL> | |
3364 | ||
3365 | </P> | |
3366 | <P> | |
3367 | <DL> | |
3368 | <DT><U>Variable:</U> char * <B>rl_completer_word_break_characters</B> | |
f9267e15 | 3369 | <DD><A NAME="IDX208"></A> |
a44161c3 EZ |
3370 | The list of characters that signal a break between words for |
3371 | <CODE>rl_complete_internal ()</CODE>. The default list is the value of | |
3372 | <CODE>rl_basic_word_break_characters</CODE>. | |
3373 | </DL> | |
3374 | ||
3375 | </P> | |
3376 | <P> | |
3377 | <DL> | |
3378 | <DT><U>Variable:</U> char * <B>rl_completer_quote_characters</B> | |
f9267e15 | 3379 | <DD><A NAME="IDX209"></A> |
a44161c3 EZ |
3380 | List of characters which can be used to quote a substring of the line. |
3381 | Completion occurs on the entire substring, and within the substring | |
3382 | <CODE>rl_completer_word_break_characters</CODE> are treated as any other character, | |
3383 | unless they also appear within this list. | |
3384 | </DL> | |
3385 | ||
3386 | </P> | |
3387 | <P> | |
3388 | <DL> | |
3389 | <DT><U>Variable:</U> char * <B>rl_filename_quote_characters</B> | |
f9267e15 | 3390 | <DD><A NAME="IDX210"></A> |
a44161c3 EZ |
3391 | A list of characters that cause a filename to be quoted by the completer |
3392 | when they appear in a completed filename. The default is the null string. | |
3393 | </DL> | |
3394 | ||
3395 | </P> | |
3396 | <P> | |
3397 | <DL> | |
3398 | <DT><U>Variable:</U> char * <B>rl_special_prefixes</B> | |
f9267e15 | 3399 | <DD><A NAME="IDX211"></A> |
a44161c3 EZ |
3400 | The list of characters that are word break characters, but should be |
3401 | left in <VAR>text</VAR> when it is passed to the completion function. | |
3402 | Programs can use this to help determine what kind of completing to do. | |
3403 | For instance, Bash sets this variable to "$@" so that it can complete | |
3404 | shell variables and hostnames. | |
3405 | </DL> | |
3406 | ||
3407 | </P> | |
3408 | <P> | |
3409 | <DL> | |
3410 | <DT><U>Variable:</U> int <B>rl_completion_append_character</B> | |
f9267e15 | 3411 | <DD><A NAME="IDX212"></A> |
a44161c3 EZ |
3412 | When a single completion alternative matches at the end of the command |
3413 | line, this character is appended to the inserted completion text. The | |
3414 | default is a space character (<SAMP>` '</SAMP>). Setting this to the null | |
3415 | character (<SAMP>`\0'</SAMP>) prevents anything being appended automatically. | |
3416 | This can be changed in custom completion functions to | |
3417 | provide the "most sensible word separator character" according to | |
3418 | an application-specific command line syntax specification. | |
3419 | </DL> | |
3420 | ||
3421 | </P> | |
3422 | <P> | |
3423 | <DL> | |
3424 | <DT><U>Variable:</U> int <B>rl_ignore_completion_duplicates</B> | |
f9267e15 | 3425 | <DD><A NAME="IDX213"></A> |
a44161c3 EZ |
3426 | If non-zero, then disallow duplicates in the matches. Default is 1. |
3427 | </DL> | |
3428 | ||
3429 | </P> | |
3430 | <P> | |
3431 | <DL> | |
3432 | <DT><U>Variable:</U> int <B>rl_filename_completion_desired</B> | |
f9267e15 | 3433 | <DD><A NAME="IDX214"></A> |
a44161c3 EZ |
3434 | Non-zero means that the results of the matches are to be treated as |
3435 | filenames. This is <EM>always</EM> zero on entry, and can only be changed | |
3436 | within a completion entry generator function. If it is set to a non-zero | |
3437 | value, directory names have a slash appended and Readline attempts to | |
3438 | quote completed filenames if they contain any embedded word break | |
3439 | characters. | |
3440 | </DL> | |
3441 | ||
3442 | </P> | |
3443 | <P> | |
3444 | <DL> | |
3445 | <DT><U>Variable:</U> int <B>rl_filename_quoting_desired</B> | |
f9267e15 | 3446 | <DD><A NAME="IDX215"></A> |
a44161c3 EZ |
3447 | Non-zero means that the results of the matches are to be quoted using |
3448 | double quotes (or an application-specific quoting mechanism) if the | |
3449 | completed filename contains any characters in | |
3450 | <CODE>rl_filename_quote_chars</CODE>. This is <EM>always</EM> non-zero | |
3451 | on entry, and can only be changed within a completion entry generator | |
3452 | function. The quoting is effected via a call to the function pointed to | |
3453 | by <CODE>rl_filename_quoting_function</CODE>. | |
3454 | </DL> | |
3455 | ||
3456 | </P> | |
3457 | <P> | |
3458 | <DL> | |
3459 | <DT><U>Variable:</U> int <B>rl_inhibit_completion</B> | |
f9267e15 | 3460 | <DD><A NAME="IDX216"></A> |
a44161c3 EZ |
3461 | If this variable is non-zero, completion is inhibit<ed. The completion |
3462 | character will be inserted as any other bound to <CODE>self-insert</CODE>. | |
3463 | </DL> | |
3464 | ||
3465 | </P> | |
3466 | <P> | |
3467 | <DL> | |
3468 | <DT><U>Variable:</U> Function * <B>rl_ignore_some_completions_function</B> | |
f9267e15 | 3469 | <DD><A NAME="IDX217"></A> |
a44161c3 EZ |
3470 | This function, if defined, is called by the completer when real filename |
3471 | completion is done, after all the matching names have been generated. | |
3472 | It is passed a <CODE>NULL</CODE> terminated array of matches. | |
3473 | The first element (<CODE>matches[0]</CODE>) is the | |
3474 | maximal substring common to all matches. This function can | |
3475 | re-arrange the list of matches as required, but each element deleted | |
3476 | from the array must be freed. | |
3477 | </DL> | |
3478 | ||
3479 | </P> | |
3480 | <P> | |
3481 | <DL> | |
3482 | <DT><U>Variable:</U> Function * <B>rl_directory_completion_hook</B> | |
f9267e15 | 3483 | <DD><A NAME="IDX218"></A> |
a44161c3 EZ |
3484 | This function, if defined, is allowed to modify the directory portion |
3485 | of filenames Readline completes. It is called with the address of a | |
3486 | string (the current directory name) as an argument. It could be used | |
3487 | to expand symbolic links or shell variables in pathnames. | |
3488 | </DL> | |
3489 | ||
3490 | </P> | |
3491 | <P> | |
3492 | <DL> | |
3493 | <DT><U>Variable:</U> VFunction * <B>rl_completion_display_matches_hook</B> | |
f9267e15 | 3494 | <DD><A NAME="IDX219"></A> |
a44161c3 EZ |
3495 | If non-zero, then this is the address of a function to call when |
3496 | completing a word would normally display the list of possible matches. | |
3497 | This function is called in lieu of Readline displaying the list. | |
3498 | It takes three arguments: | |
3499 | (<CODE>char **</CODE><VAR>matches</VAR>, <CODE>int</CODE> <VAR>num_matches</VAR>, <CODE>int</CODE> <VAR>max_length</VAR>) | |
3500 | where <VAR>matches</VAR> is the array of matching strings, | |
3501 | <VAR>num_matches</VAR> is the number of strings in that array, and | |
3502 | <VAR>max_length</VAR> is the length of the longest string in that array. | |
3503 | Readline provides a convenience function, <CODE>rl_display_match_list</CODE>, | |
3504 | that takes care of doing the display to Readline's output stream. That | |
3505 | function may be called from this hook. | |
3506 | </DL> | |
3507 | ||
3508 | </P> | |
3509 | ||
3510 | ||
3511 | <H3><A NAME="SEC45" HREF="readline.html#TOC45">A Short Completion Example</A></H3> | |
3512 | ||
3513 | <P> | |
3514 | Here is a small application demonstrating the use of the GNU Readline | |
3515 | library. It is called <CODE>fileman</CODE>, and the source code resides in | |
3516 | <TT>`examples/fileman.c'</TT>. This sample application provides | |
3517 | completion of command names, line editing features, and access to the | |
3518 | history list. | |
3519 | ||
3520 | </P> | |
3521 | ||
3522 | <PRE> | |
3523 | /* fileman.c -- A tiny application which demonstrates how to use the | |
3524 | GNU Readline library. This application interactively allows users | |
3525 | to manipulate files and their modes. */ | |
3526 | ||
3527 | #include <stdio.h> | |
3528 | #include <sys/types.h> | |
3529 | #include <sys/file.h> | |
3530 | #include <sys/stat.h> | |
3531 | #include <sys/errno.h> | |
3532 | ||
3533 | #include <readline/readline.h> | |
3534 | #include <readline/history.h> | |
3535 | ||
3536 | extern char *getwd (); | |
3537 | extern char *xmalloc (); | |
3538 | ||
3539 | /* The names of functions that actually do the manipulation. */ | |
3540 | int com_list (), com_view (), com_rename (), com_stat (), com_pwd (); | |
3541 | int com_delete (), com_help (), com_cd (), com_quit (); | |
3542 | ||
3543 | /* A structure which contains information on the commands this program | |
3544 | can understand. */ | |
3545 | ||
3546 | typedef struct { | |
3547 | char *name; /* User printable name of the function. */ | |
3548 | Function *func; /* Function to call to do the job. */ | |
3549 | char *doc; /* Documentation for this function. */ | |
3550 | } COMMAND; | |
3551 | ||
3552 | COMMAND commands[] = { | |
3553 | { "cd", com_cd, "Change to directory DIR" }, | |
3554 | { "delete", com_delete, "Delete FILE" }, | |
3555 | { "help", com_help, "Display this text" }, | |
3556 | { "?", com_help, "Synonym for `help'" }, | |
3557 | { "list", com_list, "List files in DIR" }, | |
3558 | { "ls", com_list, "Synonym for `list'" }, | |
3559 | { "pwd", com_pwd, "Print the current working directory" }, | |
3560 | { "quit", com_quit, "Quit using Fileman" }, | |
3561 | { "rename", com_rename, "Rename FILE to NEWNAME" }, | |
3562 | { "stat", com_stat, "Print out statistics on FILE" }, | |
3563 | { "view", com_view, "View the contents of FILE" }, | |
3564 | { (char *)NULL, (Function *)NULL, (char *)NULL } | |
3565 | }; | |
3566 | ||
3567 | /* Forward declarations. */ | |
3568 | char *stripwhite (); | |
3569 | COMMAND *find_command (); | |
3570 | ||
3571 | /* The name of this program, as taken from argv[0]. */ | |
3572 | char *progname; | |
3573 | ||
3574 | /* When non-zero, this global means the user is done using this program. */ | |
3575 | int done; | |
3576 | ||
3577 | char * | |
3578 | dupstr (s) | |
3579 | int s; | |
3580 | { | |
3581 | char *r; | |
3582 | ||
3583 | r = xmalloc (strlen (s) + 1); | |
3584 | strcpy (r, s); | |
3585 | return (r); | |
3586 | } | |
3587 | ||
3588 | main (argc, argv) | |
3589 | int argc; | |
3590 | char **argv; | |
3591 | { | |
3592 | char *line, *s; | |
3593 | ||
3594 | progname = argv[0]; | |
3595 | ||
3596 | initialize_readline (); /* Bind our completer. */ | |
3597 | ||
3598 | /* Loop reading and executing lines until the user quits. */ | |
3599 | for ( ; done == 0; ) | |
3600 | { | |
3601 | line = readline ("FileMan: "); | |
3602 | ||
3603 | if (!line) | |
3604 | break; | |
3605 | ||
3606 | /* Remove leading and trailing whitespace from the line. | |
3607 | Then, if there is anything left, add it to the history list | |
3608 | and execute it. */ | |
3609 | s = stripwhite (line); | |
3610 | ||
3611 | if (*s) | |
3612 | { | |
3613 | add_history (s); | |
3614 | execute_line (s); | |
3615 | } | |
3616 | ||
3617 | free (line); | |
3618 | } | |
3619 | exit (0); | |
3620 | } | |
3621 | ||
3622 | /* Execute a command line. */ | |
3623 | int | |
3624 | execute_line (line) | |
3625 | char *line; | |
3626 | { | |
3627 | register int i; | |
3628 | COMMAND *command; | |
3629 | char *word; | |
3630 | ||
3631 | /* Isolate the command word. */ | |
3632 | i = 0; | |
3633 | while (line[i] && whitespace (line[i])) | |
3634 | i++; | |
3635 | word = line + i; | |
3636 | ||
3637 | while (line[i] && !whitespace (line[i])) | |
3638 | i++; | |
3639 | ||
3640 | if (line[i]) | |
3641 | line[i++] = '\0'; | |
3642 | ||
3643 | command = find_command (word); | |
3644 | ||
3645 | if (!command) | |
3646 | { | |
3647 | fprintf (stderr, "%s: No such command for FileMan.\n", word); | |
3648 | return (-1); | |
3649 | } | |
3650 | ||
3651 | /* Get argument to command, if any. */ | |
3652 | while (whitespace (line[i])) | |
3653 | i++; | |
3654 | ||
3655 | word = line + i; | |
3656 | ||
3657 | /* Call the function. */ | |
3658 | return ((*(command->func)) (word)); | |
3659 | } | |
3660 | ||
3661 | /* Look up NAME as the name of a command, and return a pointer to that | |
3662 | command. Return a NULL pointer if NAME isn't a command name. */ | |
3663 | COMMAND * | |
3664 | find_command (name) | |
3665 | char *name; | |
3666 | { | |
3667 | register int i; | |
3668 | ||
3669 | for (i = 0; commands[i].name; i++) | |
3670 | if (strcmp (name, commands[i].name) == 0) | |
3671 | return (&commands[i]); | |
3672 | ||
3673 | return ((COMMAND *)NULL); | |
3674 | } | |
3675 | ||
3676 | /* Strip whitespace from the start and end of STRING. Return a pointer | |
3677 | into STRING. */ | |
3678 | char * | |
3679 | stripwhite (string) | |
3680 | char *string; | |
3681 | { | |
3682 | register char *s, *t; | |
3683 | ||
3684 | for (s = string; whitespace (*s); s++) | |
3685 | ; | |
3686 | ||
3687 | if (*s == 0) | |
3688 | return (s); | |
3689 | ||
3690 | t = s + strlen (s) - 1; | |
3691 | while (t > s && whitespace (*t)) | |
3692 | t--; | |
3693 | *++t = '\0'; | |
3694 | ||
3695 | return s; | |
3696 | } | |
3697 | ||
3698 | /* **************************************************************** */ | |
3699 | /* */ | |
3700 | /* Interface to Readline Completion */ | |
3701 | /* */ | |
3702 | /* **************************************************************** */ | |
3703 | ||
3704 | char *command_generator (); | |
3705 | char **fileman_completion (); | |
3706 | ||
3707 | /* Tell the GNU Readline library how to complete. We want to try to complete | |
3708 | on command names if this is the first word in the line, or on filenames | |
3709 | if not. */ | |
3710 | initialize_readline () | |
3711 | { | |
3712 | /* Allow conditional parsing of the ~/.inputrc file. */ | |
3713 | rl_readline_name = "FileMan"; | |
3714 | ||
3715 | /* Tell the completer that we want a crack first. */ | |
3716 | rl_attempted_completion_function = (CPPFunction *)fileman_completion; | |
3717 | } | |
3718 | ||
3719 | /* Attempt to complete on the contents of TEXT. START and END bound the | |
3720 | region of rl_line_buffer that contains the word to complete. TEXT is | |
3721 | the word to complete. We can use the entire contents of rl_line_buffer | |
3722 | in case we want to do some simple parsing. Return the array of matches, | |
3723 | or NULL if there aren't any. */ | |
3724 | char ** | |
3725 | fileman_completion (text, start, end) | |
3726 | char *text; | |
3727 | int start, end; | |
3728 | { | |
3729 | char **matches; | |
3730 | ||
3731 | matches = (char **)NULL; | |
3732 | ||
3733 | /* If this word is at the start of the line, then it is a command | |
3734 | to complete. Otherwise it is the name of a file in the current | |
3735 | directory. */ | |
3736 | if (start == 0) | |
3737 | matches = completion_matches (text, command_generator); | |
3738 | ||
3739 | return (matches); | |
3740 | } | |
3741 | ||
3742 | /* Generator function for command completion. STATE lets us know whether | |
3743 | to start from scratch; without any state (i.e. STATE == 0), then we | |
3744 | start at the top of the list. */ | |
3745 | char * | |
3746 | command_generator (text, state) | |
3747 | char *text; | |
3748 | int state; | |
3749 | { | |
3750 | static int list_index, len; | |
3751 | char *name; | |
3752 | ||
3753 | /* If this is a new word to complete, initialize now. This includes | |
3754 | saving the length of TEXT for efficiency, and initializing the index | |
3755 | variable to 0. */ | |
3756 | if (!state) | |
3757 | { | |
3758 | list_index = 0; | |
3759 | len = strlen (text); | |
3760 | } | |
3761 | ||
3762 | /* Return the next name which partially matches from the command list. */ | |
3763 | while (name = commands[list_index].name) | |
3764 | { | |
3765 | list_index++; | |
3766 | ||
3767 | if (strncmp (name, text, len) == 0) | |
3768 | return (dupstr(name)); | |
3769 | } | |
3770 | ||
3771 | /* If no names matched, then return NULL. */ | |
3772 | return ((char *)NULL); | |
3773 | } | |
3774 | ||
3775 | /* **************************************************************** */ | |
3776 | /* */ | |
3777 | /* FileMan Commands */ | |
3778 | /* */ | |
3779 | /* **************************************************************** */ | |
3780 | ||
3781 | /* String to pass to system (). This is for the LIST, VIEW and RENAME | |
3782 | commands. */ | |
3783 | static char syscom[1024]; | |
3784 | ||
3785 | /* List the file(s) named in arg. */ | |
3786 | com_list (arg) | |
3787 | char *arg; | |
3788 | { | |
3789 | if (!arg) | |
3790 | arg = ""; | |
3791 | ||
3792 | sprintf (syscom, "ls -FClg %s", arg); | |
3793 | return (system (syscom)); | |
3794 | } | |
3795 | ||
3796 | com_view (arg) | |
3797 | char *arg; | |
3798 | { | |
3799 | if (!valid_argument ("view", arg)) | |
3800 | return 1; | |
3801 | ||
3802 | sprintf (syscom, "more %s", arg); | |
3803 | return (system (syscom)); | |
3804 | } | |
3805 | ||
3806 | com_rename (arg) | |
3807 | char *arg; | |
3808 | { | |
3809 | too_dangerous ("rename"); | |
3810 | return (1); | |
3811 | } | |
3812 | ||
3813 | com_stat (arg) | |
3814 | char *arg; | |
3815 | { | |
3816 | struct stat finfo; | |
3817 | ||
3818 | if (!valid_argument ("stat", arg)) | |
3819 | return (1); | |
3820 | ||
3821 | if (stat (arg, &finfo) == -1) | |
3822 | { | |
3823 | perror (arg); | |
3824 | return (1); | |
3825 | } | |
3826 | ||
3827 | printf ("Statistics for `%s':\n", arg); | |
3828 | ||
3829 | printf ("%s has %d link%s, and is %d byte%s in length.\n", arg, | |
3830 | finfo.st_nlink, | |
3831 | (finfo.st_nlink == 1) ? "" : "s", | |
3832 | finfo.st_size, | |
3833 | (finfo.st_size == 1) ? "" : "s"); | |
3834 | printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime)); | |
3835 | printf (" Last access at: %s", ctime (&finfo.st_atime)); | |
3836 | printf (" Last modified at: %s", ctime (&finfo.st_mtime)); | |
3837 | return (0); | |
3838 | } | |
3839 | ||
3840 | com_delete (arg) | |
3841 | char *arg; | |
3842 | { | |
3843 | too_dangerous ("delete"); | |
3844 | return (1); | |
3845 | } | |
3846 | ||
3847 | /* Print out help for ARG, or for all of the commands if ARG is | |
3848 | not present. */ | |
3849 | com_help (arg) | |
3850 | char *arg; | |
3851 | { | |
3852 | register int i; | |
3853 | int printed = 0; | |
3854 | ||
3855 | for (i = 0; commands[i].name; i++) | |
3856 | { | |
3857 | if (!*arg || (strcmp (arg, commands[i].name) == 0)) | |
3858 | { | |
3859 | printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc); | |
3860 | printed++; | |
3861 | } | |
3862 | } | |
3863 | ||
3864 | if (!printed) | |
3865 | { | |
3866 | printf ("No commands match `%s'. Possibilties are:\n", arg); | |
3867 | ||
3868 | for (i = 0; commands[i].name; i++) | |
3869 | { | |
3870 | /* Print in six columns. */ | |
3871 | if (printed == 6) | |
3872 | { | |
3873 | printed = 0; | |
3874 | printf ("\n"); | |
3875 | } | |
3876 | ||
3877 | printf ("%s\t", commands[i].name); | |
3878 | printed++; | |
3879 | } | |
3880 | ||
3881 | if (printed) | |
3882 | printf ("\n"); | |
3883 | } | |
3884 | return (0); | |
3885 | } | |
3886 | ||
3887 | /* Change to the directory ARG. */ | |
3888 | com_cd (arg) | |
3889 | char *arg; | |
3890 | { | |
3891 | if (chdir (arg) == -1) | |
3892 | { | |
3893 | perror (arg); | |
3894 | return 1; | |
3895 | } | |
3896 | ||
3897 | com_pwd (""); | |
3898 | return (0); | |
3899 | } | |
3900 | ||
3901 | /* Print out the current working directory. */ | |
3902 | com_pwd (ignore) | |
3903 | char *ignore; | |
3904 | { | |
3905 | char dir[1024], *s; | |
3906 | ||
3907 | s = getwd (dir); | |
3908 | if (s == 0) | |
3909 | { | |
3910 | printf ("Error getting pwd: %s\n", dir); | |
3911 | return 1; | |
3912 | } | |
3913 | ||
3914 | printf ("Current directory is %s\n", dir); | |
3915 | return 0; | |
3916 | } | |
3917 | ||
3918 | /* The user wishes to quit using this program. Just set DONE non-zero. */ | |
3919 | com_quit (arg) | |
3920 | char *arg; | |
3921 | { | |
3922 | done = 1; | |
3923 | return (0); | |
3924 | } | |
3925 | ||
3926 | /* Function which tells you that you can't do this. */ | |
3927 | too_dangerous (caller) | |
3928 | char *caller; | |
3929 | { | |
3930 | fprintf (stderr, | |
3931 | "%s: Too dangerous for me to distribute. Write it yourself.\n", | |
3932 | caller); | |
3933 | } | |
3934 | ||
3935 | /* Return non-zero if ARG is a valid argument for CALLER, else print | |
3936 | an error message and return zero. */ | |
3937 | int | |
3938 | valid_argument (caller, arg) | |
3939 | char *caller, *arg; | |
3940 | { | |
3941 | if (!arg || !*arg) | |
3942 | { | |
3943 | fprintf (stderr, "%s: Argument required.\n", caller); | |
3944 | return (0); | |
3945 | } | |
3946 | ||
3947 | return (1); | |
3948 | } | |
3949 | </PRE> | |
3950 | ||
3951 | ||
3952 | ||
3953 | <H1><A NAME="SEC46" HREF="readline.html#TOC46">Concept Index</A></H1> | |
3954 | <P> | |
3955 | Jump to: | |
f9267e15 | 3956 | <A HREF="#cindex_c">c</A> |
a44161c3 | 3957 | - |
f9267e15 | 3958 | <A HREF="#cindex_e">e</A> |
a44161c3 | 3959 | - |
f9267e15 | 3960 | <A HREF="#cindex_i">i</A> |
a44161c3 | 3961 | - |
f9267e15 | 3962 | <A HREF="#cindex_k">k</A> |
a44161c3 | 3963 | - |
f9267e15 | 3964 | <A HREF="#cindex_n">n</A> |
a44161c3 | 3965 | - |
f9267e15 | 3966 | <A HREF="#cindex_r">r</A> |
a44161c3 | 3967 | - |
f9267e15 | 3968 | <A HREF="#cindex_y">y</A> |
a44161c3 | 3969 | <P> |
f9267e15 | 3970 | <H2><A NAME="cindex_c">c</A></H2> |
a44161c3 EZ |
3971 | <DIR> |
3972 | <LI><A HREF="readline.html#IDX3">command editing</A> | |
3973 | </DIR> | |
f9267e15 | 3974 | <H2><A NAME="cindex_e">e</A></H2> |
a44161c3 EZ |
3975 | <DIR> |
3976 | <LI><A HREF="readline.html#IDX4">editing command lines</A> | |
3977 | </DIR> | |
f9267e15 | 3978 | <H2><A NAME="cindex_i">i</A></H2> |
a44161c3 EZ |
3979 | <DIR> |
3980 | <LI><A HREF="readline.html#IDX8">initialization file, readline</A> | |
3981 | <LI><A HREF="readline.html#IDX1">interaction, readline</A> | |
3982 | </DIR> | |
f9267e15 | 3983 | <H2><A NAME="cindex_k">k</A></H2> |
a44161c3 EZ |
3984 | <DIR> |
3985 | <LI><A HREF="readline.html#IDX7">kill ring</A> | |
3986 | <LI><A HREF="readline.html#IDX5">killing text</A> | |
3987 | </DIR> | |
f9267e15 | 3988 | <H2><A NAME="cindex_n">n</A></H2> |
a44161c3 EZ |
3989 | <DIR> |
3990 | <LI><A HREF="readline.html#IDX2">notation, readline</A> | |
3991 | </DIR> | |
f9267e15 | 3992 | <H2><A NAME="cindex_r">r</A></H2> |
a44161c3 EZ |
3993 | <DIR> |
3994 | <LI><A HREF="readline.html#IDX98">readline, function</A> | |
3995 | </DIR> | |
f9267e15 | 3996 | <H2><A NAME="cindex_y">y</A></H2> |
a44161c3 EZ |
3997 | <DIR> |
3998 | <LI><A HREF="readline.html#IDX6">yanking text</A> | |
3999 | </DIR> | |
4000 | ||
4001 | </P> | |
4002 | ||
4003 | ||
4004 | <H1><A NAME="SEC47" HREF="readline.html#TOC47">Function and Variable Index</A></H1> | |
4005 | <P> | |
4006 | Jump to: | |
f9267e15 | 4007 | <A HREF="#findex_a">a</A> |
a44161c3 | 4008 | - |
f9267e15 | 4009 | <A HREF="#findex_b">b</A> |
a44161c3 | 4010 | - |
f9267e15 | 4011 | <A HREF="#findex_c">c</A> |
a44161c3 | 4012 | - |
f9267e15 | 4013 | <A HREF="#findex_d">d</A> |
a44161c3 | 4014 | - |
f9267e15 | 4015 | <A HREF="#findex_e">e</A> |
a44161c3 | 4016 | - |
f9267e15 | 4017 | <A HREF="#findex_f">f</A> |
a44161c3 | 4018 | - |
f9267e15 | 4019 | <A HREF="#findex_h">h</A> |
a44161c3 | 4020 | - |
f9267e15 | 4021 | <A HREF="#findex_i">i</A> |
a44161c3 | 4022 | - |
f9267e15 | 4023 | <A HREF="#findex_k">k</A> |
a44161c3 | 4024 | - |
f9267e15 | 4025 | <A HREF="#findex_l">l</A> |
a44161c3 | 4026 | - |
f9267e15 | 4027 | <A HREF="#findex_m">m</A> |
a44161c3 | 4028 | - |
f9267e15 | 4029 | <A HREF="#findex_n">n</A> |
a44161c3 | 4030 | - |
f9267e15 | 4031 | <A HREF="#findex_o">o</A> |
a44161c3 | 4032 | - |
f9267e15 | 4033 | <A HREF="#findex_p">p</A> |
a44161c3 | 4034 | - |
f9267e15 | 4035 | <A HREF="#findex_q">q</A> |
a44161c3 | 4036 | - |
f9267e15 | 4037 | <A HREF="#findex_r">r</A> |
a44161c3 | 4038 | - |
f9267e15 | 4039 | <A HREF="#findex_s">s</A> |
a44161c3 | 4040 | - |
f9267e15 | 4041 | <A HREF="#findex_t">t</A> |
a44161c3 | 4042 | - |
f9267e15 | 4043 | <A HREF="#findex_u">u</A> |
a44161c3 | 4044 | - |
f9267e15 | 4045 | <A HREF="#findex_v">v</A> |
a44161c3 | 4046 | - |
f9267e15 | 4047 | <A HREF="#findex_y">y</A> |
a44161c3 | 4048 | <P> |
f9267e15 | 4049 | <H2><A NAME="findex_a">a</A></H2> |
a44161c3 EZ |
4050 | <DIR> |
4051 | <LI><A HREF="readline.html#IDX83">abort (C-g)</A> | |
4052 | <LI><A HREF="readline.html#IDX34">accept-line (Newline, Return)</A> | |
f9267e15 | 4053 | <LI><A HREF="readline.html#IDX170">alphabetic</A> |
a44161c3 | 4054 | </DIR> |
f9267e15 | 4055 | <H2><A NAME="findex_b">b</A></H2> |
a44161c3 EZ |
4056 | <DIR> |
4057 | <LI><A HREF="readline.html#IDX29">backward-char (C-b)</A> | |
4058 | <LI><A HREF="readline.html#IDX48">backward-delete-char (Rubout)</A> | |
4059 | <LI><A HREF="readline.html#IDX59">backward-kill-line (C-x Rubout)</A> | |
4060 | <LI><A HREF="readline.html#IDX63">backward-kill-word (M-DEL)</A> | |
4061 | <LI><A HREF="readline.html#IDX31">backward-word (M-b)</A> | |
4062 | <LI><A HREF="readline.html#IDX37">beginning-of-history (M-&#60;)</A> | |
4063 | <LI><A HREF="readline.html#IDX26">beginning-of-line (C-a)</A> | |
4064 | <LI><A HREF="readline.html#IDX9">bell-style</A> | |
4065 | </DIR> | |
f9267e15 | 4066 | <H2><A NAME="findex_c">c</A></H2> |
a44161c3 EZ |
4067 | <DIR> |
4068 | <LI><A HREF="readline.html#IDX81">call-last-kbd-macro (C-x e)</A> | |
4069 | <LI><A HREF="readline.html#IDX57">capitalize-word (M-c)</A> | |
4070 | <LI><A HREF="readline.html#IDX91">character-search (C-])</A> | |
4071 | <LI><A HREF="readline.html#IDX92">character-search-backward (M-C-])</A> | |
4072 | <LI><A HREF="readline.html#IDX32">clear-screen (C-l)</A> | |
4073 | <LI><A HREF="readline.html#IDX10">comment-begin</A> | |
4074 | <LI><A HREF="readline.html#IDX74">complete (TAB)</A> | |
4075 | <LI><A HREF="readline.html#IDX11">completion-query-items</A> | |
f9267e15 | 4076 | <LI><A HREF="readline.html#IDX197">completion_matches</A> |
a44161c3 EZ |
4077 | <LI><A HREF="readline.html#IDX12">convert-meta</A> |
4078 | <LI><A HREF="readline.html#IDX68">copy-backward-word ()</A> | |
4079 | <LI><A HREF="readline.html#IDX69">copy-forward-word ()</A> | |
4080 | <LI><A HREF="readline.html#IDX67">copy-region-as-kill ()</A> | |
4081 | </DIR> | |
f9267e15 | 4082 | <H2><A NAME="findex_d">d</A></H2> |
a44161c3 EZ |
4083 | <DIR> |
4084 | <LI><A HREF="readline.html#IDX47">delete-char (C-d)</A> | |
4085 | <LI><A HREF="readline.html#IDX78">delete-char-or-list ()</A> | |
4086 | <LI><A HREF="readline.html#IDX65">delete-horizontal-space ()</A> | |
4087 | <LI><A HREF="readline.html#IDX72">digit-argument (M-0, M-1, ... M--)</A> | |
f9267e15 EZ |
4088 | <LI><A HREF="readline.html#IDX176">digit_p</A> |
4089 | <LI><A HREF="readline.html#IDX179">digit_value</A> | |
4090 | <LI><A HREF="readline.html#IDX172">ding</A> | |
a44161c3 EZ |
4091 | <LI><A HREF="readline.html#IDX13">disable-completion</A> |
4092 | <LI><A HREF="readline.html#IDX84">do-uppercase-version (M-a, M-b, M-<VAR>x</VAR>, ...)</A> | |
4093 | <LI><A HREF="readline.html#IDX56">downcase-word (M-l)</A> | |
4094 | <LI><A HREF="readline.html#IDX94">dump-functions ()</A> | |
4095 | <LI><A HREF="readline.html#IDX96">dump-macros ()</A> | |
4096 | <LI><A HREF="readline.html#IDX95">dump-variables ()</A> | |
4097 | </DIR> | |
f9267e15 | 4098 | <H2><A NAME="findex_e">e</A></H2> |
a44161c3 EZ |
4099 | <DIR> |
4100 | <LI><A HREF="readline.html#IDX14">editing-mode</A> | |
4101 | <LI><A HREF="readline.html#IDX15">enable-keypad</A> | |
4102 | <LI><A HREF="readline.html#IDX80">end-kbd-macro (C-x ))</A> | |
4103 | <LI><A HREF="readline.html#IDX38">end-of-history (M-&#62;)</A> | |
4104 | <LI><A HREF="readline.html#IDX27">end-of-line (C-e)</A> | |
4105 | <LI><A HREF="readline.html#IDX90">exchange-point-and-mark (C-x C-x)</A> | |
4106 | <LI><A HREF="readline.html#IDX16">expand-tilde</A> | |
4107 | </DIR> | |
f9267e15 | 4108 | <H2><A NAME="findex_f">f</A></H2> |
a44161c3 | 4109 | <DIR> |
f9267e15 | 4110 | <LI><A HREF="readline.html#IDX198">filename_completion_function</A> |
a44161c3 EZ |
4111 | <LI><A HREF="readline.html#IDX49">forward-backward-delete-char ()</A> |
4112 | <LI><A HREF="readline.html#IDX28">forward-char (C-f)</A> | |
4113 | <LI><A HREF="readline.html#IDX40">forward-search-history (C-s)</A> | |
4114 | <LI><A HREF="readline.html#IDX30">forward-word (M-f)</A> | |
f9267e15 | 4115 | <LI><A HREF="readline.html#IDX148">free_undo_list</A> |
a44161c3 | 4116 | </DIR> |
f9267e15 | 4117 | <H2><A NAME="findex_h">h</A></H2> |
a44161c3 EZ |
4118 | <DIR> |
4119 | <LI><A HREF="readline.html#IDX44">history-search-backward ()</A> | |
4120 | <LI><A HREF="readline.html#IDX43">history-search-forward ()</A> | |
4121 | <LI><A HREF="readline.html#IDX17">horizontal-scroll-mode</A> | |
4122 | </DIR> | |
f9267e15 | 4123 | <H2><A NAME="findex_i">i</A></H2> |
a44161c3 EZ |
4124 | <DIR> |
4125 | <LI><A HREF="readline.html#IDX18">input-meta</A> | |
4126 | <LI><A HREF="readline.html#IDX93">insert-comment (M-#)</A> | |
4127 | <LI><A HREF="readline.html#IDX76">insert-completions (M-*)</A> | |
4128 | <LI><A HREF="readline.html#IDX20">isearch-terminators</A> | |
4129 | </DIR> | |
f9267e15 | 4130 | <H2><A NAME="findex_k">k</A></H2> |
a44161c3 EZ |
4131 | <DIR> |
4132 | <LI><A HREF="readline.html#IDX21">keymap</A> | |
4133 | <LI><A HREF="readline.html#IDX58">kill-line (C-k)</A> | |
4134 | <LI><A HREF="readline.html#IDX66">kill-region ()</A> | |
4135 | <LI><A HREF="readline.html#IDX61">kill-whole-line ()</A> | |
4136 | <LI><A HREF="readline.html#IDX62">kill-word (M-d)</A> | |
4137 | </DIR> | |
f9267e15 | 4138 | <H2><A NAME="findex_l">l</A></H2> |
a44161c3 | 4139 | <DIR> |
f9267e15 | 4140 | <LI><A HREF="readline.html#IDX175">lowercase_p</A> |
a44161c3 | 4141 | </DIR> |
f9267e15 | 4142 | <H2><A NAME="findex_m">m</A></H2> |
a44161c3 EZ |
4143 | <DIR> |
4144 | <LI><A HREF="readline.html#IDX22">mark-modified-lines</A> | |
4145 | <LI><A HREF="readline.html#IDX77">menu-complete ()</A> | |
4146 | <LI><A HREF="readline.html#IDX19">meta-flag</A> | |
4147 | </DIR> | |
f9267e15 | 4148 | <H2><A NAME="findex_n">n</A></H2> |
a44161c3 EZ |
4149 | <DIR> |
4150 | <LI><A HREF="readline.html#IDX36">next-history (C-n)</A> | |
4151 | <LI><A HREF="readline.html#IDX42">non-incremental-forward-search-history (M-n)</A> | |
4152 | <LI><A HREF="readline.html#IDX41">non-incremental-reverse-search-history (M-p)</A> | |
f9267e15 | 4153 | <LI><A HREF="readline.html#IDX171">numeric</A> |
a44161c3 | 4154 | </DIR> |
f9267e15 | 4155 | <H2><A NAME="findex_o">o</A></H2> |
a44161c3 EZ |
4156 | <DIR> |
4157 | <LI><A HREF="readline.html#IDX23">output-meta</A> | |
4158 | </DIR> | |
f9267e15 | 4159 | <H2><A NAME="findex_p">p</A></H2> |
a44161c3 EZ |
4160 | <DIR> |
4161 | <LI><A HREF="readline.html#IDX75">possible-completions (M-?)</A> | |
4162 | <LI><A HREF="readline.html#IDX85">prefix-meta (ESC)</A> | |
4163 | <LI><A HREF="readline.html#IDX35">previous-history (C-p)</A> | |
4164 | </DIR> | |
f9267e15 | 4165 | <H2><A NAME="findex_q">q</A></H2> |
a44161c3 EZ |
4166 | <DIR> |
4167 | <LI><A HREF="readline.html#IDX50">quoted-insert (C-q, C-v)</A> | |
4168 | </DIR> | |
f9267e15 | 4169 | <H2><A NAME="findex_r">r</A></H2> |
a44161c3 EZ |
4170 | <DIR> |
4171 | <LI><A HREF="readline.html#IDX82">re-read-init-file (C-x C-r)</A> | |
4172 | <LI><A HREF="readline.html#IDX97">readline</A> | |
4173 | <LI><A HREF="readline.html#IDX33">redraw-current-line ()</A> | |
4174 | <LI><A HREF="readline.html#IDX39">reverse-search-history (C-r)</A> | |
4175 | <LI><A HREF="readline.html#IDX87">revert-line (M-r)</A> | |
f9267e15 EZ |
4176 | <LI><A HREF="readline.html#IDX120">rl_add_defun</A> |
4177 | <LI><A HREF="readline.html#IDX147">rl_add_undo</A> | |
4178 | <LI><A HREF="readline.html#IDX107">rl_already_prompted</A> | |
4179 | <LI><A HREF="readline.html#IDX201">rl_attempted_completion_function</A> | |
4180 | <LI><A HREF="readline.html#IDX207">rl_basic_quote_characters</A> | |
4181 | <LI><A HREF="readline.html#IDX206">rl_basic_word_break_characters</A> | |
4182 | <LI><A HREF="readline.html#IDX145">rl_begin_undo_group</A> | |
4183 | <LI><A HREF="readline.html#IDX129">rl_bind_key</A> | |
4184 | <LI><A HREF="readline.html#IDX130">rl_bind_key_in_map</A> | |
4185 | <LI><A HREF="readline.html#IDX119">rl_binding_keymap</A> | |
4186 | <LI><A HREF="readline.html#IDX180">rl_callback_handler_install</A> | |
4187 | <LI><A HREF="readline.html#IDX182">rl_callback_handler_remove</A> | |
4188 | <LI><A HREF="readline.html#IDX181">rl_callback_read_char</A> | |
4189 | <LI><A HREF="readline.html#IDX183">rl_catch_signals</A> | |
4190 | <LI><A HREF="readline.html#IDX184">rl_catch_sigwinch</A> | |
4191 | <LI><A HREF="readline.html#IDX204">rl_char_is_quoted_p</A> | |
4192 | <LI><A HREF="readline.html#IDX185">rl_cleanup_after_signal</A> | |
4193 | <LI><A HREF="readline.html#IDX157">rl_clear_message</A> | |
4194 | <LI><A HREF="readline.html#IDX190">rl_clear_signals</A> | |
4195 | <LI><A HREF="readline.html#IDX191">rl_complete</A>, <A HREF="readline.html#IDX194">rl_complete</A> | |
4196 | <LI><A HREF="readline.html#IDX193">rl_complete_internal</A> | |
4197 | <LI><A HREF="readline.html#IDX209">rl_completer_quote_characters</A> | |
4198 | <LI><A HREF="readline.html#IDX208">rl_completer_word_break_characters</A> | |
4199 | <LI><A HREF="readline.html#IDX212">rl_completion_append_character</A> | |
4200 | <LI><A HREF="readline.html#IDX219">rl_completion_display_matches_hook</A> | |
4201 | <LI><A HREF="readline.html#IDX192">rl_completion_entry_function</A>, <A HREF="readline.html#IDX200">rl_completion_entry_function</A> | |
4202 | <LI><A HREF="readline.html#IDX205">rl_completion_query_items</A> | |
4203 | <LI><A HREF="readline.html#IDX122">rl_copy_keymap</A> | |
4204 | <LI><A HREF="readline.html#IDX162">rl_copy_text</A> | |
4205 | <LI><A HREF="readline.html#IDX161">rl_delete_text</A> | |
4206 | <LI><A HREF="readline.html#IDX218">rl_directory_completion_hook</A> | |
4207 | <LI><A HREF="readline.html#IDX124">rl_discard_keymap</A> | |
4208 | <LI><A HREF="readline.html#IDX173">rl_display_match_list</A> | |
4209 | <LI><A HREF="readline.html#IDX149">rl_do_undo</A> | |
a44161c3 EZ |
4210 | <LI><A HREF="readline.html#IDX103">rl_done</A> |
4211 | <LI><A HREF="readline.html#IDX101">rl_end</A> | |
f9267e15 | 4212 | <LI><A HREF="readline.html#IDX146">rl_end_undo_group</A> |
a44161c3 | 4213 | <LI><A HREF="readline.html#IDX105">rl_erase_empty_line</A> |
f9267e15 EZ |
4214 | <LI><A HREF="readline.html#IDX115">rl_event_hook</A> |
4215 | <LI><A HREF="readline.html#IDX118">rl_executing_keymap</A> | |
4216 | <LI><A HREF="readline.html#IDX167">rl_extend_line_buffer</A> | |
4217 | <LI><A HREF="readline.html#IDX214">rl_filename_completion_desired</A> | |
4218 | <LI><A HREF="readline.html#IDX203">rl_filename_dequoting_function</A> | |
4219 | <LI><A HREF="readline.html#IDX210">rl_filename_quote_characters</A> | |
4220 | <LI><A HREF="readline.html#IDX215">rl_filename_quoting_desired</A> | |
4221 | <LI><A HREF="readline.html#IDX202">rl_filename_quoting_function</A> | |
4222 | <LI><A HREF="readline.html#IDX152">rl_forced_update_display</A> | |
4223 | <LI><A HREF="readline.html#IDX186">rl_free_line_state</A> | |
4224 | <LI><A HREF="readline.html#IDX142">rl_function_dumper</A> | |
4225 | <LI><A HREF="readline.html#IDX139">rl_function_of_keyseq</A> | |
4226 | <LI><A HREF="readline.html#IDX144">rl_funmap_names</A> | |
4227 | <LI><A HREF="readline.html#IDX135">rl_generic_bind</A> | |
4228 | <LI><A HREF="readline.html#IDX125">rl_get_keymap</A> | |
4229 | <LI><A HREF="readline.html#IDX127">rl_get_keymap_by_name</A> | |
4230 | <LI><A HREF="readline.html#IDX128">rl_get_keymap_name</A> | |
4231 | <LI><A HREF="readline.html#IDX165">rl_getc</A> | |
4232 | <LI><A HREF="readline.html#IDX116">rl_getc_function</A> | |
4233 | <LI><A HREF="readline.html#IDX213">rl_ignore_completion_duplicates</A> | |
4234 | <LI><A HREF="readline.html#IDX217">rl_ignore_some_completions_function</A> | |
4235 | <LI><A HREF="readline.html#IDX216">rl_inhibit_completion</A> | |
4236 | <LI><A HREF="readline.html#IDX168">rl_initialize</A> | |
4237 | <LI><A HREF="readline.html#IDX196">rl_insert_completions</A> | |
4238 | <LI><A HREF="readline.html#IDX160">rl_insert_text</A> | |
4239 | <LI><A HREF="readline.html#IDX111">rl_instream</A> | |
4240 | <LI><A HREF="readline.html#IDX140">rl_invoking_keyseqs</A> | |
4241 | <LI><A HREF="readline.html#IDX141">rl_invoking_keyseqs_in_map</A> | |
4242 | <LI><A HREF="readline.html#IDX163">rl_kill_text</A> | |
4243 | <LI><A HREF="readline.html#IDX108">rl_library_version</A> | |
a44161c3 | 4244 | <LI><A HREF="readline.html#IDX99">rl_line_buffer</A> |
f9267e15 EZ |
4245 | <LI><A HREF="readline.html#IDX143">rl_list_funmap_names</A> |
4246 | <LI><A HREF="readline.html#IDX121">rl_make_bare_keymap</A> | |
4247 | <LI><A HREF="readline.html#IDX123">rl_make_keymap</A> | |
a44161c3 | 4248 | <LI><A HREF="readline.html#IDX102">rl_mark</A> |
f9267e15 EZ |
4249 | <LI><A HREF="readline.html#IDX156">rl_message</A> |
4250 | <LI><A HREF="readline.html#IDX150">rl_modifying</A> | |
4251 | <LI><A HREF="readline.html#IDX138">rl_named_function</A> | |
4252 | <LI><A HREF="readline.html#IDX153">rl_on_new_line</A> | |
4253 | <LI><A HREF="readline.html#IDX154">rl_on_new_line_with_prompt</A> | |
4254 | <LI><A HREF="readline.html#IDX112">rl_outstream</A> | |
4255 | <LI><A HREF="readline.html#IDX136">rl_parse_and_bind</A> | |
a44161c3 EZ |
4256 | <LI><A HREF="readline.html#IDX104">rl_pending_input</A> |
4257 | <LI><A HREF="readline.html#IDX100">rl_point</A> | |
f9267e15 EZ |
4258 | <LI><A HREF="readline.html#IDX195">rl_possible_completions</A> |
4259 | <LI><A HREF="readline.html#IDX114">rl_pre_input_hook</A> | |
a44161c3 | 4260 | <LI><A HREF="readline.html#IDX106">rl_prompt</A> |
f9267e15 EZ |
4261 | <LI><A HREF="readline.html#IDX137">rl_read_init_file</A> |
4262 | <LI><A HREF="readline.html#IDX164">rl_read_key</A> | |
4263 | <LI><A HREF="readline.html#IDX110">rl_readline_name</A> | |
4264 | <LI><A HREF="readline.html#IDX151">rl_redisplay</A> | |
4265 | <LI><A HREF="readline.html#IDX117">rl_redisplay_function</A> | |
4266 | <LI><A HREF="readline.html#IDX187">rl_reset_after_signal</A> | |
4267 | <LI><A HREF="readline.html#IDX155">rl_reset_line_state</A> | |
4268 | <LI><A HREF="readline.html#IDX169">rl_reset_terminal</A> | |
4269 | <LI><A HREF="readline.html#IDX188">rl_resize_terminal</A> | |
4270 | <LI><A HREF="readline.html#IDX159">rl_restore_prompt</A> | |
4271 | <LI><A HREF="readline.html#IDX158">rl_save_prompt</A> | |
4272 | <LI><A HREF="readline.html#IDX126">rl_set_keymap</A> | |
4273 | <LI><A HREF="readline.html#IDX189">rl_set_signals</A> | |
4274 | <LI><A HREF="readline.html#IDX211">rl_special_prefixes</A> | |
4275 | <LI><A HREF="readline.html#IDX113">rl_startup_hook</A> | |
4276 | <LI><A HREF="readline.html#IDX166">rl_stuff_char</A> | |
4277 | <LI><A HREF="readline.html#IDX109">rl_terminal_name</A> | |
4278 | <LI><A HREF="readline.html#IDX134">rl_unbind_command_in_map</A> | |
4279 | <LI><A HREF="readline.html#IDX133">rl_unbind_function_in_map</A> | |
4280 | <LI><A HREF="readline.html#IDX131">rl_unbind_key</A> | |
4281 | <LI><A HREF="readline.html#IDX132">rl_unbind_key_in_map</A> | |
a44161c3 | 4282 | </DIR> |
f9267e15 | 4283 | <H2><A NAME="findex_s">s</A></H2> |
a44161c3 EZ |
4284 | <DIR> |
4285 | <LI><A HREF="readline.html#IDX52">self-insert (a, b, A, 1, !, ...)</A> | |
4286 | <LI><A HREF="readline.html#IDX89">set-mark (C-@)</A> | |
4287 | <LI><A HREF="readline.html#IDX24">show-all-if-ambiguous</A> | |
4288 | <LI><A HREF="readline.html#IDX79">start-kbd-macro (C-x ()</A> | |
4289 | </DIR> | |
f9267e15 | 4290 | <H2><A NAME="findex_t">t</A></H2> |
a44161c3 EZ |
4291 | <DIR> |
4292 | <LI><A HREF="readline.html#IDX51">tab-insert (M-TAB)</A> | |
4293 | <LI><A HREF="readline.html#IDX88">tilde-expand (M-~)</A> | |
f9267e15 EZ |
4294 | <LI><A HREF="readline.html#IDX178">to_lower</A> |
4295 | <LI><A HREF="readline.html#IDX177">to_upper</A> | |
a44161c3 EZ |
4296 | <LI><A HREF="readline.html#IDX53">transpose-chars (C-t)</A> |
4297 | <LI><A HREF="readline.html#IDX54">transpose-words (M-t)</A> | |
4298 | </DIR> | |
f9267e15 | 4299 | <H2><A NAME="findex_u">u</A></H2> |
a44161c3 EZ |
4300 | <DIR> |
4301 | <LI><A HREF="readline.html#IDX86">undo (C-_, C-x C-u)</A> | |
4302 | <LI><A HREF="readline.html#IDX73">universal-argument ()</A> | |
4303 | <LI><A HREF="readline.html#IDX60">unix-line-discard (C-u)</A> | |
4304 | <LI><A HREF="readline.html#IDX64">unix-word-rubout (C-w)</A> | |
4305 | <LI><A HREF="readline.html#IDX55">upcase-word (M-u)</A> | |
f9267e15 EZ |
4306 | <LI><A HREF="readline.html#IDX174">uppercase_p</A> |
4307 | <LI><A HREF="readline.html#IDX199">username_completion_function</A> | |
a44161c3 | 4308 | </DIR> |
f9267e15 | 4309 | <H2><A NAME="findex_v">v</A></H2> |
a44161c3 EZ |
4310 | <DIR> |
4311 | <LI><A HREF="readline.html#IDX25">visible-stats</A> | |
4312 | </DIR> | |
f9267e15 | 4313 | <H2><A NAME="findex_y">y</A></H2> |
a44161c3 EZ |
4314 | <DIR> |
4315 | <LI><A HREF="readline.html#IDX70">yank (C-y)</A> | |
4316 | <LI><A HREF="readline.html#IDX46">yank-last-arg (M-., M-_)</A> | |
4317 | <LI><A HREF="readline.html#IDX45">yank-nth-arg (M-C-y)</A> | |
4318 | <LI><A HREF="readline.html#IDX71">yank-pop (M-y)</A> | |
4319 | </DIR> | |
4320 | ||
4321 | </P> | |
4322 | <P><HR><P> | |
f9267e15 | 4323 | This document was generated on 1 March 2000 using the |
a44161c3 EZ |
4324 | <A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A> |
4325 | translator version 1.52.</P> | |
4326 | </BODY> | |
4327 | </HTML> |