1 |
578 |
markom |
@comment %**start of header (This is for running Texinfo on a region.)
|
2 |
|
|
@setfilename rltech.info
|
3 |
|
|
@comment %**end of header (This is for running Texinfo on a region.)
|
4 |
|
|
@setchapternewpage odd
|
5 |
|
|
|
6 |
|
|
@ifinfo
|
7 |
|
|
This document describes the GNU Readline Library, a utility for aiding
|
8 |
|
|
in the consitency of user interface across discrete programs that need
|
9 |
|
|
to provide a command line interface.
|
10 |
|
|
|
11 |
|
|
Copyright (C) 1988, 1994, 1996, 1998, 1999 Free Software Foundation, Inc.
|
12 |
|
|
|
13 |
|
|
Permission is granted to make and distribute verbatim copies of
|
14 |
|
|
this manual provided the copyright notice and this permission notice
|
15 |
|
|
pare preserved on all copies.
|
16 |
|
|
|
17 |
|
|
@ignore
|
18 |
|
|
Permission is granted to process this file through TeX and print the
|
19 |
|
|
results, provided the printed document carries copying permission
|
20 |
|
|
notice identical to this one except for the removal of this paragraph
|
21 |
|
|
(this paragraph not being relevant to the printed manual).
|
22 |
|
|
@end ignore
|
23 |
|
|
|
24 |
|
|
Permission is granted to copy and distribute modified versions of this
|
25 |
|
|
manual under the conditions for verbatim copying, provided that the entire
|
26 |
|
|
resulting derived work is distributed under the terms of a permission
|
27 |
|
|
notice identical to this one.
|
28 |
|
|
|
29 |
|
|
Permission is granted to copy and distribute translations of this manual
|
30 |
|
|
into another language, under the above conditions for modified versions,
|
31 |
|
|
except that this permission notice may be stated in a translation approved
|
32 |
|
|
by the Foundation.
|
33 |
|
|
@end ifinfo
|
34 |
|
|
|
35 |
|
|
@node Programming with GNU Readline
|
36 |
|
|
@chapter Programming with GNU Readline
|
37 |
|
|
|
38 |
|
|
This chapter describes the interface between the GNU Readline Library and
|
39 |
|
|
other programs. If you are a programmer, and you wish to include the
|
40 |
|
|
features found in GNU Readline
|
41 |
|
|
such as completion, line editing, and interactive history manipulation
|
42 |
|
|
in your own programs, this section is for you.
|
43 |
|
|
|
44 |
|
|
@menu
|
45 |
|
|
* Basic Behavior:: Using the default behavior of Readline.
|
46 |
|
|
* Custom Functions:: Adding your own functions to Readline.
|
47 |
|
|
* Readline Variables:: Variables accessible to custom
|
48 |
|
|
functions.
|
49 |
|
|
* Readline Convenience Functions:: Functions which Readline supplies to
|
50 |
|
|
aid in writing your own custom
|
51 |
|
|
functions.
|
52 |
|
|
* Readline Signal Handling:: How Readline behaves when it receives signals.
|
53 |
|
|
* Custom Completers:: Supplanting or supplementing Readline's
|
54 |
|
|
completion functions.
|
55 |
|
|
@end menu
|
56 |
|
|
|
57 |
|
|
@node Basic Behavior
|
58 |
|
|
@section Basic Behavior
|
59 |
|
|
|
60 |
|
|
Many programs provide a command line interface, such as @code{mail},
|
61 |
|
|
@code{ftp}, and @code{sh}. For such programs, the default behaviour of
|
62 |
|
|
Readline is sufficient. This section describes how to use Readline in
|
63 |
|
|
the simplest way possible, perhaps to replace calls in your code to
|
64 |
|
|
@code{gets()} or @code{fgets ()}.
|
65 |
|
|
|
66 |
|
|
@findex readline
|
67 |
|
|
@cindex readline, function
|
68 |
|
|
The function @code{readline ()} prints a prompt and then reads and returns
|
69 |
|
|
a single line of text from the user. The line @code{readline}
|
70 |
|
|
returns is allocated with @code{malloc ()}; you should @code{free ()}
|
71 |
|
|
the line when you are done with it. The declaration for @code{readline}
|
72 |
|
|
in ANSI C is
|
73 |
|
|
|
74 |
|
|
@example
|
75 |
|
|
@code{char *readline (char *@var{prompt});}
|
76 |
|
|
@end example
|
77 |
|
|
|
78 |
|
|
@noindent
|
79 |
|
|
So, one might say
|
80 |
|
|
@example
|
81 |
|
|
@code{char *line = readline ("Enter a line: ");}
|
82 |
|
|
@end example
|
83 |
|
|
@noindent
|
84 |
|
|
in order to read a line of text from the user.
|
85 |
|
|
The line returned has the final newline removed, so only the
|
86 |
|
|
text remains.
|
87 |
|
|
|
88 |
|
|
If @code{readline} encounters an @code{EOF} while reading the line, and the
|
89 |
|
|
line is empty at that point, then @code{(char *)NULL} is returned.
|
90 |
|
|
Otherwise, the line is ended just as if a newline had been typed.
|
91 |
|
|
|
92 |
|
|
If you want the user to be able to get at the line later, (with
|
93 |
|
|
@key{C-p} for example), you must call @code{add_history ()} to save the
|
94 |
|
|
line away in a @dfn{history} list of such lines.
|
95 |
|
|
|
96 |
|
|
@example
|
97 |
|
|
@code{add_history (line)};
|
98 |
|
|
@end example
|
99 |
|
|
|
100 |
|
|
@noindent
|
101 |
|
|
For full details on the GNU History Library, see the associated manual.
|
102 |
|
|
|
103 |
|
|
It is preferable to avoid saving empty lines on the history list, since
|
104 |
|
|
users rarely have a burning need to reuse a blank line. Here is
|
105 |
|
|
a function which usefully replaces the standard @code{gets ()} library
|
106 |
|
|
function, and has the advantage of no static buffer to overflow:
|
107 |
|
|
|
108 |
|
|
@example
|
109 |
|
|
/* A static variable for holding the line. */
|
110 |
|
|
static char *line_read = (char *)NULL;
|
111 |
|
|
|
112 |
|
|
/* Read a string, and return a pointer to it. Returns NULL on EOF. */
|
113 |
|
|
char *
|
114 |
|
|
rl_gets ()
|
115 |
|
|
@{
|
116 |
|
|
/* If the buffer has already been allocated, return the memory
|
117 |
|
|
to the free pool. */
|
118 |
|
|
if (line_read)
|
119 |
|
|
@{
|
120 |
|
|
free (line_read);
|
121 |
|
|
line_read = (char *)NULL;
|
122 |
|
|
@}
|
123 |
|
|
|
124 |
|
|
/* Get a line from the user. */
|
125 |
|
|
line_read = readline ("");
|
126 |
|
|
|
127 |
|
|
/* If the line has any text in it, save it on the history. */
|
128 |
|
|
if (line_read && *line_read)
|
129 |
|
|
add_history (line_read);
|
130 |
|
|
|
131 |
|
|
return (line_read);
|
132 |
|
|
@}
|
133 |
|
|
@end example
|
134 |
|
|
|
135 |
|
|
This function gives the user the default behaviour of @key{TAB}
|
136 |
|
|
completion: completion on file names. If you do not want Readline to
|
137 |
|
|
complete on filenames, you can change the binding of the @key{TAB} key
|
138 |
|
|
with @code{rl_bind_key ()}.
|
139 |
|
|
|
140 |
|
|
@example
|
141 |
|
|
@code{int rl_bind_key (int @var{key}, int (*@var{function})());}
|
142 |
|
|
@end example
|
143 |
|
|
|
144 |
|
|
@code{rl_bind_key ()} takes two arguments: @var{key} is the character that
|
145 |
|
|
you want to bind, and @var{function} is the address of the function to
|
146 |
|
|
call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert ()}
|
147 |
|
|
makes @key{TAB} insert itself.
|
148 |
|
|
@code{rl_bind_key ()} returns non-zero if @var{key} is not a valid
|
149 |
|
|
ASCII character code (between 0 and 255).
|
150 |
|
|
|
151 |
|
|
Thus, to disable the default @key{TAB} behavior, the following suffices:
|
152 |
|
|
@example
|
153 |
|
|
@code{rl_bind_key ('\t', rl_insert);}
|
154 |
|
|
@end example
|
155 |
|
|
|
156 |
|
|
This code should be executed once at the start of your program; you
|
157 |
|
|
might write a function called @code{initialize_readline ()} which
|
158 |
|
|
performs this and other desired initializations, such as installing
|
159 |
|
|
custom completers (@pxref{Custom Completers}).
|
160 |
|
|
|
161 |
|
|
@node Custom Functions
|
162 |
|
|
@section Custom Functions
|
163 |
|
|
|
164 |
|
|
Readline provides many functions for manipulating the text of
|
165 |
|
|
the line, but it isn't possible to anticipate the needs of all
|
166 |
|
|
programs. This section describes the various functions and variables
|
167 |
|
|
defined within the Readline library which allow a user program to add
|
168 |
|
|
customized functionality to Readline.
|
169 |
|
|
|
170 |
|
|
Before declaring any functions that customize Readline's behavior, or
|
171 |
|
|
using any functionality Readline provides in other code, an
|
172 |
|
|
application writer should include the file @code{<readline/readline.h>}
|
173 |
|
|
in any file that uses Readline's features. Since some of the definitions
|
174 |
|
|
in @code{readline.h} use the @code{stdio} library, the file
|
175 |
|
|
@code{<stdio.h>} should be included before @code{readline.h}.
|
176 |
|
|
|
177 |
|
|
@menu
|
178 |
|
|
* The Function Type:: C declarations to make code readable.
|
179 |
|
|
* Function Writing:: Variables and calling conventions.
|
180 |
|
|
@end menu
|
181 |
|
|
|
182 |
|
|
@node The Function Type
|
183 |
|
|
@subsection The Function Type
|
184 |
|
|
|
185 |
|
|
For readabilty, we declare a new type of object, called
|
186 |
|
|
@dfn{Function}. A @code{Function} is a C function which
|
187 |
|
|
returns an @code{int}. The type declaration for @code{Function} is:
|
188 |
|
|
|
189 |
|
|
@noindent
|
190 |
|
|
@code{typedef int Function ();}
|
191 |
|
|
|
192 |
|
|
The reason for declaring this new type is to make it easier to write
|
193 |
|
|
code describing pointers to C functions. Let us say we had a variable
|
194 |
|
|
called @var{func} which was a pointer to a function. Instead of the
|
195 |
|
|
classic C declaration
|
196 |
|
|
|
197 |
|
|
@code{int (*)()func;}
|
198 |
|
|
|
199 |
|
|
@noindent
|
200 |
|
|
we may write
|
201 |
|
|
|
202 |
|
|
@code{Function *func;}
|
203 |
|
|
|
204 |
|
|
@noindent
|
205 |
|
|
Similarly, there are
|
206 |
|
|
|
207 |
|
|
@example
|
208 |
|
|
typedef void VFunction ();
|
209 |
|
|
typedef char *CPFunction (); @r{and}
|
210 |
|
|
typedef char **CPPFunction ();
|
211 |
|
|
@end example
|
212 |
|
|
|
213 |
|
|
@noindent
|
214 |
|
|
for functions returning no value, @code{pointer to char}, and
|
215 |
|
|
@code{pointer to pointer to char}, respectively.
|
216 |
|
|
|
217 |
|
|
@node Function Writing
|
218 |
|
|
@subsection Writing a New Function
|
219 |
|
|
|
220 |
|
|
In order to write new functions for Readline, you need to know the
|
221 |
|
|
calling conventions for keyboard-invoked functions, and the names of the
|
222 |
|
|
variables that describe the current state of the line read so far.
|
223 |
|
|
|
224 |
|
|
The calling sequence for a command @code{foo} looks like
|
225 |
|
|
|
226 |
|
|
@example
|
227 |
|
|
@code{foo (int count, int key)}
|
228 |
|
|
@end example
|
229 |
|
|
|
230 |
|
|
@noindent
|
231 |
|
|
where @var{count} is the numeric argument (or 1 if defaulted) and
|
232 |
|
|
@var{key} is the key that invoked this function.
|
233 |
|
|
|
234 |
|
|
It is completely up to the function as to what should be done with the
|
235 |
|
|
numeric argument. Some functions use it as a repeat count, some
|
236 |
|
|
as a flag, and others to choose alternate behavior (refreshing the current
|
237 |
|
|
line as opposed to refreshing the screen, for example). Some choose to
|
238 |
|
|
ignore it. In general, if a
|
239 |
|
|
function uses the numeric argument as a repeat count, it should be able
|
240 |
|
|
to do something useful with both negative and positive arguments.
|
241 |
|
|
At the very least, it should be aware that it can be passed a
|
242 |
|
|
negative argument.
|
243 |
|
|
|
244 |
|
|
@node Readline Variables
|
245 |
|
|
@section Readline Variables
|
246 |
|
|
|
247 |
|
|
These variables are available to function writers.
|
248 |
|
|
|
249 |
|
|
@deftypevar {char *} rl_line_buffer
|
250 |
|
|
This is the line gathered so far. You are welcome to modify the
|
251 |
|
|
contents of the line, but see @ref{Allowing Undoing}. The
|
252 |
|
|
function @code{rl_extend_line_buffer} is available to increase
|
253 |
|
|
the memory allocated to @code{rl_line_buffer}.
|
254 |
|
|
@end deftypevar
|
255 |
|
|
|
256 |
|
|
@deftypevar int rl_point
|
257 |
|
|
The offset of the current cursor position in @code{rl_line_buffer}
|
258 |
|
|
(the @emph{point}).
|
259 |
|
|
@end deftypevar
|
260 |
|
|
|
261 |
|
|
@deftypevar int rl_end
|
262 |
|
|
The number of characters present in @code{rl_line_buffer}. When
|
263 |
|
|
@code{rl_point} is at the end of the line, @code{rl_point} and
|
264 |
|
|
@code{rl_end} are equal.
|
265 |
|
|
@end deftypevar
|
266 |
|
|
|
267 |
|
|
@deftypevar int rl_mark
|
268 |
|
|
The mark (saved position) in the current line. If set, the mark
|
269 |
|
|
and point define a @emph{region}.
|
270 |
|
|
@end deftypevar
|
271 |
|
|
|
272 |
|
|
@deftypevar int rl_done
|
273 |
|
|
Setting this to a non-zero value causes Readline to return the current
|
274 |
|
|
line immediately.
|
275 |
|
|
@end deftypevar
|
276 |
|
|
|
277 |
|
|
@deftypevar int rl_pending_input
|
278 |
|
|
Setting this to a value makes it the next keystroke read. This is a
|
279 |
|
|
way to stuff a single character into the input stream.
|
280 |
|
|
@end deftypevar
|
281 |
|
|
|
282 |
|
|
@deftypevar int rl_erase_empty_line
|
283 |
|
|
Setting this to a non-zero value causes Readline to completely erase
|
284 |
|
|
the current line, including any prompt, any time a newline is typed as
|
285 |
|
|
the only character on an otherwise-empty line. The cursor is moved to
|
286 |
|
|
the beginning of the newly-blank line.
|
287 |
|
|
@end deftypevar
|
288 |
|
|
|
289 |
|
|
@deftypevar {char *} rl_prompt
|
290 |
|
|
The prompt Readline uses. This is set from the argument to
|
291 |
|
|
@code{readline ()}, and should not be assigned to directly.
|
292 |
|
|
@end deftypevar
|
293 |
|
|
|
294 |
|
|
@deftypevar int rl_already_prompted
|
295 |
|
|
If an application wishes to display the prompt itself, rather than have
|
296 |
|
|
Readline do it the first time @code{readline()} is called, it should set
|
297 |
|
|
this variable to a non-zero value after displaying the prompt.
|
298 |
|
|
The prompt must also be passed as the argument to @code{readline()} so
|
299 |
|
|
the redisplay functions can update the display properly.
|
300 |
|
|
The calling application is responsible for managing the value; Readline
|
301 |
|
|
never sets it.
|
302 |
|
|
@end deftypevar
|
303 |
|
|
|
304 |
|
|
@deftypevar {char *} rl_library_version
|
305 |
|
|
The version number of this revision of the library.
|
306 |
|
|
@end deftypevar
|
307 |
|
|
|
308 |
|
|
@deftypevar {char *} rl_terminal_name
|
309 |
|
|
The terminal type, used for initialization.
|
310 |
|
|
@end deftypevar
|
311 |
|
|
|
312 |
|
|
@deftypevar {char *} rl_readline_name
|
313 |
|
|
This variable is set to a unique name by each application using Readline.
|
314 |
|
|
The value allows conditional parsing of the inputrc file
|
315 |
|
|
(@pxref{Conditional Init Constructs}).
|
316 |
|
|
@end deftypevar
|
317 |
|
|
|
318 |
|
|
@deftypevar {FILE *} rl_instream
|
319 |
|
|
The stdio stream from which Readline reads input.
|
320 |
|
|
@end deftypevar
|
321 |
|
|
|
322 |
|
|
@deftypevar {FILE *} rl_outstream
|
323 |
|
|
The stdio stream to which Readline performs output.
|
324 |
|
|
@end deftypevar
|
325 |
|
|
|
326 |
|
|
@deftypevar {Function *} rl_startup_hook
|
327 |
|
|
If non-zero, this is the address of a function to call just
|
328 |
|
|
before @code{readline} prints the first prompt.
|
329 |
|
|
@end deftypevar
|
330 |
|
|
|
331 |
|
|
@deftypevar {Function *} rl_pre_input_hook
|
332 |
|
|
If non-zero, this is the address of a function to call after
|
333 |
|
|
the first prompt has been printed and just before @code{readline}
|
334 |
|
|
starts reading input characters.
|
335 |
|
|
@end deftypevar
|
336 |
|
|
|
337 |
|
|
@deftypevar {Function *} rl_event_hook
|
338 |
|
|
If non-zero, this is the address of a function to call periodically
|
339 |
|
|
when readline is waiting for terminal input.
|
340 |
|
|
@end deftypevar
|
341 |
|
|
|
342 |
|
|
@deftypevar {Function *} rl_getc_function
|
343 |
|
|
If non-zero, @code{readline} will call indirectly through this pointer
|
344 |
|
|
to get a character from the input stream. By default, it is set to
|
345 |
|
|
@code{rl_getc}, the default @code{readline} character input function
|
346 |
|
|
(@pxref{Utility Functions}).
|
347 |
|
|
@end deftypevar
|
348 |
|
|
|
349 |
|
|
@deftypevar {VFunction *} rl_redisplay_function
|
350 |
|
|
If non-zero, @code{readline} will call indirectly through this pointer
|
351 |
|
|
to update the display with the current contents of the editing buffer.
|
352 |
|
|
By default, it is set to @code{rl_redisplay}, the default @code{readline}
|
353 |
|
|
redisplay function (@pxref{Redisplay}).
|
354 |
|
|
@end deftypevar
|
355 |
|
|
|
356 |
|
|
@deftypevar {Keymap} rl_executing_keymap
|
357 |
|
|
This variable is set to the keymap (@pxref{Keymaps}) in which the
|
358 |
|
|
currently executing readline function was found.
|
359 |
|
|
@end deftypevar
|
360 |
|
|
|
361 |
|
|
@deftypevar {Keymap} rl_binding_keymap
|
362 |
|
|
This variable is set to the keymap (@pxref{Keymaps}) in which the
|
363 |
|
|
last key binding occurred.
|
364 |
|
|
@end deftypevar
|
365 |
|
|
|
366 |
|
|
@node Readline Convenience Functions
|
367 |
|
|
@section Readline Convenience Functions
|
368 |
|
|
|
369 |
|
|
@menu
|
370 |
|
|
* Function Naming:: How to give a function you write a name.
|
371 |
|
|
* Keymaps:: Making keymaps.
|
372 |
|
|
* Binding Keys:: Changing Keymaps.
|
373 |
|
|
* Associating Function Names and Bindings:: Translate function names to
|
374 |
|
|
key sequences.
|
375 |
|
|
* Allowing Undoing:: How to make your functions undoable.
|
376 |
|
|
* Redisplay:: Functions to control line display.
|
377 |
|
|
* Modifying Text:: Functions to modify @code{rl_line_buffer}.
|
378 |
|
|
* Utility Functions:: Generally useful functions and hooks.
|
379 |
|
|
* Alternate Interface:: Using Readline in a `callback' fashion.
|
380 |
|
|
@end menu
|
381 |
|
|
|
382 |
|
|
@node Function Naming
|
383 |
|
|
@subsection Naming a Function
|
384 |
|
|
|
385 |
|
|
The user can dynamically change the bindings of keys while using
|
386 |
|
|
Readline. This is done by representing the function with a descriptive
|
387 |
|
|
name. The user is able to type the descriptive name when referring to
|
388 |
|
|
the function. Thus, in an init file, one might find
|
389 |
|
|
|
390 |
|
|
@example
|
391 |
|
|
Meta-Rubout: backward-kill-word
|
392 |
|
|
@end example
|
393 |
|
|
|
394 |
|
|
This binds the keystroke @key{Meta-Rubout} to the function
|
395 |
|
|
@emph{descriptively} named @code{backward-kill-word}. You, as the
|
396 |
|
|
programmer, should bind the functions you write to descriptive names as
|
397 |
|
|
well. Readline provides a function for doing that:
|
398 |
|
|
|
399 |
|
|
@deftypefun int rl_add_defun (char *name, Function *function, int key)
|
400 |
|
|
Add @var{name} to the list of named functions. Make @var{function} be
|
401 |
|
|
the function that gets called. If @var{key} is not -1, then bind it to
|
402 |
|
|
@var{function} using @code{rl_bind_key ()}.
|
403 |
|
|
@end deftypefun
|
404 |
|
|
|
405 |
|
|
Using this function alone is sufficient for most applications. It is
|
406 |
|
|
the recommended way to add a few functions to the default functions that
|
407 |
|
|
Readline has built in. If you need to do something other
|
408 |
|
|
than adding a function to Readline, you may need to use the
|
409 |
|
|
underlying functions described below.
|
410 |
|
|
|
411 |
|
|
@node Keymaps
|
412 |
|
|
@subsection Selecting a Keymap
|
413 |
|
|
|
414 |
|
|
Key bindings take place on a @dfn{keymap}. The keymap is the
|
415 |
|
|
association between the keys that the user types and the functions that
|
416 |
|
|
get run. You can make your own keymaps, copy existing keymaps, and tell
|
417 |
|
|
Readline which keymap to use.
|
418 |
|
|
|
419 |
|
|
@deftypefun Keymap rl_make_bare_keymap ()
|
420 |
|
|
Returns a new, empty keymap. The space for the keymap is allocated with
|
421 |
|
|
@code{malloc ()}; you should @code{free ()} it when you are done.
|
422 |
|
|
@end deftypefun
|
423 |
|
|
|
424 |
|
|
@deftypefun Keymap rl_copy_keymap (Keymap map)
|
425 |
|
|
Return a new keymap which is a copy of @var{map}.
|
426 |
|
|
@end deftypefun
|
427 |
|
|
|
428 |
|
|
@deftypefun Keymap rl_make_keymap ()
|
429 |
|
|
Return a new keymap with the printing characters bound to rl_insert,
|
430 |
|
|
the lowercase Meta characters bound to run their equivalents, and
|
431 |
|
|
the Meta digits bound to produce numeric arguments.
|
432 |
|
|
@end deftypefun
|
433 |
|
|
|
434 |
|
|
@deftypefun void rl_discard_keymap (Keymap keymap)
|
435 |
|
|
Free the storage associated with @var{keymap}.
|
436 |
|
|
@end deftypefun
|
437 |
|
|
|
438 |
|
|
Readline has several internal keymaps. These functions allow you to
|
439 |
|
|
change which keymap is active.
|
440 |
|
|
|
441 |
|
|
@deftypefun Keymap rl_get_keymap ()
|
442 |
|
|
Returns the currently active keymap.
|
443 |
|
|
@end deftypefun
|
444 |
|
|
|
445 |
|
|
@deftypefun void rl_set_keymap (Keymap keymap)
|
446 |
|
|
Makes @var{keymap} the currently active keymap.
|
447 |
|
|
@end deftypefun
|
448 |
|
|
|
449 |
|
|
@deftypefun Keymap rl_get_keymap_by_name (char *name)
|
450 |
|
|
Return the keymap matching @var{name}. @var{name} is one which would
|
451 |
|
|
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
|
452 |
|
|
@end deftypefun
|
453 |
|
|
|
454 |
|
|
@deftypefun {char *} rl_get_keymap_name (Keymap keymap)
|
455 |
|
|
Return the name matching @var{keymap}. @var{name} is one which would
|
456 |
|
|
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
|
457 |
|
|
@end deftypefun
|
458 |
|
|
|
459 |
|
|
@node Binding Keys
|
460 |
|
|
@subsection Binding Keys
|
461 |
|
|
|
462 |
|
|
You associate keys with functions through the keymap. Readline has
|
463 |
|
|
several internal keymaps: @code{emacs_standard_keymap},
|
464 |
|
|
@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
|
465 |
|
|
@code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
|
466 |
|
|
@code{emacs_standard_keymap} is the default, and the examples in
|
467 |
|
|
this manual assume that.
|
468 |
|
|
|
469 |
|
|
Since @code{readline} installs a set of default key bindings the first
|
470 |
|
|
time it is called, there is always the danger that a custom binding
|
471 |
|
|
installed before the first call to @code{readline} will be overridden.
|
472 |
|
|
An alternate mechanism is to install custom key bindings in an
|
473 |
|
|
initialization function assigned to the @code{rl_startup_hook} variable
|
474 |
|
|
(@pxref{Readline Variables}).
|
475 |
|
|
|
476 |
|
|
These functions manage key bindings.
|
477 |
|
|
|
478 |
|
|
@deftypefun int rl_bind_key (int key, Function *function)
|
479 |
|
|
Binds @var{key} to @var{function} in the currently active keymap.
|
480 |
|
|
Returns non-zero in the case of an invalid @var{key}.
|
481 |
|
|
@end deftypefun
|
482 |
|
|
|
483 |
|
|
@deftypefun int rl_bind_key_in_map (int key, Function *function, Keymap map)
|
484 |
|
|
Bind @var{key} to @var{function} in @var{map}. Returns non-zero in the case
|
485 |
|
|
of an invalid @var{key}.
|
486 |
|
|
@end deftypefun
|
487 |
|
|
|
488 |
|
|
@deftypefun int rl_unbind_key (int key)
|
489 |
|
|
Bind @var{key} to the null function in the currently active keymap.
|
490 |
|
|
Returns non-zero in case of error.
|
491 |
|
|
@end deftypefun
|
492 |
|
|
|
493 |
|
|
@deftypefun int rl_unbind_key_in_map (int key, Keymap map)
|
494 |
|
|
Bind @var{key} to the null function in @var{map}.
|
495 |
|
|
Returns non-zero in case of error.
|
496 |
|
|
@end deftypefun
|
497 |
|
|
|
498 |
|
|
@deftypefun int rl_unbind_function_in_map (Function *function, Keymap map)
|
499 |
|
|
Unbind all keys that execute @var{function} in @var{map}.
|
500 |
|
|
@end deftypefun
|
501 |
|
|
|
502 |
|
|
@deftypefun int rl_unbind_command_in_map (char *command, Keymap map)
|
503 |
|
|
Unbind all keys that are bound to @var{command} in @var{map}.
|
504 |
|
|
@end deftypefun
|
505 |
|
|
|
506 |
|
|
@deftypefun int rl_generic_bind (int type, char *keyseq, char *data, Keymap map)
|
507 |
|
|
Bind the key sequence represented by the string @var{keyseq} to the arbitrary
|
508 |
|
|
pointer @var{data}. @var{type} says what kind of data is pointed to by
|
509 |
|
|
@var{data}; this can be a function (@code{ISFUNC}), a macro
|
510 |
|
|
(@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as
|
511 |
|
|
necessary. The initial keymap in which to do bindings is @var{map}.
|
512 |
|
|
@end deftypefun
|
513 |
|
|
|
514 |
|
|
@deftypefun int rl_parse_and_bind (char *line)
|
515 |
|
|
Parse @var{line} as if it had been read from the @code{inputrc} file and
|
516 |
|
|
perform any key bindings and variable assignments found
|
517 |
|
|
(@pxref{Readline Init File}).
|
518 |
|
|
@end deftypefun
|
519 |
|
|
|
520 |
|
|
@deftypefun int rl_read_init_file (char *filename)
|
521 |
|
|
Read keybindings and variable assignments from @var{filename}
|
522 |
|
|
(@pxref{Readline Init File}).
|
523 |
|
|
@end deftypefun
|
524 |
|
|
|
525 |
|
|
@node Associating Function Names and Bindings
|
526 |
|
|
@subsection Associating Function Names and Bindings
|
527 |
|
|
|
528 |
|
|
These functions allow you to find out what keys invoke named functions
|
529 |
|
|
and the functions invoked by a particular key sequence.
|
530 |
|
|
|
531 |
|
|
@deftypefun {Function *} rl_named_function (char *name)
|
532 |
|
|
Return the function with name @var{name}.
|
533 |
|
|
@end deftypefun
|
534 |
|
|
|
535 |
|
|
@deftypefun {Function *} rl_function_of_keyseq (char *keyseq, Keymap map, int *type)
|
536 |
|
|
Return the function invoked by @var{keyseq} in keymap @var{map}.
|
537 |
|
|
If @var{map} is NULL, the current keymap is used. If @var{type} is
|
538 |
|
|
not NULL, the type of the object is returned in it (one of @code{ISFUNC},
|
539 |
|
|
@code{ISKMAP}, or @code{ISMACR}).
|
540 |
|
|
@end deftypefun
|
541 |
|
|
|
542 |
|
|
@deftypefun {char **} rl_invoking_keyseqs (Function *function)
|
543 |
|
|
Return an array of strings representing the key sequences used to
|
544 |
|
|
invoke @var{function} in the current keymap.
|
545 |
|
|
@end deftypefun
|
546 |
|
|
|
547 |
|
|
@deftypefun {char **} rl_invoking_keyseqs_in_map (Function *function, Keymap map)
|
548 |
|
|
Return an array of strings representing the key sequences used to
|
549 |
|
|
invoke @var{function} in the keymap @var{map}.
|
550 |
|
|
@end deftypefun
|
551 |
|
|
|
552 |
|
|
@deftypefun void rl_function_dumper (int readable)
|
553 |
|
|
Print the readline function names and the key sequences currently
|
554 |
|
|
bound to them to @code{rl_outstream}. If @var{readable} is non-zero,
|
555 |
|
|
the list is formatted in such a way that it can be made part of an
|
556 |
|
|
@code{inputrc} file and re-read.
|
557 |
|
|
@end deftypefun
|
558 |
|
|
|
559 |
|
|
@deftypefun void rl_list_funmap_names ()
|
560 |
|
|
Print the names of all bindable Readline functions to @code{rl_outstream}.
|
561 |
|
|
@end deftypefun
|
562 |
|
|
|
563 |
|
|
@deftypefun {char **} rl_funmap_names ()
|
564 |
|
|
Return a NULL terminated array of known function names. The array is
|
565 |
|
|
sorted. The array itself is allocated, but not the strings inside. You
|
566 |
|
|
should free () the array when you done, but not the pointrs.
|
567 |
|
|
@end deftypefun
|
568 |
|
|
|
569 |
|
|
@node Allowing Undoing
|
570 |
|
|
@subsection Allowing Undoing
|
571 |
|
|
|
572 |
|
|
Supporting the undo command is a painless thing, and makes your
|
573 |
|
|
functions much more useful. It is certainly easy to try
|
574 |
|
|
something if you know you can undo it. I could use an undo function for
|
575 |
|
|
the stock market.
|
576 |
|
|
|
577 |
|
|
If your function simply inserts text once, or deletes text once, and
|
578 |
|
|
uses @code{rl_insert_text ()} or @code{rl_delete_text ()} to do it, then
|
579 |
|
|
undoing is already done for you automatically.
|
580 |
|
|
|
581 |
|
|
If you do multiple insertions or multiple deletions, or any combination
|
582 |
|
|
of these operations, you should group them together into one operation.
|
583 |
|
|
This is done with @code{rl_begin_undo_group ()} and
|
584 |
|
|
@code{rl_end_undo_group ()}.
|
585 |
|
|
|
586 |
|
|
The types of events that can be undone are:
|
587 |
|
|
|
588 |
|
|
@example
|
589 |
|
|
enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
|
590 |
|
|
@end example
|
591 |
|
|
|
592 |
|
|
Notice that @code{UNDO_DELETE} means to insert some text, and
|
593 |
|
|
@code{UNDO_INSERT} means to delete some text. That is, the undo code
|
594 |
|
|
tells undo what to undo, not how to undo it. @code{UNDO_BEGIN} and
|
595 |
|
|
@code{UNDO_END} are tags added by @code{rl_begin_undo_group ()} and
|
596 |
|
|
@code{rl_end_undo_group ()}.
|
597 |
|
|
|
598 |
|
|
@deftypefun int rl_begin_undo_group ()
|
599 |
|
|
Begins saving undo information in a group construct. The undo
|
600 |
|
|
information usually comes from calls to @code{rl_insert_text ()} and
|
601 |
|
|
@code{rl_delete_text ()}, but could be the result of calls to
|
602 |
|
|
@code{rl_add_undo ()}.
|
603 |
|
|
@end deftypefun
|
604 |
|
|
|
605 |
|
|
@deftypefun int rl_end_undo_group ()
|
606 |
|
|
Closes the current undo group started with @code{rl_begin_undo_group
|
607 |
|
|
()}. There should be one call to @code{rl_end_undo_group ()}
|
608 |
|
|
for each call to @code{rl_begin_undo_group ()}.
|
609 |
|
|
@end deftypefun
|
610 |
|
|
|
611 |
|
|
@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
|
612 |
|
|
Remember how to undo an event (according to @var{what}). The affected
|
613 |
|
|
text runs from @var{start} to @var{end}, and encompasses @var{text}.
|
614 |
|
|
@end deftypefun
|
615 |
|
|
|
616 |
|
|
@deftypefun void free_undo_list ()
|
617 |
|
|
Free the existing undo list.
|
618 |
|
|
@end deftypefun
|
619 |
|
|
|
620 |
|
|
@deftypefun int rl_do_undo ()
|
621 |
|
|
Undo the first thing on the undo list. Returns @code{0} if there was
|
622 |
|
|
nothing to undo, non-zero if something was undone.
|
623 |
|
|
@end deftypefun
|
624 |
|
|
|
625 |
|
|
Finally, if you neither insert nor delete text, but directly modify the
|
626 |
|
|
existing text (e.g., change its case), call @code{rl_modifying ()}
|
627 |
|
|
once, just before you modify the text. You must supply the indices of
|
628 |
|
|
the text range that you are going to modify.
|
629 |
|
|
|
630 |
|
|
@deftypefun int rl_modifying (int start, int end)
|
631 |
|
|
Tell Readline to save the text between @var{start} and @var{end} as a
|
632 |
|
|
single undo unit. It is assumed that you will subsequently modify
|
633 |
|
|
that text.
|
634 |
|
|
@end deftypefun
|
635 |
|
|
|
636 |
|
|
@node Redisplay
|
637 |
|
|
@subsection Redisplay
|
638 |
|
|
|
639 |
|
|
@deftypefun void rl_redisplay ()
|
640 |
|
|
Change what's displayed on the screen to reflect the current contents
|
641 |
|
|
of @code{rl_line_buffer}.
|
642 |
|
|
@end deftypefun
|
643 |
|
|
|
644 |
|
|
@deftypefun int rl_forced_update_display ()
|
645 |
|
|
Force the line to be updated and redisplayed, whether or not
|
646 |
|
|
Readline thinks the screen display is correct.
|
647 |
|
|
@end deftypefun
|
648 |
|
|
|
649 |
|
|
@deftypefun int rl_on_new_line ()
|
650 |
|
|
Tell the update functions that we have moved onto a new (empty) line,
|
651 |
|
|
usually after ouputting a newline.
|
652 |
|
|
@end deftypefun
|
653 |
|
|
|
654 |
|
|
@deftypefun int rl_on_new_line_with_prompt ()
|
655 |
|
|
Tell the update functions that we have moved onto a new line, with
|
656 |
|
|
@var{rl_prompt} already displayed.
|
657 |
|
|
This could be used by applications that want to output the prompt string
|
658 |
|
|
themselves, but still need Readline to know the prompt string length for
|
659 |
|
|
redisplay.
|
660 |
|
|
It should be used after setting @var{rl_already_prompted}.
|
661 |
|
|
@end deftypefun
|
662 |
|
|
|
663 |
|
|
@deftypefun int rl_reset_line_state ()
|
664 |
|
|
Reset the display state to a clean state and redisplay the current line
|
665 |
|
|
starting on a new line.
|
666 |
|
|
@end deftypefun
|
667 |
|
|
|
668 |
|
|
@deftypefun int rl_message (va_alist)
|
669 |
|
|
The arguments are a string as would be supplied to @code{printf}. The
|
670 |
|
|
resulting string is displayed in the @dfn{echo area}. The echo area
|
671 |
|
|
is also used to display numeric arguments and search strings.
|
672 |
|
|
@end deftypefun
|
673 |
|
|
|
674 |
|
|
@deftypefun int rl_clear_message ()
|
675 |
|
|
Clear the message in the echo area.
|
676 |
|
|
@end deftypefun
|
677 |
|
|
|
678 |
|
|
@deftypefun void rl_save_prompt ()
|
679 |
|
|
Save the local Readline prompt display state in preparation for
|
680 |
|
|
displaying a new message in the message area with @code{rl_message}.
|
681 |
|
|
@end deftypefun
|
682 |
|
|
|
683 |
|
|
@deftypefun void rl_restore_prompt ()
|
684 |
|
|
Restore the local Readline prompt display state saved by the most
|
685 |
|
|
recent call to @code{rl_save_prompt}.
|
686 |
|
|
@end deftypefun
|
687 |
|
|
|
688 |
|
|
@node Modifying Text
|
689 |
|
|
@subsection Modifying Text
|
690 |
|
|
|
691 |
|
|
@deftypefun int rl_insert_text (char *text)
|
692 |
|
|
Insert @var{text} into the line at the current cursor position.
|
693 |
|
|
@end deftypefun
|
694 |
|
|
|
695 |
|
|
@deftypefun int rl_delete_text (int start, int end)
|
696 |
|
|
Delete the text between @var{start} and @var{end} in the current line.
|
697 |
|
|
@end deftypefun
|
698 |
|
|
|
699 |
|
|
@deftypefun {char *} rl_copy_text (int start, int end)
|
700 |
|
|
Return a copy of the text between @var{start} and @var{end} in
|
701 |
|
|
the current line.
|
702 |
|
|
@end deftypefun
|
703 |
|
|
|
704 |
|
|
@deftypefun int rl_kill_text (int start, int end)
|
705 |
|
|
Copy the text between @var{start} and @var{end} in the current line
|
706 |
|
|
to the kill ring, appending or prepending to the last kill if the
|
707 |
|
|
last command was a kill command. The text is deleted.
|
708 |
|
|
If @var{start} is less than @var{end},
|
709 |
|
|
the text is appended, otherwise prepended. If the last command was
|
710 |
|
|
not a kill, a new kill ring slot is used.
|
711 |
|
|
@end deftypefun
|
712 |
|
|
|
713 |
|
|
@node Utility Functions
|
714 |
|
|
@subsection Utility Functions
|
715 |
|
|
|
716 |
|
|
@deftypefun int rl_read_key ()
|
717 |
|
|
Return the next character available. This handles input inserted into
|
718 |
|
|
the input stream via @var{pending input} (@pxref{Readline Variables})
|
719 |
|
|
and @code{rl_stuff_char ()}, macros, and characters read from the keyboard.
|
720 |
|
|
@end deftypefun
|
721 |
|
|
|
722 |
|
|
@deftypefun int rl_getc (FILE *)
|
723 |
|
|
Return the next character available from the keyboard.
|
724 |
|
|
@end deftypefun
|
725 |
|
|
|
726 |
|
|
@deftypefun int rl_stuff_char (int c)
|
727 |
|
|
Insert @var{c} into the Readline input stream. It will be "read"
|
728 |
|
|
before Readline attempts to read characters from the terminal with
|
729 |
|
|
@code{rl_read_key ()}.
|
730 |
|
|
@end deftypefun
|
731 |
|
|
|
732 |
|
|
@deftypefun int rl_extend_line_buffer (int len)
|
733 |
|
|
Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
|
734 |
|
|
characters, possibly reallocating it if necessary.
|
735 |
|
|
@end deftypefun
|
736 |
|
|
|
737 |
|
|
@deftypefun int rl_initialize ()
|
738 |
|
|
Initialize or re-initialize Readline's internal state.
|
739 |
|
|
@end deftypefun
|
740 |
|
|
|
741 |
|
|
@deftypefun int rl_reset_terminal (char *terminal_name)
|
742 |
|
|
Reinitialize Readline's idea of the terminal settings using
|
743 |
|
|
@var{terminal_name} as the terminal type (e.g., @code{vt100}).
|
744 |
|
|
If @var{terminal_name} is NULL, the value of the @code{TERM}
|
745 |
|
|
environment variable is used.
|
746 |
|
|
@end deftypefun
|
747 |
|
|
|
748 |
|
|
@deftypefun int alphabetic (int c)
|
749 |
|
|
Return 1 if @var{c} is an alphabetic character.
|
750 |
|
|
@end deftypefun
|
751 |
|
|
|
752 |
|
|
@deftypefun int numeric (int c)
|
753 |
|
|
Return 1 if @var{c} is a numeric character.
|
754 |
|
|
@end deftypefun
|
755 |
|
|
|
756 |
|
|
@deftypefun int ding ()
|
757 |
|
|
Ring the terminal bell, obeying the setting of @code{bell-style}.
|
758 |
|
|
@end deftypefun
|
759 |
|
|
|
760 |
|
|
@deftypefun void rl_display_match_list (char **matches, int len, int max)
|
761 |
|
|
A convenience function for displaying a list of strings in
|
762 |
|
|
columnar format on Readline's output stream. @code{matches} is the list
|
763 |
|
|
of strings, in argv format, such as a list of completion matches.
|
764 |
|
|
@code{len} is the number of strings in @code{matches}, and @code{max}
|
765 |
|
|
is the length of the longest string in @code{matches}. This function uses
|
766 |
|
|
the setting of @code{print-completions-horizontally} to select how the
|
767 |
|
|
matches are displayed (@pxref{Readline Init File Syntax}).
|
768 |
|
|
@end deftypefun
|
769 |
|
|
|
770 |
|
|
The following are implemented as macros, defined in @code{chartypes.h}.
|
771 |
|
|
|
772 |
|
|
@deftypefun int uppercase_p (int c)
|
773 |
|
|
Return 1 if @var{c} is an uppercase alphabetic character.
|
774 |
|
|
@end deftypefun
|
775 |
|
|
|
776 |
|
|
@deftypefun int lowercase_p (int c)
|
777 |
|
|
Return 1 if @var{c} is a lowercase alphabetic character.
|
778 |
|
|
@end deftypefun
|
779 |
|
|
|
780 |
|
|
@deftypefun int digit_p (int c)
|
781 |
|
|
Return 1 if @var{c} is a numeric character.
|
782 |
|
|
@end deftypefun
|
783 |
|
|
|
784 |
|
|
@deftypefun int to_upper (int c)
|
785 |
|
|
If @var{c} is a lowercase alphabetic character, return the corresponding
|
786 |
|
|
uppercase character.
|
787 |
|
|
@end deftypefun
|
788 |
|
|
|
789 |
|
|
@deftypefun int to_lower (int c)
|
790 |
|
|
If @var{c} is an uppercase alphabetic character, return the corresponding
|
791 |
|
|
lowercase character.
|
792 |
|
|
@end deftypefun
|
793 |
|
|
|
794 |
|
|
@deftypefun int digit_value (int c)
|
795 |
|
|
If @var{c} is a number, return the value it represents.
|
796 |
|
|
@end deftypefun
|
797 |
|
|
|
798 |
|
|
@node Alternate Interface
|
799 |
|
|
@subsection Alternate Interface
|
800 |
|
|
|
801 |
|
|
An alternate interface is available to plain @code{readline()}. Some
|
802 |
|
|
applications need to interleave keyboard I/O with file, device, or
|
803 |
|
|
window system I/O, typically by using a main loop to @code{select()}
|
804 |
|
|
on various file descriptors. To accomodate this need, readline can
|
805 |
|
|
also be invoked as a `callback' function from an event loop. There
|
806 |
|
|
are functions available to make this easy.
|
807 |
|
|
|
808 |
|
|
@deftypefun void rl_callback_handler_install (char *prompt, Vfunction *lhandler)
|
809 |
|
|
Set up the terminal for readline I/O and display the initial
|
810 |
|
|
expanded value of @var{prompt}. Save the value of @var{lhandler} to
|
811 |
|
|
use as a callback when a complete line of input has been entered.
|
812 |
|
|
@end deftypefun
|
813 |
|
|
|
814 |
|
|
@deftypefun void rl_callback_read_char ()
|
815 |
|
|
Whenever an application determines that keyboard input is available, it
|
816 |
|
|
should call @code{rl_callback_read_char()}, which will read the next
|
817 |
|
|
character from the current input source. If that character completes the
|
818 |
|
|
line, @code{rl_callback_read_char} will invoke the @var{lhandler}
|
819 |
|
|
function saved by @code{rl_callback_handler_install} to process the
|
820 |
|
|
line. @code{EOF} is indicated by calling @var{lhandler} with a
|
821 |
|
|
@code{NULL} line.
|
822 |
|
|
@end deftypefun
|
823 |
|
|
|
824 |
|
|
@deftypefun void rl_callback_handler_remove ()
|
825 |
|
|
Restore the terminal to its initial state and remove the line handler.
|
826 |
|
|
This may be called from within a callback as well as independently.
|
827 |
|
|
@end deftypefun
|
828 |
|
|
|
829 |
|
|
@subsection An Example
|
830 |
|
|
|
831 |
|
|
Here is a function which changes lowercase characters to their uppercase
|
832 |
|
|
equivalents, and uppercase characters to lowercase. If
|
833 |
|
|
this function was bound to @samp{M-c}, then typing @samp{M-c} would
|
834 |
|
|
change the case of the character under point. Typing @samp{M-1 0 M-c}
|
835 |
|
|
would change the case of the following 10 characters, leaving the cursor on
|
836 |
|
|
the last character changed.
|
837 |
|
|
|
838 |
|
|
@example
|
839 |
|
|
/* Invert the case of the COUNT following characters. */
|
840 |
|
|
int
|
841 |
|
|
invert_case_line (count, key)
|
842 |
|
|
int count, key;
|
843 |
|
|
@{
|
844 |
|
|
register int start, end, i;
|
845 |
|
|
|
846 |
|
|
start = rl_point;
|
847 |
|
|
|
848 |
|
|
if (rl_point >= rl_end)
|
849 |
|
|
return (0);
|
850 |
|
|
|
851 |
|
|
if (count < 0)
|
852 |
|
|
@{
|
853 |
|
|
direction = -1;
|
854 |
|
|
count = -count;
|
855 |
|
|
@}
|
856 |
|
|
else
|
857 |
|
|
direction = 1;
|
858 |
|
|
|
859 |
|
|
/* Find the end of the range to modify. */
|
860 |
|
|
end = start + (count * direction);
|
861 |
|
|
|
862 |
|
|
/* Force it to be within range. */
|
863 |
|
|
if (end > rl_end)
|
864 |
|
|
end = rl_end;
|
865 |
|
|
else if (end < 0)
|
866 |
|
|
end = 0;
|
867 |
|
|
|
868 |
|
|
if (start == end)
|
869 |
|
|
return (0);
|
870 |
|
|
|
871 |
|
|
if (start > end)
|
872 |
|
|
@{
|
873 |
|
|
int temp = start;
|
874 |
|
|
start = end;
|
875 |
|
|
end = temp;
|
876 |
|
|
@}
|
877 |
|
|
|
878 |
|
|
/* Tell readline that we are modifying the line, so it will save
|
879 |
|
|
the undo information. */
|
880 |
|
|
rl_modifying (start, end);
|
881 |
|
|
|
882 |
|
|
for (i = start; i != end; i++)
|
883 |
|
|
@{
|
884 |
|
|
if (uppercase_p (rl_line_buffer[i]))
|
885 |
|
|
rl_line_buffer[i] = to_lower (rl_line_buffer[i]);
|
886 |
|
|
else if (lowercase_p (rl_line_buffer[i]))
|
887 |
|
|
rl_line_buffer[i] = to_upper (rl_line_buffer[i]);
|
888 |
|
|
@}
|
889 |
|
|
/* Move point to on top of the last character changed. */
|
890 |
|
|
rl_point = (direction == 1) ? end - 1 : start;
|
891 |
|
|
return (0);
|
892 |
|
|
@}
|
893 |
|
|
@end example
|
894 |
|
|
|
895 |
|
|
@node Readline Signal Handling
|
896 |
|
|
@section Readline Signal Handling
|
897 |
|
|
|
898 |
|
|
Signals are asynchronous events sent to a process by the Unix kernel,
|
899 |
|
|
sometimes on behalf of another process. They are intended to indicate
|
900 |
|
|
exceptional events, like a user pressing the interrupt key on his
|
901 |
|
|
terminal, or a network connection being broken. There is a class of
|
902 |
|
|
signals that can be sent to the process currently reading input from
|
903 |
|
|
the keyboard. Since Readline changes the terminal attributes when it
|
904 |
|
|
is called, it needs to perform special processing when a signal is
|
905 |
|
|
received to restore the terminal to a sane state, or provide application
|
906 |
|
|
writers with functions to do so manually.
|
907 |
|
|
|
908 |
|
|
Readline contains an internal signal handler that is installed for a
|
909 |
|
|
number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
|
910 |
|
|
@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
|
911 |
|
|
When one of these signals is received, the signal handler
|
912 |
|
|
will reset the terminal attributes to those that were in effect before
|
913 |
|
|
@code{readline ()} was called, reset the signal handling to what it was
|
914 |
|
|
before @code{readline ()} was called, and resend the signal to the calling
|
915 |
|
|
application.
|
916 |
|
|
If and when the calling application's signal handler returns, Readline
|
917 |
|
|
will reinitialize the terminal and continue to accept input.
|
918 |
|
|
When a @code{SIGINT} is received, the Readline signal handler performs
|
919 |
|
|
some additional work, which will cause any partially-entered line to be
|
920 |
|
|
aborted (see the description of @code{rl_free_line_state ()}).
|
921 |
|
|
|
922 |
|
|
There is an additional Readline signal handler, for @code{SIGWINCH}, which
|
923 |
|
|
the kernel sends to a process whenever the terminal's size changes (for
|
924 |
|
|
example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH}
|
925 |
|
|
handler updates Readline's internal screen size state, and then calls any
|
926 |
|
|
@code{SIGWINCH} signal handler the calling application has installed.
|
927 |
|
|
Readline calls the application's @code{SIGWINCH} signal handler without
|
928 |
|
|
resetting the terminal to its original state. If the application's signal
|
929 |
|
|
handler does more than update its idea of the terminal size and return (for
|
930 |
|
|
example, a @code{longjmp} back to a main processing loop), it @emph{must}
|
931 |
|
|
call @code{rl_cleanup_after_signal ()} (described below), to restore the
|
932 |
|
|
terminal state.
|
933 |
|
|
|
934 |
|
|
Readline provides two variables that allow application writers to
|
935 |
|
|
control whether or not it will catch certain signals and act on them
|
936 |
|
|
when they are received. It is important that applications change the
|
937 |
|
|
values of these variables only when calling @code{readline ()}, not in
|
938 |
|
|
a signal handler, so Readline's internal signal state is not corrupted.
|
939 |
|
|
|
940 |
|
|
@deftypevar int rl_catch_signals
|
941 |
|
|
If this variable is non-zero, Readline will install signal handlers for
|
942 |
|
|
@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGALRM},
|
943 |
|
|
@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
|
944 |
|
|
|
945 |
|
|
The default value of @code{rl_catch_signals} is 1.
|
946 |
|
|
@end deftypevar
|
947 |
|
|
|
948 |
|
|
@deftypevar int rl_catch_sigwinch
|
949 |
|
|
If this variable is non-zero, Readline will install a signal handler for
|
950 |
|
|
@code{SIGWINCH}.
|
951 |
|
|
|
952 |
|
|
The default value of @code{rl_catch_sigwinch} is 1.
|
953 |
|
|
@end deftypevar
|
954 |
|
|
|
955 |
|
|
If an application does not wish to have Readline catch any signals, or
|
956 |
|
|
to handle signals other than those Readline catches (@code{SIGHUP},
|
957 |
|
|
for example),
|
958 |
|
|
Readline provides convenience functions to do the necessary terminal
|
959 |
|
|
and internal state cleanup upon receipt of a signal.
|
960 |
|
|
|
961 |
|
|
@deftypefun void rl_cleanup_after_signal (void)
|
962 |
|
|
This function will reset the state of the terminal to what it was before
|
963 |
|
|
@code{readline ()} was called, and remove the Readline signal handlers for
|
964 |
|
|
all signals, depending on the values of @code{rl_catch_signals} and
|
965 |
|
|
@code{rl_catch_sigwinch}.
|
966 |
|
|
@end deftypefun
|
967 |
|
|
|
968 |
|
|
@deftypefun void rl_free_line_state (void)
|
969 |
|
|
This will free any partial state associated with the current input line
|
970 |
|
|
(undo information, any partial history entry, any partially-entered
|
971 |
|
|
keyboard macro, and any partially-entered numeric argument). This
|
972 |
|
|
should be called before @code{rl_cleanup_after_signal ()}. The
|
973 |
|
|
Readline signal handler for @code{SIGINT} calls this to abort the
|
974 |
|
|
current input line.
|
975 |
|
|
@end deftypefun
|
976 |
|
|
|
977 |
|
|
@deftypefun void rl_reset_after_signal (void)
|
978 |
|
|
This will reinitialize the terminal and reinstall any Readline signal
|
979 |
|
|
handlers, depending on the values of @code{rl_catch_signals} and
|
980 |
|
|
@code{rl_catch_sigwinch}.
|
981 |
|
|
@end deftypefun
|
982 |
|
|
|
983 |
|
|
If an application does not wish Readline to catch @code{SIGWINCH}, it may
|
984 |
|
|
call @code{rl_resize_terminal ()} to force Readline to update its idea of
|
985 |
|
|
the terminal size when a @code{SIGWINCH} is received.
|
986 |
|
|
|
987 |
|
|
@deftypefun void rl_resize_terminal (void)
|
988 |
|
|
Update Readline's internal screen size.
|
989 |
|
|
@end deftypefun
|
990 |
|
|
|
991 |
|
|
The following functions install and remove Readline's signal handlers.
|
992 |
|
|
|
993 |
|
|
@deftypefun int rl_set_signals (void)
|
994 |
|
|
Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
|
995 |
|
|
@code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
|
996 |
|
|
@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
|
997 |
|
|
@code{rl_catch_signals} and @code{rl_catch_sigwinch}.
|
998 |
|
|
@end deftypefun
|
999 |
|
|
|
1000 |
|
|
@deftypefun int rl_clear_signals (void)
|
1001 |
|
|
Remove all of the Readline signal handlers installed by
|
1002 |
|
|
@code{rl_set_signals ()}.
|
1003 |
|
|
@end deftypefun
|
1004 |
|
|
|
1005 |
|
|
@node Custom Completers
|
1006 |
|
|
@section Custom Completers
|
1007 |
|
|
|
1008 |
|
|
Typically, a program that reads commands from the user has a way of
|
1009 |
|
|
disambiguating commands and data. If your program is one of these, then
|
1010 |
|
|
it can provide completion for commands, data, or both.
|
1011 |
|
|
The following sections describe how your program and Readline
|
1012 |
|
|
cooperate to provide this service.
|
1013 |
|
|
|
1014 |
|
|
@menu
|
1015 |
|
|
* How Completing Works:: The logic used to do completion.
|
1016 |
|
|
* Completion Functions:: Functions provided by Readline.
|
1017 |
|
|
* Completion Variables:: Variables which control completion.
|
1018 |
|
|
* A Short Completion Example:: An example of writing completer subroutines.
|
1019 |
|
|
@end menu
|
1020 |
|
|
|
1021 |
|
|
@node How Completing Works
|
1022 |
|
|
@subsection How Completing Works
|
1023 |
|
|
|
1024 |
|
|
In order to complete some text, the full list of possible completions
|
1025 |
|
|
must be available. That is, it is not possible to accurately
|
1026 |
|
|
expand a partial word without knowing all of the possible words
|
1027 |
|
|
which make sense in that context. The Readline library provides
|
1028 |
|
|
the user interface to completion, and two of the most common
|
1029 |
|
|
completion functions: filename and username. For completing other types
|
1030 |
|
|
of text, you must write your own completion function. This section
|
1031 |
|
|
describes exactly what such functions must do, and provides an example.
|
1032 |
|
|
|
1033 |
|
|
There are three major functions used to perform completion:
|
1034 |
|
|
|
1035 |
|
|
@enumerate
|
1036 |
|
|
@item
|
1037 |
|
|
The user-interface function @code{rl_complete ()}. This function is
|
1038 |
|
|
called with the same arguments as other Readline
|
1039 |
|
|
functions intended for interactive use: @var{count} and
|
1040 |
|
|
@var{invoking_key}. It isolates the word to be completed and calls
|
1041 |
|
|
@code{completion_matches ()} to generate a list of possible completions.
|
1042 |
|
|
It then either lists the possible completions, inserts the possible
|
1043 |
|
|
completions, or actually performs the
|
1044 |
|
|
completion, depending on which behavior is desired.
|
1045 |
|
|
|
1046 |
|
|
@item
|
1047 |
|
|
The internal function @code{completion_matches ()} uses your
|
1048 |
|
|
@dfn{generator} function to generate the list of possible matches, and
|
1049 |
|
|
then returns the array of these matches. You should place the address
|
1050 |
|
|
of your generator function in @code{rl_completion_entry_function}.
|
1051 |
|
|
|
1052 |
|
|
@item
|
1053 |
|
|
The generator function is called repeatedly from
|
1054 |
|
|
@code{completion_matches ()}, returning a string each time. The
|
1055 |
|
|
arguments to the generator function are @var{text} and @var{state}.
|
1056 |
|
|
@var{text} is the partial word to be completed. @var{state} is zero the
|
1057 |
|
|
first time the function is called, allowing the generator to perform
|
1058 |
|
|
any necessary initialization, and a positive non-zero integer for
|
1059 |
|
|
each subsequent call. When the generator function returns
|
1060 |
|
|
@code{(char *)NULL} this signals @code{completion_matches ()} that there are
|
1061 |
|
|
no more possibilities left. Usually the generator function computes the
|
1062 |
|
|
list of possible completions when @var{state} is zero, and returns them
|
1063 |
|
|
one at a time on subsequent calls. Each string the generator function
|
1064 |
|
|
returns as a match must be allocated with @code{malloc()}; Readline
|
1065 |
|
|
frees the strings when it has finished with them.
|
1066 |
|
|
|
1067 |
|
|
@end enumerate
|
1068 |
|
|
|
1069 |
|
|
@deftypefun int rl_complete (int ignore, int invoking_key)
|
1070 |
|
|
Complete the word at or before point. You have supplied the function
|
1071 |
|
|
that does the initial simple matching selection algorithm (see
|
1072 |
|
|
@code{completion_matches ()}). The default is to do filename completion.
|
1073 |
|
|
@end deftypefun
|
1074 |
|
|
|
1075 |
|
|
@deftypevar {Function *} rl_completion_entry_function
|
1076 |
|
|
This is a pointer to the generator function for @code{completion_matches
|
1077 |
|
|
()}. If the value of @code{rl_completion_entry_function} is
|
1078 |
|
|
@code{(Function *)NULL} then the default filename generator function,
|
1079 |
|
|
@code{filename_completion_function ()}, is used.
|
1080 |
|
|
@end deftypevar
|
1081 |
|
|
|
1082 |
|
|
@node Completion Functions
|
1083 |
|
|
@subsection Completion Functions
|
1084 |
|
|
|
1085 |
|
|
Here is the complete list of callable completion functions present in
|
1086 |
|
|
Readline.
|
1087 |
|
|
|
1088 |
|
|
@deftypefun int rl_complete_internal (int what_to_do)
|
1089 |
|
|
Complete the word at or before point. @var{what_to_do} says what to do
|
1090 |
|
|
with the completion. A value of @samp{?} means list the possible
|
1091 |
|
|
completions. @samp{TAB} means do standard completion. @samp{*} means
|
1092 |
|
|
insert all of the possible completions. @samp{!} means to display
|
1093 |
|
|
all of the possible completions, if there is more than one, as well as
|
1094 |
|
|
performing partial completion.
|
1095 |
|
|
@end deftypefun
|
1096 |
|
|
|
1097 |
|
|
@deftypefun int rl_complete (int ignore, int invoking_key)
|
1098 |
|
|
Complete the word at or before point. You have supplied the function
|
1099 |
|
|
that does the initial simple matching selection algorithm (see
|
1100 |
|
|
@code{completion_matches ()} and @code{rl_completion_entry_function}).
|
1101 |
|
|
The default is to do filename
|
1102 |
|
|
completion. This calls @code{rl_complete_internal ()} with an
|
1103 |
|
|
argument depending on @var{invoking_key}.
|
1104 |
|
|
@end deftypefun
|
1105 |
|
|
|
1106 |
|
|
@deftypefun int rl_possible_completions (int count, int invoking_key))
|
1107 |
|
|
List the possible completions. See description of @code{rl_complete
|
1108 |
|
|
()}. This calls @code{rl_complete_internal ()} with an argument of
|
1109 |
|
|
@samp{?}.
|
1110 |
|
|
@end deftypefun
|
1111 |
|
|
|
1112 |
|
|
@deftypefun int rl_insert_completions (int count, int invoking_key))
|
1113 |
|
|
Insert the list of possible completions into the line, deleting the
|
1114 |
|
|
partially-completed word. See description of @code{rl_complete ()}.
|
1115 |
|
|
This calls @code{rl_complete_internal ()} with an argument of @samp{*}.
|
1116 |
|
|
@end deftypefun
|
1117 |
|
|
|
1118 |
|
|
@deftypefun {char **} completion_matches (char *text, CPFunction *entry_func)
|
1119 |
|
|
Returns an array of @code{(char *)} which is a list of completions for
|
1120 |
|
|
@var{text}. If there are no completions, returns @code{(char **)NULL}.
|
1121 |
|
|
The first entry in the returned array is the substitution for @var{text}.
|
1122 |
|
|
The remaining entries are the possible completions. The array is
|
1123 |
|
|
terminated with a @code{NULL} pointer.
|
1124 |
|
|
|
1125 |
|
|
@var{entry_func} is a function of two args, and returns a
|
1126 |
|
|
@code{(char *)}. The first argument is @var{text}. The second is a
|
1127 |
|
|
state argument; it is zero on the first call, and non-zero on subsequent
|
1128 |
|
|
calls. @var{entry_func} returns a @code{NULL} pointer to the caller
|
1129 |
|
|
when there are no more matches.
|
1130 |
|
|
@end deftypefun
|
1131 |
|
|
|
1132 |
|
|
@deftypefun {char *} filename_completion_function (char *text, int state)
|
1133 |
|
|
A generator function for filename completion in the general case. Note
|
1134 |
|
|
that completion in Bash is a little different because of all
|
1135 |
|
|
the pathnames that must be followed when looking up completions for a
|
1136 |
|
|
command. The Bash source is a useful reference for writing custom
|
1137 |
|
|
completion functions.
|
1138 |
|
|
@end deftypefun
|
1139 |
|
|
|
1140 |
|
|
@deftypefun {char *} username_completion_function (char *text, int state)
|
1141 |
|
|
A completion generator for usernames. @var{text} contains a partial
|
1142 |
|
|
username preceded by a random character (usually @samp{~}). As with all
|
1143 |
|
|
completion generators, @var{state} is zero on the first call and non-zero
|
1144 |
|
|
for subsequent calls.
|
1145 |
|
|
@end deftypefun
|
1146 |
|
|
|
1147 |
|
|
@node Completion Variables
|
1148 |
|
|
@subsection Completion Variables
|
1149 |
|
|
|
1150 |
|
|
@deftypevar {Function *} rl_completion_entry_function
|
1151 |
|
|
A pointer to the generator function for @code{completion_matches ()}.
|
1152 |
|
|
@code{NULL} means to use @code{filename_completion_function ()}, the default
|
1153 |
|
|
filename completer.
|
1154 |
|
|
@end deftypevar
|
1155 |
|
|
|
1156 |
|
|
@deftypevar {CPPFunction *} rl_attempted_completion_function
|
1157 |
|
|
A pointer to an alternative function to create matches.
|
1158 |
|
|
The function is called with @var{text}, @var{start}, and @var{end}.
|
1159 |
|
|
@var{start} and @var{end} are indices in @code{rl_line_buffer} saying
|
1160 |
|
|
what the boundaries of @var{text} are. If this function exists and
|
1161 |
|
|
returns @code{NULL}, or if this variable is set to @code{NULL}, then
|
1162 |
|
|
@code{rl_complete ()} will call the value of
|
1163 |
|
|
@code{rl_completion_entry_function} to generate matches, otherwise the
|
1164 |
|
|
array of strings returned will be used.
|
1165 |
|
|
@end deftypevar
|
1166 |
|
|
|
1167 |
|
|
@deftypevar {CPFunction *} rl_filename_quoting_function
|
1168 |
|
|
A pointer to a function that will quote a filename in an application-
|
1169 |
|
|
specific fashion. This is called if filename completion is being
|
1170 |
|
|
attempted and one of the characters in @code{rl_filename_quote_characters}
|
1171 |
|
|
appears in a completed filename. The function is called with
|
1172 |
|
|
@var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text}
|
1173 |
|
|
is the filename to be quoted. The @var{match_type} is either
|
1174 |
|
|
@code{SINGLE_MATCH}, if there is only one completion match, or
|
1175 |
|
|
@code{MULT_MATCH}. Some functions use this to decide whether or not to
|
1176 |
|
|
insert a closing quote character. The @var{quote_pointer} is a pointer
|
1177 |
|
|
to any opening quote character the user typed. Some functions choose
|
1178 |
|
|
to reset this character.
|
1179 |
|
|
@end deftypevar
|
1180 |
|
|
|
1181 |
|
|
@deftypevar {CPFunction *} rl_filename_dequoting_function
|
1182 |
|
|
A pointer to a function that will remove application-specific quoting
|
1183 |
|
|
characters from a filename before completion is attempted, so those
|
1184 |
|
|
characters do not interfere with matching the text against names in
|
1185 |
|
|
the filesystem. It is called with @var{text}, the text of the word
|
1186 |
|
|
to be dequoted, and @var{quote_char}, which is the quoting character
|
1187 |
|
|
that delimits the filename (usually @samp{'} or @samp{"}). If
|
1188 |
|
|
@var{quote_char} is zero, the filename was not in an embedded string.
|
1189 |
|
|
@end deftypevar
|
1190 |
|
|
|
1191 |
|
|
@deftypevar {Function *} rl_char_is_quoted_p
|
1192 |
|
|
A pointer to a function to call that determines whether or not a specific
|
1193 |
|
|
character in the line buffer is quoted, according to whatever quoting
|
1194 |
|
|
mechanism the program calling readline uses. The function is called with
|
1195 |
|
|
two arguments: @var{text}, the text of the line, and @var{index}, the
|
1196 |
|
|
index of the character in the line. It is used to decide whether a
|
1197 |
|
|
character found in @code{rl_completer_word_break_characters} should be
|
1198 |
|
|
used to break words for the completer.
|
1199 |
|
|
@end deftypevar
|
1200 |
|
|
|
1201 |
|
|
@deftypevar int rl_completion_query_items
|
1202 |
|
|
Up to this many items will be displayed in response to a
|
1203 |
|
|
possible-completions call. After that, we ask the user if she is sure
|
1204 |
|
|
she wants to see them all. The default value is 100.
|
1205 |
|
|
@end deftypevar
|
1206 |
|
|
|
1207 |
|
|
@deftypevar {char *} rl_basic_word_break_characters
|
1208 |
|
|
The basic list of characters that signal a break between words for the
|
1209 |
|
|
completer routine. The default value of this variable is the characters
|
1210 |
|
|
which break words for completion in Bash, i.e.,
|
1211 |
|
|
@code{" \t\n\"\\'`@@$><=;|&@{("}.
|
1212 |
|
|
@end deftypevar
|
1213 |
|
|
|
1214 |
|
|
@deftypevar {char *} rl_basic_quote_characters
|
1215 |
|
|
List of quote characters which can cause a word break.
|
1216 |
|
|
@end deftypevar
|
1217 |
|
|
|
1218 |
|
|
@deftypevar {char *} rl_completer_word_break_characters
|
1219 |
|
|
The list of characters that signal a break between words for
|
1220 |
|
|
@code{rl_complete_internal ()}. The default list is the value of
|
1221 |
|
|
@code{rl_basic_word_break_characters}.
|
1222 |
|
|
@end deftypevar
|
1223 |
|
|
|
1224 |
|
|
@deftypevar {char *} rl_completer_quote_characters
|
1225 |
|
|
List of characters which can be used to quote a substring of the line.
|
1226 |
|
|
Completion occurs on the entire substring, and within the substring
|
1227 |
|
|
@code{rl_completer_word_break_characters} are treated as any other character,
|
1228 |
|
|
unless they also appear within this list.
|
1229 |
|
|
@end deftypevar
|
1230 |
|
|
|
1231 |
|
|
@deftypevar {char *} rl_filename_quote_characters
|
1232 |
|
|
A list of characters that cause a filename to be quoted by the completer
|
1233 |
|
|
when they appear in a completed filename. The default is the null string.
|
1234 |
|
|
@end deftypevar
|
1235 |
|
|
|
1236 |
|
|
@deftypevar {char *} rl_special_prefixes
|
1237 |
|
|
The list of characters that are word break characters, but should be
|
1238 |
|
|
left in @var{text} when it is passed to the completion function.
|
1239 |
|
|
Programs can use this to help determine what kind of completing to do.
|
1240 |
|
|
For instance, Bash sets this variable to "$@@" so that it can complete
|
1241 |
|
|
shell variables and hostnames.
|
1242 |
|
|
@end deftypevar
|
1243 |
|
|
|
1244 |
|
|
@deftypevar {int} rl_completion_append_character
|
1245 |
|
|
When a single completion alternative matches at the end of the command
|
1246 |
|
|
line, this character is appended to the inserted completion text. The
|
1247 |
|
|
default is a space character (@samp{ }). Setting this to the null
|
1248 |
|
|
character (@samp{\0}) prevents anything being appended automatically.
|
1249 |
|
|
This can be changed in custom completion functions to
|
1250 |
|
|
provide the ``most sensible word separator character'' according to
|
1251 |
|
|
an application-specific command line syntax specification.
|
1252 |
|
|
@end deftypevar
|
1253 |
|
|
|
1254 |
|
|
@deftypevar int rl_ignore_completion_duplicates
|
1255 |
|
|
If non-zero, then disallow duplicates in the matches. Default is 1.
|
1256 |
|
|
@end deftypevar
|
1257 |
|
|
|
1258 |
|
|
@deftypevar int rl_filename_completion_desired
|
1259 |
|
|
Non-zero means that the results of the matches are to be treated as
|
1260 |
|
|
filenames. This is @emph{always} zero on entry, and can only be changed
|
1261 |
|
|
within a completion entry generator function. If it is set to a non-zero
|
1262 |
|
|
value, directory names have a slash appended and Readline attempts to
|
1263 |
|
|
quote completed filenames if they contain any embedded word break
|
1264 |
|
|
characters.
|
1265 |
|
|
@end deftypevar
|
1266 |
|
|
|
1267 |
|
|
@deftypevar int rl_filename_quoting_desired
|
1268 |
|
|
Non-zero means that the results of the matches are to be quoted using
|
1269 |
|
|
double quotes (or an application-specific quoting mechanism) if the
|
1270 |
|
|
completed filename contains any characters in
|
1271 |
|
|
@code{rl_filename_quote_chars}. This is @emph{always} non-zero
|
1272 |
|
|
on entry, and can only be changed within a completion entry generator
|
1273 |
|
|
function. The quoting is effected via a call to the function pointed to
|
1274 |
|
|
by @code{rl_filename_quoting_function}.
|
1275 |
|
|
@end deftypevar
|
1276 |
|
|
|
1277 |
|
|
@deftypevar int rl_inhibit_completion
|
1278 |
|
|
If this variable is non-zero, completion is inhibit<ed. The completion
|
1279 |
|
|
character will be inserted as any other bound to @code{self-insert}.
|
1280 |
|
|
@end deftypevar
|
1281 |
|
|
|
1282 |
|
|
@deftypevar {Function *} rl_ignore_some_completions_function
|
1283 |
|
|
This function, if defined, is called by the completer when real filename
|
1284 |
|
|
completion is done, after all the matching names have been generated.
|
1285 |
|
|
It is passed a @code{NULL} terminated array of matches.
|
1286 |
|
|
The first element (@code{matches[0]}) is the
|
1287 |
|
|
maximal substring common to all matches. This function can
|
1288 |
|
|
re-arrange the list of matches as required, but each element deleted
|
1289 |
|
|
from the array must be freed.
|
1290 |
|
|
@end deftypevar
|
1291 |
|
|
|
1292 |
|
|
@deftypevar {Function *} rl_directory_completion_hook
|
1293 |
|
|
This function, if defined, is allowed to modify the directory portion
|
1294 |
|
|
of filenames Readline completes. It is called with the address of a
|
1295 |
|
|
string (the current directory name) as an argument. It could be used
|
1296 |
|
|
to expand symbolic links or shell variables in pathnames.
|
1297 |
|
|
@end deftypevar
|
1298 |
|
|
|
1299 |
|
|
@deftypevar {VFunction *} rl_completion_display_matches_hook
|
1300 |
|
|
If non-zero, then this is the address of a function to call when
|
1301 |
|
|
completing a word would normally display the list of possible matches.
|
1302 |
|
|
This function is called in lieu of Readline displaying the list.
|
1303 |
|
|
It takes three arguments:
|
1304 |
|
|
(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
|
1305 |
|
|
where @var{matches} is the array of matching strings,
|
1306 |
|
|
@var{num_matches} is the number of strings in that array, and
|
1307 |
|
|
@var{max_length} is the length of the longest string in that array.
|
1308 |
|
|
Readline provides a convenience function, @code{rl_display_match_list},
|
1309 |
|
|
that takes care of doing the display to Readline's output stream. That
|
1310 |
|
|
function may be called from this hook.
|
1311 |
|
|
@end deftypevar
|
1312 |
|
|
|
1313 |
|
|
@node A Short Completion Example
|
1314 |
|
|
@subsection A Short Completion Example
|
1315 |
|
|
|
1316 |
|
|
Here is a small application demonstrating the use of the GNU Readline
|
1317 |
|
|
library. It is called @code{fileman}, and the source code resides in
|
1318 |
|
|
@file{examples/fileman.c}. This sample application provides
|
1319 |
|
|
completion of command names, line editing features, and access to the
|
1320 |
|
|
history list.
|
1321 |
|
|
|
1322 |
|
|
@page
|
1323 |
|
|
@smallexample
|
1324 |
|
|
/* fileman.c -- A tiny application which demonstrates how to use the
|
1325 |
|
|
GNU Readline library. This application interactively allows users
|
1326 |
|
|
to manipulate files and their modes. */
|
1327 |
|
|
|
1328 |
|
|
#include <stdio.h>
|
1329 |
|
|
#include <sys/types.h>
|
1330 |
|
|
#include <sys/file.h>
|
1331 |
|
|
#include <sys/stat.h>
|
1332 |
|
|
#include <sys/errno.h>
|
1333 |
|
|
|
1334 |
|
|
#include <readline/readline.h>
|
1335 |
|
|
#include <readline/history.h>
|
1336 |
|
|
|
1337 |
|
|
extern char *getwd ();
|
1338 |
|
|
extern char *xmalloc ();
|
1339 |
|
|
|
1340 |
|
|
/* The names of functions that actually do the manipulation. */
|
1341 |
|
|
int com_list (), com_view (), com_rename (), com_stat (), com_pwd ();
|
1342 |
|
|
int com_delete (), com_help (), com_cd (), com_quit ();
|
1343 |
|
|
|
1344 |
|
|
/* A structure which contains information on the commands this program
|
1345 |
|
|
can understand. */
|
1346 |
|
|
|
1347 |
|
|
typedef struct @{
|
1348 |
|
|
char *name; /* User printable name of the function. */
|
1349 |
|
|
Function *func; /* Function to call to do the job. */
|
1350 |
|
|
char *doc; /* Documentation for this function. */
|
1351 |
|
|
@} COMMAND;
|
1352 |
|
|
|
1353 |
|
|
COMMAND commands[] = @{
|
1354 |
|
|
@{ "cd", com_cd, "Change to directory DIR" @},
|
1355 |
|
|
@{ "delete", com_delete, "Delete FILE" @},
|
1356 |
|
|
@{ "help", com_help, "Display this text" @},
|
1357 |
|
|
@{ "?", com_help, "Synonym for `help'" @},
|
1358 |
|
|
@{ "list", com_list, "List files in DIR" @},
|
1359 |
|
|
@{ "ls", com_list, "Synonym for `list'" @},
|
1360 |
|
|
@{ "pwd", com_pwd, "Print the current working directory" @},
|
1361 |
|
|
@{ "quit", com_quit, "Quit using Fileman" @},
|
1362 |
|
|
@{ "rename", com_rename, "Rename FILE to NEWNAME" @},
|
1363 |
|
|
@{ "stat", com_stat, "Print out statistics on FILE" @},
|
1364 |
|
|
@{ "view", com_view, "View the contents of FILE" @},
|
1365 |
|
|
@{ (char *)NULL, (Function *)NULL, (char *)NULL @}
|
1366 |
|
|
@};
|
1367 |
|
|
|
1368 |
|
|
/* Forward declarations. */
|
1369 |
|
|
char *stripwhite ();
|
1370 |
|
|
COMMAND *find_command ();
|
1371 |
|
|
|
1372 |
|
|
/* The name of this program, as taken from argv[0]. */
|
1373 |
|
|
char *progname;
|
1374 |
|
|
|
1375 |
|
|
/* When non-zero, this global means the user is done using this program. */
|
1376 |
|
|
int done;
|
1377 |
|
|
|
1378 |
|
|
char *
|
1379 |
|
|
dupstr (s)
|
1380 |
|
|
int s;
|
1381 |
|
|
@{
|
1382 |
|
|
char *r;
|
1383 |
|
|
|
1384 |
|
|
r = xmalloc (strlen (s) + 1);
|
1385 |
|
|
strcpy (r, s);
|
1386 |
|
|
return (r);
|
1387 |
|
|
@}
|
1388 |
|
|
|
1389 |
|
|
main (argc, argv)
|
1390 |
|
|
int argc;
|
1391 |
|
|
char **argv;
|
1392 |
|
|
@{
|
1393 |
|
|
char *line, *s;
|
1394 |
|
|
|
1395 |
|
|
progname = argv[0];
|
1396 |
|
|
|
1397 |
|
|
initialize_readline (); /* Bind our completer. */
|
1398 |
|
|
|
1399 |
|
|
/* Loop reading and executing lines until the user quits. */
|
1400 |
|
|
for ( ; done == 0; )
|
1401 |
|
|
@{
|
1402 |
|
|
line = readline ("FileMan: ");
|
1403 |
|
|
|
1404 |
|
|
if (!line)
|
1405 |
|
|
break;
|
1406 |
|
|
|
1407 |
|
|
/* Remove leading and trailing whitespace from the line.
|
1408 |
|
|
Then, if there is anything left, add it to the history list
|
1409 |
|
|
and execute it. */
|
1410 |
|
|
s = stripwhite (line);
|
1411 |
|
|
|
1412 |
|
|
if (*s)
|
1413 |
|
|
@{
|
1414 |
|
|
add_history (s);
|
1415 |
|
|
execute_line (s);
|
1416 |
|
|
@}
|
1417 |
|
|
|
1418 |
|
|
free (line);
|
1419 |
|
|
@}
|
1420 |
|
|
exit (0);
|
1421 |
|
|
@}
|
1422 |
|
|
|
1423 |
|
|
/* Execute a command line. */
|
1424 |
|
|
int
|
1425 |
|
|
execute_line (line)
|
1426 |
|
|
char *line;
|
1427 |
|
|
@{
|
1428 |
|
|
register int i;
|
1429 |
|
|
COMMAND *command;
|
1430 |
|
|
char *word;
|
1431 |
|
|
|
1432 |
|
|
/* Isolate the command word. */
|
1433 |
|
|
i = 0;
|
1434 |
|
|
while (line[i] && whitespace (line[i]))
|
1435 |
|
|
i++;
|
1436 |
|
|
word = line + i;
|
1437 |
|
|
|
1438 |
|
|
while (line[i] && !whitespace (line[i]))
|
1439 |
|
|
i++;
|
1440 |
|
|
|
1441 |
|
|
if (line[i])
|
1442 |
|
|
line[i++] = '\0';
|
1443 |
|
|
|
1444 |
|
|
command = find_command (word);
|
1445 |
|
|
|
1446 |
|
|
if (!command)
|
1447 |
|
|
@{
|
1448 |
|
|
fprintf (stderr, "%s: No such command for FileMan.\n", word);
|
1449 |
|
|
return (-1);
|
1450 |
|
|
@}
|
1451 |
|
|
|
1452 |
|
|
/* Get argument to command, if any. */
|
1453 |
|
|
while (whitespace (line[i]))
|
1454 |
|
|
i++;
|
1455 |
|
|
|
1456 |
|
|
word = line + i;
|
1457 |
|
|
|
1458 |
|
|
/* Call the function. */
|
1459 |
|
|
return ((*(command->func)) (word));
|
1460 |
|
|
@}
|
1461 |
|
|
|
1462 |
|
|
/* Look up NAME as the name of a command, and return a pointer to that
|
1463 |
|
|
command. Return a NULL pointer if NAME isn't a command name. */
|
1464 |
|
|
COMMAND *
|
1465 |
|
|
find_command (name)
|
1466 |
|
|
char *name;
|
1467 |
|
|
@{
|
1468 |
|
|
register int i;
|
1469 |
|
|
|
1470 |
|
|
for (i = 0; commands[i].name; i++)
|
1471 |
|
|
if (strcmp (name, commands[i].name) == 0)
|
1472 |
|
|
return (&commands[i]);
|
1473 |
|
|
|
1474 |
|
|
return ((COMMAND *)NULL);
|
1475 |
|
|
@}
|
1476 |
|
|
|
1477 |
|
|
/* Strip whitespace from the start and end of STRING. Return a pointer
|
1478 |
|
|
into STRING. */
|
1479 |
|
|
char *
|
1480 |
|
|
stripwhite (string)
|
1481 |
|
|
char *string;
|
1482 |
|
|
@{
|
1483 |
|
|
register char *s, *t;
|
1484 |
|
|
|
1485 |
|
|
for (s = string; whitespace (*s); s++)
|
1486 |
|
|
;
|
1487 |
|
|
|
1488 |
|
|
if (*s == 0)
|
1489 |
|
|
return (s);
|
1490 |
|
|
|
1491 |
|
|
t = s + strlen (s) - 1;
|
1492 |
|
|
while (t > s && whitespace (*t))
|
1493 |
|
|
t--;
|
1494 |
|
|
*++t = '\0';
|
1495 |
|
|
|
1496 |
|
|
return s;
|
1497 |
|
|
@}
|
1498 |
|
|
|
1499 |
|
|
/* **************************************************************** */
|
1500 |
|
|
/* */
|
1501 |
|
|
/* Interface to Readline Completion */
|
1502 |
|
|
/* */
|
1503 |
|
|
/* **************************************************************** */
|
1504 |
|
|
|
1505 |
|
|
char *command_generator ();
|
1506 |
|
|
char **fileman_completion ();
|
1507 |
|
|
|
1508 |
|
|
/* Tell the GNU Readline library how to complete. We want to try to complete
|
1509 |
|
|
on command names if this is the first word in the line, or on filenames
|
1510 |
|
|
if not. */
|
1511 |
|
|
initialize_readline ()
|
1512 |
|
|
@{
|
1513 |
|
|
/* Allow conditional parsing of the ~/.inputrc file. */
|
1514 |
|
|
rl_readline_name = "FileMan";
|
1515 |
|
|
|
1516 |
|
|
/* Tell the completer that we want a crack first. */
|
1517 |
|
|
rl_attempted_completion_function = (CPPFunction *)fileman_completion;
|
1518 |
|
|
@}
|
1519 |
|
|
|
1520 |
|
|
/* Attempt to complete on the contents of TEXT. START and END bound the
|
1521 |
|
|
region of rl_line_buffer that contains the word to complete. TEXT is
|
1522 |
|
|
the word to complete. We can use the entire contents of rl_line_buffer
|
1523 |
|
|
in case we want to do some simple parsing. Return the array of matches,
|
1524 |
|
|
or NULL if there aren't any. */
|
1525 |
|
|
char **
|
1526 |
|
|
fileman_completion (text, start, end)
|
1527 |
|
|
char *text;
|
1528 |
|
|
int start, end;
|
1529 |
|
|
@{
|
1530 |
|
|
char **matches;
|
1531 |
|
|
|
1532 |
|
|
matches = (char **)NULL;
|
1533 |
|
|
|
1534 |
|
|
/* If this word is at the start of the line, then it is a command
|
1535 |
|
|
to complete. Otherwise it is the name of a file in the current
|
1536 |
|
|
directory. */
|
1537 |
|
|
if (start == 0)
|
1538 |
|
|
matches = completion_matches (text, command_generator);
|
1539 |
|
|
|
1540 |
|
|
return (matches);
|
1541 |
|
|
@}
|
1542 |
|
|
|
1543 |
|
|
/* Generator function for command completion. STATE lets us know whether
|
1544 |
|
|
to start from scratch; without any state (i.e. STATE == 0), then we
|
1545 |
|
|
start at the top of the list. */
|
1546 |
|
|
char *
|
1547 |
|
|
command_generator (text, state)
|
1548 |
|
|
char *text;
|
1549 |
|
|
int state;
|
1550 |
|
|
@{
|
1551 |
|
|
static int list_index, len;
|
1552 |
|
|
char *name;
|
1553 |
|
|
|
1554 |
|
|
/* If this is a new word to complete, initialize now. This includes
|
1555 |
|
|
saving the length of TEXT for efficiency, and initializing the index
|
1556 |
|
|
variable to 0. */
|
1557 |
|
|
if (!state)
|
1558 |
|
|
@{
|
1559 |
|
|
list_index = 0;
|
1560 |
|
|
len = strlen (text);
|
1561 |
|
|
@}
|
1562 |
|
|
|
1563 |
|
|
/* Return the next name which partially matches from the command list. */
|
1564 |
|
|
while (name = commands[list_index].name)
|
1565 |
|
|
@{
|
1566 |
|
|
list_index++;
|
1567 |
|
|
|
1568 |
|
|
if (strncmp (name, text, len) == 0)
|
1569 |
|
|
return (dupstr(name));
|
1570 |
|
|
@}
|
1571 |
|
|
|
1572 |
|
|
/* If no names matched, then return NULL. */
|
1573 |
|
|
return ((char *)NULL);
|
1574 |
|
|
@}
|
1575 |
|
|
|
1576 |
|
|
/* **************************************************************** */
|
1577 |
|
|
/* */
|
1578 |
|
|
/* FileMan Commands */
|
1579 |
|
|
/* */
|
1580 |
|
|
/* **************************************************************** */
|
1581 |
|
|
|
1582 |
|
|
/* String to pass to system (). This is for the LIST, VIEW and RENAME
|
1583 |
|
|
commands. */
|
1584 |
|
|
static char syscom[1024];
|
1585 |
|
|
|
1586 |
|
|
/* List the file(s) named in arg. */
|
1587 |
|
|
com_list (arg)
|
1588 |
|
|
char *arg;
|
1589 |
|
|
@{
|
1590 |
|
|
if (!arg)
|
1591 |
|
|
arg = "";
|
1592 |
|
|
|
1593 |
|
|
sprintf (syscom, "ls -FClg %s", arg);
|
1594 |
|
|
return (system (syscom));
|
1595 |
|
|
@}
|
1596 |
|
|
|
1597 |
|
|
com_view (arg)
|
1598 |
|
|
char *arg;
|
1599 |
|
|
@{
|
1600 |
|
|
if (!valid_argument ("view", arg))
|
1601 |
|
|
return 1;
|
1602 |
|
|
|
1603 |
|
|
sprintf (syscom, "more %s", arg);
|
1604 |
|
|
return (system (syscom));
|
1605 |
|
|
@}
|
1606 |
|
|
|
1607 |
|
|
com_rename (arg)
|
1608 |
|
|
char *arg;
|
1609 |
|
|
@{
|
1610 |
|
|
too_dangerous ("rename");
|
1611 |
|
|
return (1);
|
1612 |
|
|
@}
|
1613 |
|
|
|
1614 |
|
|
com_stat (arg)
|
1615 |
|
|
char *arg;
|
1616 |
|
|
@{
|
1617 |
|
|
struct stat finfo;
|
1618 |
|
|
|
1619 |
|
|
if (!valid_argument ("stat", arg))
|
1620 |
|
|
return (1);
|
1621 |
|
|
|
1622 |
|
|
if (stat (arg, &finfo) == -1)
|
1623 |
|
|
@{
|
1624 |
|
|
perror (arg);
|
1625 |
|
|
return (1);
|
1626 |
|
|
@}
|
1627 |
|
|
|
1628 |
|
|
printf ("Statistics for `%s':\n", arg);
|
1629 |
|
|
|
1630 |
|
|
printf ("%s has %d link%s, and is %d byte%s in length.\n", arg,
|
1631 |
|
|
finfo.st_nlink,
|
1632 |
|
|
(finfo.st_nlink == 1) ? "" : "s",
|
1633 |
|
|
finfo.st_size,
|
1634 |
|
|
(finfo.st_size == 1) ? "" : "s");
|
1635 |
|
|
printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
|
1636 |
|
|
printf (" Last access at: %s", ctime (&finfo.st_atime));
|
1637 |
|
|
printf (" Last modified at: %s", ctime (&finfo.st_mtime));
|
1638 |
|
|
return (0);
|
1639 |
|
|
@}
|
1640 |
|
|
|
1641 |
|
|
com_delete (arg)
|
1642 |
|
|
char *arg;
|
1643 |
|
|
@{
|
1644 |
|
|
too_dangerous ("delete");
|
1645 |
|
|
return (1);
|
1646 |
|
|
@}
|
1647 |
|
|
|
1648 |
|
|
/* Print out help for ARG, or for all of the commands if ARG is
|
1649 |
|
|
not present. */
|
1650 |
|
|
com_help (arg)
|
1651 |
|
|
char *arg;
|
1652 |
|
|
@{
|
1653 |
|
|
register int i;
|
1654 |
|
|
int printed = 0;
|
1655 |
|
|
|
1656 |
|
|
for (i = 0; commands[i].name; i++)
|
1657 |
|
|
@{
|
1658 |
|
|
if (!*arg || (strcmp (arg, commands[i].name) == 0))
|
1659 |
|
|
@{
|
1660 |
|
|
printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
|
1661 |
|
|
printed++;
|
1662 |
|
|
@}
|
1663 |
|
|
@}
|
1664 |
|
|
|
1665 |
|
|
if (!printed)
|
1666 |
|
|
@{
|
1667 |
|
|
printf ("No commands match `%s'. Possibilties are:\n", arg);
|
1668 |
|
|
|
1669 |
|
|
for (i = 0; commands[i].name; i++)
|
1670 |
|
|
@{
|
1671 |
|
|
/* Print in six columns. */
|
1672 |
|
|
if (printed == 6)
|
1673 |
|
|
@{
|
1674 |
|
|
printed = 0;
|
1675 |
|
|
printf ("\n");
|
1676 |
|
|
@}
|
1677 |
|
|
|
1678 |
|
|
printf ("%s\t", commands[i].name);
|
1679 |
|
|
printed++;
|
1680 |
|
|
@}
|
1681 |
|
|
|
1682 |
|
|
if (printed)
|
1683 |
|
|
printf ("\n");
|
1684 |
|
|
@}
|
1685 |
|
|
return (0);
|
1686 |
|
|
@}
|
1687 |
|
|
|
1688 |
|
|
/* Change to the directory ARG. */
|
1689 |
|
|
com_cd (arg)
|
1690 |
|
|
char *arg;
|
1691 |
|
|
@{
|
1692 |
|
|
if (chdir (arg) == -1)
|
1693 |
|
|
@{
|
1694 |
|
|
perror (arg);
|
1695 |
|
|
return 1;
|
1696 |
|
|
@}
|
1697 |
|
|
|
1698 |
|
|
com_pwd ("");
|
1699 |
|
|
return (0);
|
1700 |
|
|
@}
|
1701 |
|
|
|
1702 |
|
|
/* Print out the current working directory. */
|
1703 |
|
|
com_pwd (ignore)
|
1704 |
|
|
char *ignore;
|
1705 |
|
|
@{
|
1706 |
|
|
char dir[1024], *s;
|
1707 |
|
|
|
1708 |
|
|
s = getwd (dir);
|
1709 |
|
|
if (s == 0)
|
1710 |
|
|
@{
|
1711 |
|
|
printf ("Error getting pwd: %s\n", dir);
|
1712 |
|
|
return 1;
|
1713 |
|
|
@}
|
1714 |
|
|
|
1715 |
|
|
printf ("Current directory is %s\n", dir);
|
1716 |
|
|
return 0;
|
1717 |
|
|
@}
|
1718 |
|
|
|
1719 |
|
|
/* The user wishes to quit using this program. Just set DONE non-zero. */
|
1720 |
|
|
com_quit (arg)
|
1721 |
|
|
char *arg;
|
1722 |
|
|
@{
|
1723 |
|
|
done = 1;
|
1724 |
|
|
return (0);
|
1725 |
|
|
@}
|
1726 |
|
|
|
1727 |
|
|
/* Function which tells you that you can't do this. */
|
1728 |
|
|
too_dangerous (caller)
|
1729 |
|
|
char *caller;
|
1730 |
|
|
@{
|
1731 |
|
|
fprintf (stderr,
|
1732 |
|
|
"%s: Too dangerous for me to distribute. Write it yourself.\n",
|
1733 |
|
|
caller);
|
1734 |
|
|
@}
|
1735 |
|
|
|
1736 |
|
|
/* Return non-zero if ARG is a valid argument for CALLER, else print
|
1737 |
|
|
an error message and return zero. */
|
1738 |
|
|
int
|
1739 |
|
|
valid_argument (caller, arg)
|
1740 |
|
|
char *caller, *arg;
|
1741 |
|
|
@{
|
1742 |
|
|
if (!arg || !*arg)
|
1743 |
|
|
@{
|
1744 |
|
|
fprintf (stderr, "%s: Argument required.\n", caller);
|
1745 |
|
|
return (0);
|
1746 |
|
|
@}
|
1747 |
|
|
|
1748 |
|
|
return (1);
|
1749 |
|
|
@}
|
1750 |
|
|
@end smallexample
|