7a67dd45 |
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 | |
136 | So, one might say |
137 | @example |
138 | @code{char *line = readline ("Enter a line: ");} |
139 | @end example |
140 | in order to read a line of text from the user. |
141 | |
142 | The line which is returned has the final newline removed, so only the |
143 | text of the line remains. |
144 | |
145 | If readline encounters an EOF while reading the line, and the line is |
146 | empty at that point, then @code{(char *)NULL} is returned. Otherwise, |
147 | the line is ended just as if a newline was typed. |
148 | |
149 | If you want the user to be able to get at the line later, (with |
150 | @key{C-p} for example), you must call @code{add_history ()} to save the |
151 | line away in a @dfn{history} list of such lines. |
152 | |
153 | @example |
154 | @code{add_history (line)}; |
155 | @end example |
156 | |
157 | For full details on the GNU History Library, see the associated manual. |
158 | |
159 | It is polite to avoid saving empty lines on the history list, since |
160 | no one has a burning need to reuse a blank line. Here is a function |
161 | which usefully replaces the standard @code{gets ()} library function: |
162 | |
163 | @example |
164 | /* A static variable for holding the line. */ |
165 | static char *my_gets_line = (char *)NULL; |
166 | |
167 | /* Read a string, and return a pointer to it. Returns NULL on EOF. */ |
168 | char * |
169 | my_gets () |
170 | @{ |
171 | /* If the buffer has already been allocated, return the memory |
172 | to the free pool. */ |
173 | if (my_gets_line != (char *)NULL) |
174 | free (my_gets_line); |
175 | |
176 | /* Get a line from the user. */ |
177 | my_gets_line = readline (""); |
178 | |
179 | /* If the line has any text in it, save it on the history. */ |
180 | if (my_get_line && *my_gets_line) |
181 | add_history (my_gets_line); |
182 | |
183 | return (my_gets_line); |
184 | @} |
185 | @end example |
186 | |
187 | The above code gives the user the default behaviour of @key{TAB} |
188 | completion: completion on file names. If you do not want readline to |
189 | complete on filenames, you can change the binding of the @key{TAB} key |
190 | with @code{rl_bind_key ()}. |
191 | |
192 | @findex rl_bind_key () |
193 | |
194 | @example |
195 | @code{int rl_bind_key (int @var{key}, (int (*)())@var{function});} |
196 | @end example |
197 | |
198 | @code{rl_bind_key ()} takes 2 arguments; @var{key} is the character that |
199 | you want to bind, and @var{function} is the address of the function to |
200 | run when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert ()} |
201 | makes @key{TAB} just insert itself. |
202 | |
203 | @code{rl_bind_key ()} returns non-zero if @var{key} is not a valid |
204 | ASCII character code (between 0 and 255). |
205 | |
206 | @example |
207 | @code{rl_bind_key ('\t', rl_insert);} |
208 | @end example |
209 | |
210 | @node Custom Functions, Custom Completers, Default Behaviour, Readline Technical |
211 | @section Custom Functions |
212 | |
213 | Readline provides a great many functions for manipulating the text of |
214 | the line. But it isn't possible to anticipate the needs of all |
215 | programs. This section describes the various functions and variables |
216 | defined in within the Readline library which allow a user program to add |
217 | customized functionality to Readline. |
218 | |
219 | @menu |
220 | * The Function Type:: C declarations to make code readable. |
221 | * Function Naming:: How to give a function you write a name. |
222 | * Keymaps:: Making keymaps. |
223 | * Binding Keys:: Changing Keymaps. |
224 | * Function Writing:: Variables and calling conventions. |
225 | * Allowing Undoing:: How to make your functions undoable. |
226 | @end menu |
227 | |
228 | @node The Function Type, Function Naming, Custom Functions, Custom Functions |
229 | For the sake of readabilty, we declare a new type of object, called |
230 | @dfn{Function}. `Function' is a C language function which returns an |
231 | @code{int}. The type declaration for `Function' is: |
232 | |
233 | @code{typedef int Function ();} |
234 | |
235 | The reason for declaring this new type is to make it easier to discuss |
236 | pointers to C functions. Let us say we had a variable called @var{func} |
237 | which was a pointer to a function. Instead of the classic C declaration |
238 | |
239 | @code{int (*)()func;} |
240 | |
241 | we have |
242 | |
243 | @code{Function *func;} |
244 | |
245 | @node Function Naming, Keymaps, The Function Type, Custom Functions |
246 | @subsection Naming a Function |
247 | |
248 | The user can dynamically change the bindings of keys while using |
249 | Readline. This is done by representing the function with a descriptive |
250 | name. The user is able to type the descriptive name when referring to |
251 | the function. Thus, in an init file, one might find |
252 | |
253 | @example |
254 | Meta-Rubout: backward-kill-word |
255 | @end example |
256 | |
257 | This binds @key{Meta-Rubout} to the function @emph{descriptively} named |
258 | @code{backward-kill-word}. You, as a programmer, should bind the |
259 | functions you write to descriptive names as well. Here is how to do |
260 | that. |
261 | |
262 | @defun rl_add_defun (char *name, Function *function, int key) |
263 | Add @var{name} to the list of named functions. Make @var{function} be |
264 | the function that gets called. If @var{key} is not -1, then bind it to |
265 | @var{function} using @code{rl_bind_key ()}. |
266 | @end defun |
267 | |
268 | Using this function alone is sufficient for most applications. It is |
269 | the recommended way to add a few functions to the default functions that |
270 | Readline has built in already. If you need to do more or different |
271 | things than adding a function to Readline, you may need to use the |
272 | underlying functions described below. |
273 | |
274 | @node Keymaps, Binding Keys, Function Naming, Custom Functions |
275 | @subsection Selecting a Keymap |
276 | |
277 | Key bindings take place on a @dfn{keymap}. The keymap is the |
278 | association between the keys that the user types and the functions that |
279 | get run. You can make your own keymaps, copy existing keymaps, and tell |
280 | Readline which keymap to use. |
281 | |
282 | @defun rl_make_bare_keymap () |
283 | Returns a new, empty keymap. The space for the keymap is allocated with |
284 | @code{malloc ()}; you should @code{free ()} it when you are done. |
285 | @end defun |
286 | |
287 | @defun rl_copy_keymap (Keymap map) |
288 | Return a new keymap which is a copy of @var{map}. |
289 | @end defun |
290 | |
291 | @defun rl_make_keymap () |
292 | Return a new keymap with the printing characters bound to rl_insert, |
293 | the lowercase Meta characters bound to run their equivalents, and |
294 | the Meta digits bound to produce numeric arguments. |
295 | @end defun |
296 | |
297 | @node Binding Keys, Function Writing, Keymaps, Custom Functions |
298 | @subsection Binding Keys |
299 | |
300 | You associate keys with functions through the keymap. Here are |
301 | the functions for doing that. |
302 | |
303 | @defun rl_bind_key (int key, Function *function) |
304 | Binds @var{key} to @var{function} in the currently selected keymap. |
305 | Returns non-zero in the case of an invalid @var{key}. |
306 | @end defun |
307 | |
308 | @defun rl_bind_key_in_map (int key, Function *function, Keymap map) |
309 | Bind @var{key} to @var{function} in @var{map}. Returns non-zero in the case |
310 | of an invalid @var{key}. |
311 | @end defun |
312 | |
313 | @defun rl_unbind_key (int key) |
314 | Make @var{key} do nothing in the currently selected keymap. |
315 | Returns non-zero in case of error. |
316 | @end defun |
317 | |
318 | @defun rl_unbind_key_in_map (int key, Keymap map) |
319 | Make @var{key} be bound to the null function in @var{map}. |
320 | Returns non-zero in case of error. |
321 | @end defun |
322 | |
323 | @node Function Writing, Allowing Undoing, Binding Keys, Custom Functions |
324 | @subsection Writing a New Function |
325 | |
326 | In order to write new functions for Readline, you need to know the |
327 | calling conventions for keyboard invoked functions, and the names of the |
328 | variables that describe the current state of the line gathered so far. |
329 | |
330 | @defvar char *rl_line_buffer |
331 | This is the line gathered so far. You are welcome to modify the |
332 | contents of this, but see Undoing, below. |
333 | @end defvar |
334 | |
335 | @defvar int rl_point |
336 | The offset of the current cursor position in @var{rl_line_buffer}. |
337 | @end defvar |
338 | |
339 | @defvar int rl_end |
340 | The number of characters present in @code{rl_line_buffer}. When |
341 | @code{rl_point} is at the end of the line, then @code{rl_point} and |
342 | @code{rl_end} are equal. |
343 | @end defvar |
344 | |
345 | The calling sequence for a command @code{foo} looks like |
346 | |
347 | @example |
348 | @code{foo (count, key)} |
349 | @end example |
350 | |
351 | where @var{count} is the numeric argument (or 1 if defaulted) and |
352 | @var{key} is the key that invoked this function. |
353 | |
354 | It is completely up to the function as to what should be done with the |
355 | numeric argument; some functions use it as a repeat count, other |
356 | functions as a flag, and some choose to ignore it. In general, if a |
357 | function uses the numeric argument as a repeat count, it should be able |
358 | to do something useful with a negative argument as well as a positive |
359 | argument. At the very least, it should be aware that it can be passed a |
360 | negative argument. |
361 | |
362 | @node Allowing Undoing, , Function Writing, Custom Functions |
363 | @subsection Allowing Undoing |
364 | |
365 | Supporting the undo command is a painless thing to do, and makes your |
366 | function much more useful to the end user. It is certainly easy to try |
367 | something if you know you can undo it. I could use an undo function for |
368 | the stock market. |
369 | |
370 | If your function simply inserts text once, or deletes text once, and it |
371 | calls @code{rl_insert_text ()} or @code{rl_delete_text ()} to do it, then |
372 | undoing is already done for you automatically, and you can safely skip |
373 | this section. |
374 | |
375 | If you do multiple insertions or multiple deletions, or any combination |
376 | of these operations, you will want to group them together into one |
377 | operation. This can be done with @code{rl_begin_undo_group ()} and |
378 | @code{rl_end_undo_group ()}. |
379 | |
380 | @defun rl_begin_undo_group () |
381 | Begins saving undo information in a group construct. The undo |
382 | information usually comes from calls to @code{rl_insert_text ()} and |
383 | @code{rl_delete_text ()}, but they could be direct calls to |
384 | @code{rl_add_undo ()}. |
385 | @end defun |
386 | |
387 | @defun rl_end_undo_group () |
388 | Closes the current undo group started with @code{rl_begin_undo_group |
389 | ()}. There should be exactly one call to @code{rl_end_undo_group ()} |
390 | for every call to @code{rl_begin_undo_group ()}. |
391 | @end defun |
392 | |
393 | Finally, if you neither insert nor delete text, but directly modify the |
394 | existing text (e.g. change its case), you call @code{rl_modifying ()} |
395 | once, just before you modify the text. You must supply the indices of |
396 | the text range that you are going to modify. |
397 | |
398 | @defun rl_modifying (int start, int end) |
399 | Tell Readline to save the text between @var{start} and @var{end} as a |
400 | single undo unit. It is assumed that subsequent to this call you will |
401 | modify that range of text in some way. |
402 | @end defun |
403 | |
404 | @subsection An Example |
405 | |
406 | Let us say that we are actually going to put an example here. |
407 | |
408 | @node Custom Completers, Variable Index, Custom Functions, Readline Technical |
409 | |
410 | Typically, a program that reads commands from the user has a way of |
411 | disambiguating between commands and data. If your program is one of |
412 | these, then it can provide completion for either commands, or data, or |
413 | both commands and data. The following sections describe how your |
414 | program and Readline cooperate to provide this service to end users. |
415 | |
416 | @menu |
417 | @end menu |
418 | |
419 | @node Variable Index, , Custom Completers, Readline Technical |
420 | @appendix Variable Index |
421 | @printindex vr |
422 | @contents |
423 | |
424 | @bye |
425 | |