Commit | Line | Data |
---|---|---|
dd3b648e RP |
1 | \input texinfo @c -*-texinfo-*- |
2 | @comment %**start of header (This is for running Texinfo on a region.) | |
3 | @setfilename readline.info | |
4 | @settitle Line Editing Commands | |
5 | @comment %**end of header (This is for running Texinfo on a region.) | |
6 | @synindex fn vr | |
7 | ||
8 | @iftex | |
9 | @comment finalout | |
10 | @end iftex | |
11 | ||
12 | @ifinfo | |
13 | This document describes the GNU Readline Library, a utility for aiding | |
14 | in the consitency of user interface across discrete programs that need | |
15 | to provide a command line interface. | |
16 | ||
17 | Copyright (C) 1988 Free Software Foundation, Inc. | |
18 | ||
19 | Permission is granted to make and distribute verbatim copies of | |
20 | this manual provided the copyright notice and this permission notice | |
21 | pare preserved on all copies. | |
22 | ||
23 | @ignore | |
24 | Permission is granted to process this file through TeX and print the | |
25 | results, provided the printed document carries copying permission | |
26 | notice identical to this one except for the removal of this paragraph | |
27 | (this paragraph not being relevant to the printed manual). | |
28 | ||
29 | @end ignore | |
30 | Permission is granted to copy and distribute modified versions of this | |
31 | manual under the conditions for verbatim copying, provided that the entire | |
32 | resulting derived work is distributed under the terms of a permission | |
33 | notice identical to this one. | |
34 | ||
35 | Permission is granted to copy and distribute translations of this manual | |
36 | into another language, under the above conditions for modified versions, | |
37 | except that this permission notice may be stated in a translation approved | |
38 | by the Foundation. | |
39 | @end ifinfo | |
40 | ||
41 | @setchapternewpage odd | |
42 | @titlepage | |
43 | @sp 11 | |
44 | @center @titlefont{GNU Readline Library} | |
45 | @sp 2 | |
46 | @center by Brian Fox | |
47 | @sp 2 | |
48 | @center Version 1.0 | |
49 | @sp 2 | |
50 | @center February 1989 | |
51 | ||
52 | @comment Include the Distribution inside the titlepage environment so | |
53 | @c that headings are turned off. | |
54 | ||
55 | @page | |
56 | @vskip 0pt plus 1filll | |
57 | Copyright @copyright{} 1989 Free Software Foundation, Inc. | |
58 | ||
59 | @sp 2 | |
60 | This document describes the GNU Readline Library, a utility for aiding | |
61 | in the consistency of user interface across discrete programs that need | |
62 | to provide a command line interface. | |
63 | @sp 2 | |
64 | ||
65 | Published by the Free Software Foundation @* | |
66 | 675 Massachusetts Avenue, @* | |
67 | Cambridge, MA 02139 USA | |
68 | ||
69 | Permission is granted to make and distribute verbatim copies of | |
70 | this manual provided the copyright notice and this permission notice | |
71 | are preserved on all copies. | |
72 | ||
73 | Permission is granted to copy and distribute modified versions of this | |
74 | manual under the conditions for verbatim copying, provided that the entire | |
75 | resulting derived work is distributed under the terms of a permission | |
76 | notice identical to this one. | |
77 | ||
78 | Permission is granted to copy and distribute translations of this manual | |
79 | into another language, under the above conditions for modified versions, | |
80 | except that this permission notice may be stated in a translation approved | |
81 | by the Foundation. | |
82 | ||
83 | @end titlepage | |
84 | ||
85 | @node Top, Readline Top, ,(DIR) | |
86 | @chapter GNU Readline Library | |
87 | ||
88 | @ifinfo | |
89 | This document describes the GNU Readline Library, a utility for aiding | |
90 | in the consistency of user interface across discrete programs that need | |
91 | to provide a command line interface. | |
92 | @end ifinfo | |
93 | ||
94 | @menu | |
95 | * Readline Top:: GNU Readline User's Manual | |
96 | * Readline Technical:: GNU Readline Programmer's Manual | |
97 | @end menu | |
98 | @include inc-readline.texinfo | |
99 | @node Readline Technical, , Top, Top | |
100 | @chapter Readline Programmer's Manual | |
101 | ||
102 | This manual describes the interface between the GNU Readline Library and | |
103 | user programs. If you are a programmer, and you wish to include the | |
104 | features found in GNU Readline in your own programs, such as completion, | |
105 | line editing, and interactive history manipulation, this documentation | |
106 | is for you. | |
107 | ||
108 | @menu | |
109 | * Default Behaviour:: Using the default behaviour of Readline. | |
110 | * Custom Functions:: Adding your own functions to Readline. | |
111 | * Custom Completers:: Supplanting or supplementing Readline's | |
112 | completion functions. | |
113 | * Variable Index:: Index of externally tweakable variables. | |
114 | @end menu | |
115 | ||
116 | @node Default Behaviour, Custom Functions, Readline Technical, Readline Technical | |
117 | @section Default Behaviour | |
118 | ||
119 | Many programs provide a command line interface, such as @code{mail}, | |
120 | @code{ftp}, and @code{sh}. For such programs, the default behaviour of | |
121 | Readline is sufficient. This section describes how to use Readline in | |
122 | the simplest way possible, perhaps to replace calls in your code to | |
123 | @code{gets ()}. | |
124 | ||
125 | @findex readline () | |
126 | @cindex readline, function | |
127 | The function @code{readline} prints a prompt and then reads and returns | |
128 | a single line of text from the user. The line which @code{readline ()} | |
129 | returns is allocated with @code{malloc ()}; you should @code{free ()} | |
130 | the line when you are done with it. The declaration in ANSI C is | |
131 | ||
132 | @example | |
133 | @code{char *readline (char *@var{prompt});} | |
134 | @end example | |
135 | or, preferably, | |
136 | @example | |
137 | @code{#include <readline/readline.h>} | |
138 | @end example | |
139 | ||
140 | So, one might say | |
141 | @example | |
142 | @code{char *line = readline ("Enter a line: ");} | |
143 | @end example | |
144 | in order to read a line of text from the user. | |
145 | ||
146 | The line which is returned has the final newline removed, so only the | |
147 | text of the line remains. | |
148 | ||
149 | If readline encounters an EOF while reading the line, and the line is | |
150 | empty at that point, then @code{(char *)NULL} is returned. Otherwise, | |
151 | the line is ended just as if a newline was typed. | |
152 | ||
153 | If you want the user to be able to get at the line later, (with | |
154 | @key{C-p} for example), you must call @code{add_history ()} to save the | |
155 | line away in a @dfn{history} list of such lines. | |
156 | ||
157 | @example | |
158 | @code{add_history (line)}; | |
159 | @end example | |
160 | ||
161 | If you use @code{add_history ()}, you should also | |
162 | @code{#include <readline/history.h>} | |
163 | For full details on the GNU History Library, see the associated manual. | |
164 | ||
165 | It is polite to avoid saving empty lines on the history list, since | |
166 | no one has a burning need to reuse a blank line. Here is a function | |
167 | which usefully replaces the standard @code{gets ()} library function: | |
168 | ||
169 | @example | |
170 | #include <readline/readline.h> | |
171 | #include <readline/history.h> | |
172 | ||
173 | /* A static variable for holding the line. */ | |
174 | static char *my_gets_line = (char *)NULL; | |
175 | ||
176 | /* Read a string, and return a pointer to it. Returns NULL on EOF. */ | |
177 | char * | |
178 | my_gets () | |
179 | @{ | |
180 | /* If the buffer has already been allocated, return the memory | |
181 | to the free pool. */ | |
182 | if (my_gets_line != (char *)NULL) | |
183 | free (my_gets_line); | |
184 | ||
185 | /* Get a line from the user. */ | |
186 | my_gets_line = readline (""); | |
187 | ||
188 | /* If the line has any text in it, save it on the history. */ | |
189 | if (my_get_line && *my_gets_line) | |
190 | add_history (my_gets_line); | |
191 | ||
192 | return (my_gets_line); | |
193 | @} | |
194 | @end example | |
195 | ||
196 | The above code gives the user the default behaviour of @key{TAB} | |
197 | completion: completion on file names. If you do not want readline to | |
198 | complete on filenames, you can change the binding of the @key{TAB} key | |
199 | with @code{rl_bind_key ()}. | |
200 | ||
201 | @findex rl_bind_key () | |
202 | ||
203 | @example | |
204 | @code{int rl_bind_key (int @var{key}, (int (*)())@var{function});} | |
205 | @end example | |
206 | ||
207 | @code{rl_bind_key ()} takes 2 arguments; @var{key} is the character that | |
208 | you want to bind, and @var{function} is the address of the function to | |
209 | run when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert ()} | |
210 | makes @key{TAB} just insert itself. | |
211 | ||
212 | @code{rl_bind_key ()} returns non-zero if @var{key} is not a valid | |
213 | ASCII character code (between 0 and 255). | |
214 | ||
215 | @example | |
216 | @code{rl_bind_key ('\t', rl_insert);} | |
217 | @end example | |
218 | ||
219 | @node Custom Functions, Custom Completers, Default Behaviour, Readline Technical | |
220 | @section Custom Functions | |
221 | ||
222 | Readline provides a great many functions for manipulating the text of | |
223 | the line. But it isn't possible to anticipate the needs of all | |
224 | programs. This section describes the various functions and variables | |
225 | defined in within the Readline library which allow a user program to add | |
226 | customized functionality to Readline. | |
227 | ||
228 | @menu | |
229 | * The Function Type:: C declarations to make code readable. | |
230 | * Function Naming:: How to give a function you write a name. | |
231 | * Keymaps:: Making keymaps. | |
232 | * Binding Keys:: Changing Keymaps. | |
233 | * Function Writing:: Variables and calling conventions. | |
234 | * Allowing Undoing:: How to make your functions undoable. | |
235 | @end menu | |
236 | ||
237 | @node The Function Type, Function Naming, Custom Functions, Custom Functions | |
238 | For the sake of readabilty, we declare a new type of object, called | |
239 | @dfn{Function}. `Function' is a C language function which returns an | |
240 | @code{int}. The type declaration for `Function' is: | |
241 | ||
242 | @code{typedef int Function ();} | |
243 | ||
244 | The reason for declaring this new type is to make it easier to discuss | |
245 | pointers to C functions. Let us say we had a variable called @var{func} | |
246 | which was a pointer to a function. Instead of the classic C declaration | |
247 | ||
248 | @code{int (*)()func;} | |
249 | ||
250 | we have | |
251 | ||
252 | @code{Function *func;} | |
253 | ||
254 | @node Function Naming, Keymaps, The Function Type, Custom Functions | |
255 | @subsection Naming a Function | |
256 | ||
257 | The user can dynamically change the bindings of keys while using | |
258 | Readline. This is done by representing the function with a descriptive | |
259 | name. The user is able to type the descriptive name when referring to | |
260 | the function. Thus, in an init file, one might find | |
261 | ||
262 | @example | |
263 | Meta-Rubout: backward-kill-word | |
264 | @end example | |
265 | ||
266 | This binds @key{Meta-Rubout} to the function @emph{descriptively} named | |
267 | @code{backward-kill-word}. You, as a programmer, should bind the | |
268 | functions you write to descriptive names as well. Here is how to do | |
269 | that. | |
270 | ||
271 | @defun rl_add_defun (char *name, Function *function, int key) | |
272 | Add @var{name} to the list of named functions. Make @var{function} be | |
273 | the function that gets called. If @var{key} is not -1, then bind it to | |
274 | @var{function} using @code{rl_bind_key ()}. | |
275 | @end defun | |
276 | ||
277 | Using this function alone is sufficient for most applications. It is | |
278 | the recommended way to add a few functions to the default functions that | |
279 | Readline has built in already. If you need to do more or different | |
280 | things than adding a function to Readline, you may need to use the | |
281 | underlying functions described below. | |
282 | ||
283 | @node Keymaps, Binding Keys, Function Naming, Custom Functions | |
284 | @subsection Selecting a Keymap | |
285 | ||
286 | Key bindings take place on a @dfn{keymap}. The keymap is the | |
287 | association between the keys that the user types and the functions that | |
288 | get run. You can make your own keymaps, copy existing keymaps, and tell | |
289 | Readline which keymap to use. | |
290 | ||
291 | @defun rl_make_bare_keymap () | |
292 | Returns a new, empty keymap. The space for the keymap is allocated with | |
293 | @code{malloc ()}; you should @code{free ()} it when you are done. | |
294 | @end defun | |
295 | ||
296 | @defun rl_copy_keymap (Keymap map) | |
297 | Return a new keymap which is a copy of @var{map}. | |
298 | @end defun | |
299 | ||
300 | @defun rl_make_keymap () | |
301 | Return a new keymap with the printing characters bound to rl_insert, | |
302 | the lowercase Meta characters bound to run their equivalents, and | |
303 | the Meta digits bound to produce numeric arguments. | |
304 | @end defun | |
305 | ||
306 | @node Binding Keys, Function Writing, Keymaps, Custom Functions | |
307 | @subsection Binding Keys | |
308 | ||
309 | You associate keys with functions through the keymap. Here are | |
310 | the functions for doing that. | |
311 | ||
312 | @defun rl_bind_key (int key, Function *function) | |
313 | Binds @var{key} to @var{function} in the currently selected keymap. | |
314 | Returns non-zero in the case of an invalid @var{key}. | |
315 | @end defun | |
316 | ||
317 | @defun rl_bind_key_in_map (int key, Function *function, Keymap map) | |
318 | Bind @var{key} to @var{function} in @var{map}. Returns non-zero in the case | |
319 | of an invalid @var{key}. | |
320 | @end defun | |
321 | ||
322 | @defun rl_unbind_key (int key) | |
323 | Make @var{key} do nothing in the currently selected keymap. | |
324 | Returns non-zero in case of error. | |
325 | @end defun | |
326 | ||
327 | @defun rl_unbind_key_in_map (int key, Keymap map) | |
328 | Make @var{key} be bound to the null function in @var{map}. | |
329 | Returns non-zero in case of error. | |
330 | @end defun | |
331 | ||
332 | @node Function Writing, Allowing Undoing, Binding Keys, Custom Functions | |
333 | @subsection Writing a New Function | |
334 | ||
335 | In order to write new functions for Readline, you need to know the | |
336 | calling conventions for keyboard invoked functions, and the names of the | |
337 | variables that describe the current state of the line gathered so far. | |
338 | ||
339 | @defvar char *rl_line_buffer | |
340 | This is the line gathered so far. You are welcome to modify the | |
341 | contents of this, but see Undoing, below. | |
342 | @end defvar | |
343 | ||
344 | @defvar int rl_point | |
345 | The offset of the current cursor position in @var{rl_line_buffer}. | |
346 | @end defvar | |
347 | ||
348 | @defvar int rl_end | |
349 | The number of characters present in @code{rl_line_buffer}. When | |
350 | @code{rl_point} is at the end of the line, then @code{rl_point} and | |
351 | @code{rl_end} are equal. | |
352 | @end defvar | |
353 | ||
354 | The calling sequence for a command @code{foo} looks like | |
355 | ||
356 | @example | |
357 | @code{foo (count, key)} | |
358 | @end example | |
359 | ||
360 | where @var{count} is the numeric argument (or 1 if defaulted) and | |
361 | @var{key} is the key that invoked this function. | |
362 | ||
363 | It is completely up to the function as to what should be done with the | |
364 | numeric argument; some functions use it as a repeat count, other | |
365 | functions as a flag, and some choose to ignore it. In general, if a | |
366 | function uses the numeric argument as a repeat count, it should be able | |
367 | to do something useful with a negative argument as well as a positive | |
368 | argument. At the very least, it should be aware that it can be passed a | |
369 | negative argument. | |
370 | ||
371 | @node Allowing Undoing, , Function Writing, Custom Functions | |
372 | @subsection Allowing Undoing | |
373 | ||
374 | Supporting the undo command is a painless thing to do, and makes your | |
375 | function much more useful to the end user. It is certainly easy to try | |
376 | something if you know you can undo it. I could use an undo function for | |
377 | the stock market. | |
378 | ||
379 | If your function simply inserts text once, or deletes text once, and it | |
380 | calls @code{rl_insert_text ()} or @code{rl_delete_text ()} to do it, then | |
381 | undoing is already done for you automatically, and you can safely skip | |
382 | this section. | |
383 | ||
384 | If you do multiple insertions or multiple deletions, or any combination | |
385 | of these operations, you will want to group them together into one | |
386 | operation. This can be done with @code{rl_begin_undo_group ()} and | |
387 | @code{rl_end_undo_group ()}. | |
388 | ||
389 | @defun rl_begin_undo_group () | |
390 | Begins saving undo information in a group construct. The undo | |
391 | information usually comes from calls to @code{rl_insert_text ()} and | |
392 | @code{rl_delete_text ()}, but they could be direct calls to | |
393 | @code{rl_add_undo ()}. | |
394 | @end defun | |
395 | ||
396 | @defun rl_end_undo_group () | |
397 | Closes the current undo group started with @code{rl_begin_undo_group | |
398 | ()}. There should be exactly one call to @code{rl_end_undo_group ()} | |
399 | for every call to @code{rl_begin_undo_group ()}. | |
400 | @end defun | |
401 | ||
402 | Finally, if you neither insert nor delete text, but directly modify the | |
403 | existing text (e.g. change its case), you call @code{rl_modifying ()} | |
404 | once, just before you modify the text. You must supply the indices of | |
405 | the text range that you are going to modify. | |
406 | ||
407 | @defun rl_modifying (int start, int end) | |
408 | Tell Readline to save the text between @var{start} and @var{end} as a | |
409 | single undo unit. It is assumed that subsequent to this call you will | |
410 | modify that range of text in some way. | |
411 | @end defun | |
412 | ||
413 | @subsection An Example | |
414 | ||
415 | Let us say that we are actually going to put an example here. | |
416 | ||
417 | @node Custom Completers, Variable Index, Custom Functions, Readline Technical | |
418 | ||
419 | Typically, a program that reads commands from the user has a way of | |
420 | disambiguating between commands and data. If your program is one of | |
421 | these, then it can provide completion for either commands, or data, or | |
422 | both commands and data. The following sections describe how your | |
423 | program and Readline cooperate to provide this service to end users. | |
424 | ||
425 | @menu | |
426 | @end menu | |
427 | ||
428 | @node Variable Index, , Custom Completers, Readline Technical | |
429 | @appendix Variable Index | |
430 | @printindex vr | |
431 | @contents | |
432 | ||
433 | @bye | |
434 |