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.)
11 * Readline: (readline). The GNU Readline Library.
21 This document describes the GNU Readline Library, a utility for aiding
22 in the consitency of user interface across discrete programs that need
23 to provide a command line interface.
25 Copyright (C) 1988 Free Software Foundation, Inc.
27 Permission is granted to make and distribute verbatim copies of
28 this manual provided the copyright notice and this permission notice
29 pare preserved on all copies.
32 Permission is granted to process this file through TeX and print the
33 results, provided the printed document carries copying permission
34 notice identical to this one except for the removal of this paragraph
35 (this paragraph not being relevant to the printed manual).
38 Permission is granted to copy and distribute modified versions of this
39 manual under the conditions for verbatim copying, provided that the entire
40 resulting derived work is distributed under the terms of a permission
41 notice identical to this one.
43 Permission is granted to copy and distribute translations of this manual
44 into another language, under the above conditions for modified versions,
45 except that this permission notice may be stated in a translation approved
49 @setchapternewpage odd
52 @center @titlefont{GNU Readline Library}
60 @comment Include the Distribution inside the titlepage environment so
61 @c that headings are turned off.
64 @vskip 0pt plus 1filll
65 Copyright @copyright{} 1989 Free Software Foundation, Inc.
68 This document describes the GNU Readline Library, a utility for aiding
69 in the consistency of user interface across discrete programs that need
70 to provide a command line interface.
73 Published by the Free Software Foundation @*
74 675 Massachusetts Avenue, @*
75 Cambridge, MA 02139 USA
77 Permission is granted to make and distribute verbatim copies of
78 this manual provided the copyright notice and this permission notice
79 are preserved on all copies.
81 Permission is granted to copy and distribute modified versions of this
82 manual under the conditions for verbatim copying, provided that the entire
83 resulting derived work is distributed under the terms of a permission
84 notice identical to this one.
86 Permission is granted to copy and distribute translations of this manual
87 into another language, under the above conditions for modified versions,
88 except that this permission notice may be stated in a translation approved
94 @chapter GNU Readline Library
97 This document describes the GNU Readline Library, a utility for aiding
98 in the consistency of user interface across discrete programs that need
99 to provide a command line interface.
103 * Command Line Editing:: GNU Readline User's Manual
104 * Readline Technical:: GNU Readline Programmer's Manual
106 @include inc-read.texi
107 @node Readline Technical, , Top, Top
108 @chapter Readline Programmer's Manual
110 This manual describes the interface between the GNU Readline Library and
111 user programs. If you are a programmer, and you wish to include the
112 features found in GNU Readline in your own programs, such as completion,
113 line editing, and interactive history manipulation, this documentation
117 * Default Behaviour:: Using the default behaviour of Readline.
118 * Custom Functions:: Adding your own functions to Readline.
119 * Custom Completers:: Supplanting or supplementing Readline's
120 completion functions.
121 * Variable Index:: Index of externally tweakable variables.
124 @node Default Behaviour, Custom Functions, Readline Technical, Readline Technical
125 @section Default Behaviour
127 Many programs provide a command line interface, such as @code{mail},
128 @code{ftp}, and @code{sh}. For such programs, the default behaviour of
129 Readline is sufficient. This section describes how to use Readline in
130 the simplest way possible, perhaps to replace calls in your code to
134 @cindex readline, function
135 The function @code{readline} prints a prompt and then reads and returns
136 a single line of text from the user. The line which @code{readline ()}
137 returns is allocated with @code{malloc ()}; you should @code{free ()}
138 the line when you are done with it. The declaration in ANSI C is
141 @code{char *readline (char *@var{prompt});}
145 @code{#include <readline/readline.h>}
150 @code{char *line = readline ("Enter a line: ");}
152 in order to read a line of text from the user.
154 The line which is returned has the final newline removed, so only the
155 text of the line remains.
157 If readline encounters an EOF while reading the line, and the line is
158 empty at that point, then @code{(char *)NULL} is returned. Otherwise,
159 the line is ended just as if a newline was typed.
161 If you want the user to be able to get at the line later, (with
162 @key{C-p} for example), you must call @code{add_history ()} to save the
163 line away in a @dfn{history} list of such lines.
166 @code{add_history (line)};
169 If you use @code{add_history ()}, you should also
170 @code{#include <readline/history.h>}
171 For full details on the GNU History Library, see the associated manual.
173 It is polite to avoid saving empty lines on the history list, since
174 no one has a burning need to reuse a blank line. Here is a function
175 which usefully replaces the standard @code{gets ()} library function:
178 #include <readline/readline.h>
179 #include <readline/history.h>
181 /* A static variable for holding the line. */
182 static char *my_gets_line = (char *)NULL;
184 /* Read a string, and return a pointer to it. Returns NULL on EOF. */
188 /* If the buffer has already been allocated, return the memory
190 if (my_gets_line != (char *)NULL)
193 /* Get a line from the user. */
194 my_gets_line = readline ("");
196 /* If the line has any text in it, save it on the history. */
197 if (my_get_line && *my_gets_line)
198 add_history (my_gets_line);
200 return (my_gets_line);
204 The above code gives the user the default behaviour of @key{TAB}
205 completion: completion on file names. If you do not want readline to
206 complete on filenames, you can change the binding of the @key{TAB} key
207 with @code{rl_bind_key ()}.
209 @findex rl_bind_key ()
212 @code{int rl_bind_key (int @var{key}, (int (*)())@var{function});}
215 @code{rl_bind_key ()} takes 2 arguments; @var{key} is the character that
216 you want to bind, and @var{function} is the address of the function to
217 run when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert ()}
218 makes @key{TAB} just insert itself.
220 @code{rl_bind_key ()} returns non-zero if @var{key} is not a valid
221 ASCII character code (between 0 and 255).
224 @code{rl_bind_key ('\t', rl_insert);}
227 @node Custom Functions, Custom Completers, Default Behaviour, Readline Technical
228 @section Custom Functions
230 Readline provides a great many functions for manipulating the text of
231 the line. But it isn't possible to anticipate the needs of all
232 programs. This section describes the various functions and variables
233 defined in within the Readline library which allow a user program to add
234 customized functionality to Readline.
237 * The Function Type:: C declarations to make code readable.
238 * Function Naming:: How to give a function you write a name.
239 * Keymaps:: Making keymaps.
240 * Binding Keys:: Changing Keymaps.
241 * Function Writing:: Variables and calling conventions.
242 * Allowing Undoing:: How to make your functions undoable.
245 @node The Function Type, Function Naming, Custom Functions, Custom Functions
246 For the sake of readabilty, we declare a new type of object, called
247 @dfn{Function}. `Function' is a C language function which returns an
248 @code{int}. The type declaration for `Function' is:
250 @code{typedef int Function ();}
252 The reason for declaring this new type is to make it easier to discuss
253 pointers to C functions. Let us say we had a variable called @var{func}
254 which was a pointer to a function. Instead of the classic C declaration
256 @code{int (*)()func;}
260 @code{Function *func;}
262 @node Function Naming, Keymaps, The Function Type, Custom Functions
263 @subsection Naming a Function
265 The user can dynamically change the bindings of keys while using
266 Readline. This is done by representing the function with a descriptive
267 name. The user is able to type the descriptive name when referring to
268 the function. Thus, in an init file, one might find
271 Meta-Rubout: backward-kill-word
274 This binds @key{Meta-Rubout} to the function @emph{descriptively} named
275 @code{backward-kill-word}. You, as a programmer, should bind the
276 functions you write to descriptive names as well. Here is how to do
279 @defun rl_add_defun (char *name, Function *function, int key)
280 Add @var{name} to the list of named functions. Make @var{function} be
281 the function that gets called. If @var{key} is not -1, then bind it to
282 @var{function} using @code{rl_bind_key ()}.
285 Using this function alone is sufficient for most applications. It is
286 the recommended way to add a few functions to the default functions that
287 Readline has built in already. If you need to do more or different
288 things than adding a function to Readline, you may need to use the
289 underlying functions described below.
291 @node Keymaps, Binding Keys, Function Naming, Custom Functions
292 @subsection Selecting a Keymap
294 Key bindings take place on a @dfn{keymap}. The keymap is the
295 association between the keys that the user types and the functions that
296 get run. You can make your own keymaps, copy existing keymaps, and tell
297 Readline which keymap to use.
299 @defun rl_make_bare_keymap ()
300 Returns a new, empty keymap. The space for the keymap is allocated with
301 @code{malloc ()}; you should @code{free ()} it when you are done.
304 @defun rl_copy_keymap (Keymap map)
305 Return a new keymap which is a copy of @var{map}.
308 @defun rl_make_keymap ()
309 Return a new keymap with the printing characters bound to rl_insert,
310 the lowercase Meta characters bound to run their equivalents, and
311 the Meta digits bound to produce numeric arguments.
314 @node Binding Keys, Function Writing, Keymaps, Custom Functions
315 @subsection Binding Keys
317 You associate keys with functions through the keymap. Here are
318 the functions for doing that.
320 @defun rl_bind_key (int key, Function *function)
321 Binds @var{key} to @var{function} in the currently selected keymap.
322 Returns non-zero in the case of an invalid @var{key}.
325 @defun rl_bind_key_in_map (int key, Function *function, Keymap map)
326 Bind @var{key} to @var{function} in @var{map}. Returns non-zero in the case
327 of an invalid @var{key}.
330 @defun rl_unbind_key (int key)
331 Make @var{key} do nothing in the currently selected keymap.
332 Returns non-zero in case of error.
335 @defun rl_unbind_key_in_map (int key, Keymap map)
336 Make @var{key} be bound to the null function in @var{map}.
337 Returns non-zero in case of error.
340 @node Function Writing, Allowing Undoing, Binding Keys, Custom Functions
341 @subsection Writing a New Function
343 In order to write new functions for Readline, you need to know the
344 calling conventions for keyboard invoked functions, and the names of the
345 variables that describe the current state of the line gathered so far.
347 @defvar char *rl_line_buffer
348 This is the line gathered so far. You are welcome to modify the
349 contents of this, but see Undoing, below.
353 The offset of the current cursor position in @var{rl_line_buffer}.
357 The number of characters present in @code{rl_line_buffer}. When
358 @code{rl_point} is at the end of the line, then @code{rl_point} and
359 @code{rl_end} are equal.
362 The calling sequence for a command @code{foo} looks like
365 @code{foo (count, key)}
368 where @var{count} is the numeric argument (or 1 if defaulted) and
369 @var{key} is the key that invoked this function.
371 It is completely up to the function as to what should be done with the
372 numeric argument; some functions use it as a repeat count, other
373 functions as a flag, and some choose to ignore it. In general, if a
374 function uses the numeric argument as a repeat count, it should be able
375 to do something useful with a negative argument as well as a positive
376 argument. At the very least, it should be aware that it can be passed a
379 @node Allowing Undoing, , Function Writing, Custom Functions
380 @subsection Allowing Undoing
382 Supporting the undo command is a painless thing to do, and makes your
383 function much more useful to the end user. It is certainly easy to try
384 something if you know you can undo it. I could use an undo function for
387 If your function simply inserts text once, or deletes text once, and it
388 calls @code{rl_insert_text ()} or @code{rl_delete_text ()} to do it, then
389 undoing is already done for you automatically, and you can safely skip
392 If you do multiple insertions or multiple deletions, or any combination
393 of these operations, you will want to group them together into one
394 operation. This can be done with @code{rl_begin_undo_group ()} and
395 @code{rl_end_undo_group ()}.
397 @defun rl_begin_undo_group ()
398 Begins saving undo information in a group construct. The undo
399 information usually comes from calls to @code{rl_insert_text ()} and
400 @code{rl_delete_text ()}, but they could be direct calls to
401 @code{rl_add_undo ()}.
404 @defun rl_end_undo_group ()
405 Closes the current undo group started with @code{rl_begin_undo_group
406 ()}. There should be exactly one call to @code{rl_end_undo_group ()}
407 for every call to @code{rl_begin_undo_group ()}.
410 Finally, if you neither insert nor delete text, but directly modify the
411 existing text (e.g. change its case), you call @code{rl_modifying ()}
412 once, just before you modify the text. You must supply the indices of
413 the text range that you are going to modify.
415 @defun rl_modifying (int start, int end)
416 Tell Readline to save the text between @var{start} and @var{end} as a
417 single undo unit. It is assumed that subsequent to this call you will
418 modify that range of text in some way.
421 @subsection An Example
423 Let us say that we are actually going to put an example here.
425 @node Custom Completers, Variable Index, Custom Functions, Readline Technical
427 Typically, a program that reads commands from the user has a way of
428 disambiguating between commands and data. If your program is one of
429 these, then it can provide completion for either commands, or data, or
430 both commands and data. The following sections describe how your
431 program and Readline cooperate to provide this service to end users.
436 @node Variable Index, , Custom Completers, Readline Technical
437 @appendix Variable Index