28a02d99607344761b34c53f2ebc8b1100a3fe9a
[deliverable/binutils-gdb.git] / readline / doc / rltech.texi
1 @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
5 @ifinfo
6 This document describes the GNU Readline Library, a utility for aiding
7 in the consistency of user interface across discrete programs that need
8 to provide a command line interface.
9
10 Copyright (C) 1988--2016 Free Software Foundation, Inc.
11
12 Permission is granted to make and distribute verbatim copies of
13 this manual provided the copyright notice and this permission notice
14 pare preserved on all copies.
15
16 @ignore
17 Permission is granted to process this file through TeX and print the
18 results, provided the printed document carries copying permission
19 notice identical to this one except for the removal of this paragraph
20 (this paragraph not being relevant to the printed manual).
21 @end ignore
22
23 Permission is granted to copy and distribute modified versions of this
24 manual under the conditions for verbatim copying, provided that the entire
25 resulting derived work is distributed under the terms of a permission
26 notice identical to this one.
27
28 Permission is granted to copy and distribute translations of this manual
29 into another language, under the above conditions for modified versions,
30 except that this permission notice may be stated in a translation approved
31 by the Foundation.
32 @end ifinfo
33
34 @node Programming with GNU Readline
35 @chapter Programming with GNU Readline
36
37 This chapter describes the interface between the @sc{gnu} Readline Library and
38 other programs. If you are a programmer, and you wish to include the
39 features found in @sc{gnu} Readline
40 such as completion, line editing, and interactive history manipulation
41 in your own programs, this section is for you.
42
43 @menu
44 * Basic Behavior:: Using the default behavior of Readline.
45 * Custom Functions:: Adding your own functions to Readline.
46 * Readline Variables:: Variables accessible to custom
47 functions.
48 * Readline Convenience Functions:: Functions which Readline supplies to
49 aid in writing your own custom
50 functions.
51 * Readline Signal Handling:: How Readline behaves when it receives signals.
52 * Custom Completers:: Supplanting or supplementing Readline's
53 completion functions.
54 @end menu
55
56 @node Basic Behavior
57 @section Basic Behavior
58
59 Many programs provide a command line interface, such as @code{mail},
60 @code{ftp}, and @code{sh}. For such programs, the default behaviour of
61 Readline is sufficient. This section describes how to use Readline in
62 the simplest way possible, perhaps to replace calls in your code to
63 @code{gets()} or @code{fgets()}.
64
65 @findex readline
66 @cindex readline, function
67
68 The function @code{readline()} prints a prompt @var{prompt}
69 and then reads and returns a single line of text from the user.
70 If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed.
71 The line @code{readline} returns is allocated with @code{malloc()};
72 the caller should @code{free()} the line when it has finished with it.
73 The declaration for @code{readline} in ANSI C is
74
75 @example
76 @code{char *readline (const char *@var{prompt});}
77 @end example
78
79 @noindent
80 So, one might say
81 @example
82 @code{char *line = readline ("Enter a line: ");}
83 @end example
84 @noindent
85 in order to read a line of text from the user.
86 The line returned has the final newline removed, so only the
87 text remains.
88
89 If @code{readline} encounters an @code{EOF} while reading the line, and the
90 line is empty at that point, then @code{(char *)NULL} is returned.
91 Otherwise, the line is ended just as if a newline had been typed.
92
93 Readline performs some expansion on the @var{prompt} before it is
94 displayed on the screen. See the description of @code{rl_expand_prompt}
95 (@pxref{Redisplay}) for additional details, especially if @var{prompt}
96 will contain characters that do not consume physical screen space when
97 displayed.
98
99 If you want the user to be able to get at the line later, (with
100 @key{C-p} for example), you must call @code{add_history()} to save the
101 line away in a @dfn{history} list of such lines.
102
103 @example
104 @code{add_history (line)};
105 @end example
106
107 @noindent
108 For full details on the GNU History Library, see the associated manual.
109
110 It is preferable to avoid saving empty lines on the history list, since
111 users rarely have a burning need to reuse a blank line. Here is
112 a function which usefully replaces the standard @code{gets()} library
113 function, and has the advantage of no static buffer to overflow:
114
115 @example
116 /* A static variable for holding the line. */
117 static char *line_read = (char *)NULL;
118
119 /* Read a string, and return a pointer to it.
120 Returns NULL on EOF. */
121 char *
122 rl_gets ()
123 @{
124 /* If the buffer has already been allocated,
125 return the memory to the free pool. */
126 if (line_read)
127 @{
128 free (line_read);
129 line_read = (char *)NULL;
130 @}
131
132 /* Get a line from the user. */
133 line_read = readline ("");
134
135 /* If the line has any text in it,
136 save it on the history. */
137 if (line_read && *line_read)
138 add_history (line_read);
139
140 return (line_read);
141 @}
142 @end example
143
144 This function gives the user the default behaviour of @key{TAB}
145 completion: completion on file names. If you do not want Readline to
146 complete on filenames, you can change the binding of the @key{TAB} key
147 with @code{rl_bind_key()}.
148
149 @example
150 @code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});}
151 @end example
152
153 @code{rl_bind_key()} takes two arguments: @var{key} is the character that
154 you want to bind, and @var{function} is the address of the function to
155 call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert()}
156 makes @key{TAB} insert itself.
157 @code{rl_bind_key()} returns non-zero if @var{key} is not a valid
158 ASCII character code (between 0 and 255).
159
160 Thus, to disable the default @key{TAB} behavior, the following suffices:
161 @example
162 @code{rl_bind_key ('\t', rl_insert);}
163 @end example
164
165 This code should be executed once at the start of your program; you
166 might write a function called @code{initialize_readline()} which
167 performs this and other desired initializations, such as installing
168 custom completers (@pxref{Custom Completers}).
169
170 @node Custom Functions
171 @section Custom Functions
172
173 Readline provides many functions for manipulating the text of
174 the line, but it isn't possible to anticipate the needs of all
175 programs. This section describes the various functions and variables
176 defined within the Readline library which allow a user program to add
177 customized functionality to Readline.
178
179 Before declaring any functions that customize Readline's behavior, or
180 using any functionality Readline provides in other code, an
181 application writer should include the file @code{<readline/readline.h>}
182 in any file that uses Readline's features. Since some of the definitions
183 in @code{readline.h} use the @code{stdio} library, the file
184 @code{<stdio.h>} should be included before @code{readline.h}.
185
186 @code{readline.h} defines a C preprocessor variable that should
187 be treated as an integer, @code{RL_READLINE_VERSION}, which may
188 be used to conditionally compile application code depending on
189 the installed Readline version. The value is a hexadecimal
190 encoding of the major and minor version numbers of the library,
191 of the form 0x@var{MMmm}. @var{MM} is the two-digit major
192 version number; @var{mm} is the two-digit minor version number.
193 For Readline 4.2, for example, the value of
194 @code{RL_READLINE_VERSION} would be @code{0x0402}.
195
196 @menu
197 * Readline Typedefs:: C declarations to make code readable.
198 * Function Writing:: Variables and calling conventions.
199 @end menu
200
201 @node Readline Typedefs
202 @subsection Readline Typedefs
203
204 For readability, we declare a number of new object types, all pointers
205 to functions.
206
207 The reason for declaring these new types is to make it easier to write
208 code describing pointers to C functions with appropriately prototyped
209 arguments and return values.
210
211 For instance, say we want to declare a variable @var{func} as a pointer
212 to a function which takes two @code{int} arguments and returns an
213 @code{int} (this is the type of all of the Readline bindable functions).
214 Instead of the classic C declaration
215
216 @code{int (*func)();}
217
218 @noindent
219 or the ANSI-C style declaration
220
221 @code{int (*func)(int, int);}
222
223 @noindent
224 we may write
225
226 @code{rl_command_func_t *func;}
227
228 The full list of function pointer types available is
229
230 @table @code
231 @item typedef int rl_command_func_t (int, int);
232
233 @item typedef char *rl_compentry_func_t (const char *, int);
234
235 @item typedef char **rl_completion_func_t (const char *, int, int);
236
237 @item typedef char *rl_quote_func_t (char *, int, char *);
238
239 @item typedef char *rl_dequote_func_t (char *, int);
240
241 @item typedef int rl_compignore_func_t (char **);
242
243 @item typedef void rl_compdisp_func_t (char **, int, int);
244
245 @item typedef int rl_hook_func_t (void);
246
247 @item typedef int rl_getc_func_t (FILE *);
248
249 @item typedef int rl_linebuf_func_t (char *, int);
250
251 @item typedef int rl_intfunc_t (int);
252 @item #define rl_ivoidfunc_t rl_hook_func_t
253 @item typedef int rl_icpfunc_t (char *);
254 @item typedef int rl_icppfunc_t (char **);
255
256 @item typedef void rl_voidfunc_t (void);
257 @item typedef void rl_vintfunc_t (int);
258 @item typedef void rl_vcpfunc_t (char *);
259 @item typedef void rl_vcppfunc_t (char **);
260
261 @end table
262
263 @node Function Writing
264 @subsection Writing a New Function
265
266 In order to write new functions for Readline, you need to know the
267 calling conventions for keyboard-invoked functions, and the names of the
268 variables that describe the current state of the line read so far.
269
270 The calling sequence for a command @code{foo} looks like
271
272 @example
273 @code{int foo (int count, int key)}
274 @end example
275
276 @noindent
277 where @var{count} is the numeric argument (or 1 if defaulted) and
278 @var{key} is the key that invoked this function.
279
280 It is completely up to the function as to what should be done with the
281 numeric argument. Some functions use it as a repeat count, some
282 as a flag, and others to choose alternate behavior (refreshing the current
283 line as opposed to refreshing the screen, for example). Some choose to
284 ignore it. In general, if a
285 function uses the numeric argument as a repeat count, it should be able
286 to do something useful with both negative and positive arguments.
287 At the very least, it should be aware that it can be passed a
288 negative argument.
289
290 A command function should return 0 if its action completes successfully,
291 and a value greater than zero if some error occurs.
292 This is the convention obeyed by all of the builtin Readline bindable
293 command functions.
294
295 @node Readline Variables
296 @section Readline Variables
297
298 These variables are available to function writers.
299
300 @deftypevar {char *} rl_line_buffer
301 This is the line gathered so far. You are welcome to modify the
302 contents of the line, but see @ref{Allowing Undoing}. The
303 function @code{rl_extend_line_buffer} is available to increase
304 the memory allocated to @code{rl_line_buffer}.
305 @end deftypevar
306
307 @deftypevar int rl_point
308 The offset of the current cursor position in @code{rl_line_buffer}
309 (the @emph{point}).
310 @end deftypevar
311
312 @deftypevar int rl_end
313 The number of characters present in @code{rl_line_buffer}. When
314 @code{rl_point} is at the end of the line, @code{rl_point} and
315 @code{rl_end} are equal.
316 @end deftypevar
317
318 @deftypevar int rl_mark
319 The @var{mark} (saved position) in the current line. If set, the mark
320 and point define a @emph{region}.
321 @end deftypevar
322
323 @deftypevar int rl_done
324 Setting this to a non-zero value causes Readline to return the current
325 line immediately.
326 @end deftypevar
327
328 @deftypevar int rl_num_chars_to_read
329 Setting this to a positive value before calling @code{readline()} causes
330 Readline to return after accepting that many characters, rather
331 than reading up to a character bound to @code{accept-line}.
332 @end deftypevar
333
334 @deftypevar int rl_pending_input
335 Setting this to a value makes it the next keystroke read. This is a
336 way to stuff a single character into the input stream.
337 @end deftypevar
338
339 @deftypevar int rl_dispatching
340 Set to a non-zero value if a function is being called from a key binding;
341 zero otherwise. Application functions can test this to discover whether
342 they were called directly or by Readline's dispatching mechanism.
343 @end deftypevar
344
345 @deftypevar int rl_erase_empty_line
346 Setting this to a non-zero value causes Readline to completely erase
347 the current line, including any prompt, any time a newline is typed as
348 the only character on an otherwise-empty line. The cursor is moved to
349 the beginning of the newly-blank line.
350 @end deftypevar
351
352 @deftypevar {char *} rl_prompt
353 The prompt Readline uses. This is set from the argument to
354 @code{readline()}, and should not be assigned to directly.
355 The @code{rl_set_prompt()} function (@pxref{Redisplay}) may
356 be used to modify the prompt string after calling @code{readline()}.
357 @end deftypevar
358
359 @deftypevar {char *} rl_display_prompt
360 The string displayed as the prompt. This is usually identical to
361 @var{rl_prompt}, but may be changed temporarily by functions that
362 use the prompt string as a message area, such as incremental search.
363 @end deftypevar
364
365 @deftypevar int rl_already_prompted
366 If an application wishes to display the prompt itself, rather than have
367 Readline do it the first time @code{readline()} is called, it should set
368 this variable to a non-zero value after displaying the prompt.
369 The prompt must also be passed as the argument to @code{readline()} so
370 the redisplay functions can update the display properly.
371 The calling application is responsible for managing the value; Readline
372 never sets it.
373 @end deftypevar
374
375 @deftypevar {const char *} rl_library_version
376 The version number of this revision of the library.
377 @end deftypevar
378
379 @deftypevar int rl_readline_version
380 An integer encoding the current version of the library. The encoding is
381 of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version
382 number, and @var{mm} is the two-digit minor version number.
383 For example, for Readline-4.2, @code{rl_readline_version} would have the
384 value 0x0402.
385 @end deftypevar
386
387 @deftypevar {int} rl_gnu_readline_p
388 Always set to 1, denoting that this is @sc{gnu} readline rather than some
389 emulation.
390 @end deftypevar
391
392 @deftypevar {const char *} rl_terminal_name
393 The terminal type, used for initialization. If not set by the application,
394 Readline sets this to the value of the @env{TERM} environment variable
395 the first time it is called.
396 @end deftypevar
397
398 @deftypevar {const char *} rl_readline_name
399 This variable is set to a unique name by each application using Readline.
400 The value allows conditional parsing of the inputrc file
401 (@pxref{Conditional Init Constructs}).
402 @end deftypevar
403
404 @deftypevar {FILE *} rl_instream
405 The stdio stream from which Readline reads input.
406 If @code{NULL}, Readline defaults to @var{stdin}.
407 @end deftypevar
408
409 @deftypevar {FILE *} rl_outstream
410 The stdio stream to which Readline performs output.
411 If @code{NULL}, Readline defaults to @var{stdout}.
412 @end deftypevar
413
414 @deftypevar int rl_prefer_env_winsize
415 If non-zero, Readline gives values found in the @env{LINES} and
416 @env{COLUMNS} environment variables greater precedence than values fetched
417 from the kernel when computing the screen dimensions.
418 @end deftypevar
419
420 @deftypevar {rl_command_func_t *} rl_last_func
421 The address of the last command function Readline executed. May be used to
422 test whether or not a function is being executed twice in succession, for
423 example.
424 @end deftypevar
425
426 @deftypevar {rl_hook_func_t *} rl_startup_hook
427 If non-zero, this is the address of a function to call just
428 before @code{readline} prints the first prompt.
429 @end deftypevar
430
431 @deftypevar {rl_hook_func_t *} rl_pre_input_hook
432 If non-zero, this is the address of a function to call after
433 the first prompt has been printed and just before @code{readline}
434 starts reading input characters.
435 @end deftypevar
436
437 @deftypevar {rl_hook_func_t *} rl_event_hook
438 If non-zero, this is the address of a function to call periodically
439 when Readline is waiting for terminal input.
440 By default, this will be called at most ten times a second if there
441 is no keyboard input.
442 @end deftypevar
443
444 @deftypevar {rl_getc_func_t *} rl_getc_function
445 If non-zero, Readline will call indirectly through this pointer
446 to get a character from the input stream. By default, it is set to
447 @code{rl_getc}, the default Readline character input function
448 (@pxref{Character Input}).
449 In general, an application that sets @var{rl_getc_function} should consider
450 setting @var{rl_input_available_hook} as well.
451 @end deftypevar
452
453 @deftypevar {rl_hook_func_t *} rl_signal_event_hook
454 If non-zero, this is the address of a function to call if a read system
455 call is interrupted when Readline is reading terminal input.
456 @end deftypevar
457
458 @deftypevar {rl_hook_func_t *} rl_input_available_hook
459 If non-zero, Readline will use this function's return value when it needs
460 to determine whether or not there is available input on the current input
461 source.
462 The default hook checks @code{rl_instream}; if an application is using a
463 different input source, it should set the hook appropriately.
464 Readline queries for available input when implementing intra-key-sequence
465 timeouts during input and incremental searches.
466 This may use an application-specific timeout before returning a value;
467 Readline uses the value passed to @code{rl_set_keyboard_input_timeout()}
468 or the value of the user-settable @var{keyseq-timeout} variable.
469 This is designed for use by applications using Readline's callback interface
470 (@pxref{Alternate Interface}), which may not use the traditional
471 @code{read(2)} and file descriptor interface, or other applications using
472 a different input mechanism.
473 If an application uses an input mechanism or hook that can potentially exceed
474 the value of @var{keyseq-timeout}, it should increase the timeout or set
475 this hook appropriately even when not using the callback interface.
476 In general, an application that sets @var{rl_getc_function} should consider
477 setting @var{rl_input_available_hook} as well.
478 @end deftypevar
479
480 @deftypevar {rl_voidfunc_t *} rl_redisplay_function
481 If non-zero, Readline will call indirectly through this pointer
482 to update the display with the current contents of the editing buffer.
483 By default, it is set to @code{rl_redisplay}, the default Readline
484 redisplay function (@pxref{Redisplay}).
485 @end deftypevar
486
487 @deftypevar {rl_vintfunc_t *} rl_prep_term_function
488 If non-zero, Readline will call indirectly through this pointer
489 to initialize the terminal. The function takes a single argument, an
490 @code{int} flag that says whether or not to use eight-bit characters.
491 By default, this is set to @code{rl_prep_terminal}
492 (@pxref{Terminal Management}).
493 @end deftypevar
494
495 @deftypevar {rl_voidfunc_t *} rl_deprep_term_function
496 If non-zero, Readline will call indirectly through this pointer
497 to reset the terminal. This function should undo the effects of
498 @code{rl_prep_term_function}.
499 By default, this is set to @code{rl_deprep_terminal}
500 (@pxref{Terminal Management}).
501 @end deftypevar
502
503 @deftypevar {Keymap} rl_executing_keymap
504 This variable is set to the keymap (@pxref{Keymaps}) in which the
505 currently executing readline function was found.
506 @end deftypevar
507
508 @deftypevar {Keymap} rl_binding_keymap
509 This variable is set to the keymap (@pxref{Keymaps}) in which the
510 last key binding occurred.
511 @end deftypevar
512
513 @deftypevar {char *} rl_executing_macro
514 This variable is set to the text of any currently-executing macro.
515 @end deftypevar
516
517 @deftypevar int rl_executing_key
518 The key that caused the dispatch to the currently-executing Readline function.
519 @end deftypevar
520
521 @deftypevar {char *} rl_executing_keyseq
522 The full key sequence that caused the dispatch to the currently-executing
523 Readline function.
524 @end deftypevar
525
526 @deftypevar int rl_key_sequence_length
527 The number of characters in @var{rl_executing_keyseq}.
528 @end deftypevar
529
530 @deftypevar {int} rl_readline_state
531 A variable with bit values that encapsulate the current Readline state.
532 A bit is set with the @code{RL_SETSTATE} macro, and unset with the
533 @code{RL_UNSETSTATE} macro. Use the @code{RL_ISSTATE} macro to test
534 whether a particular state bit is set. Current state bits include:
535
536 @table @code
537 @item RL_STATE_NONE
538 Readline has not yet been called, nor has it begun to initialize.
539 @item RL_STATE_INITIALIZING
540 Readline is initializing its internal data structures.
541 @item RL_STATE_INITIALIZED
542 Readline has completed its initialization.
543 @item RL_STATE_TERMPREPPED
544 Readline has modified the terminal modes to do its own input and redisplay.
545 @item RL_STATE_READCMD
546 Readline is reading a command from the keyboard.
547 @item RL_STATE_METANEXT
548 Readline is reading more input after reading the meta-prefix character.
549 @item RL_STATE_DISPATCHING
550 Readline is dispatching to a command.
551 @item RL_STATE_MOREINPUT
552 Readline is reading more input while executing an editing command.
553 @item RL_STATE_ISEARCH
554 Readline is performing an incremental history search.
555 @item RL_STATE_NSEARCH
556 Readline is performing a non-incremental history search.
557 @item RL_STATE_SEARCH
558 Readline is searching backward or forward through the history for a string.
559 @item RL_STATE_NUMERICARG
560 Readline is reading a numeric argument.
561 @item RL_STATE_MACROINPUT
562 Readline is currently getting its input from a previously-defined keyboard
563 macro.
564 @item RL_STATE_MACRODEF
565 Readline is currently reading characters defining a keyboard macro.
566 @item RL_STATE_OVERWRITE
567 Readline is in overwrite mode.
568 @item RL_STATE_COMPLETING
569 Readline is performing word completion.
570 @item RL_STATE_SIGHANDLER
571 Readline is currently executing the readline signal handler.
572 @item RL_STATE_UNDOING
573 Readline is performing an undo.
574 @item RL_STATE_INPUTPENDING
575 Readline has input pending due to a call to @code{rl_execute_next()}.
576 @item RL_STATE_TTYCSAVED
577 Readline has saved the values of the terminal's special characters.
578 @item RL_STATE_CALLBACK
579 Readline is currently using the alternate (callback) interface
580 (@pxref{Alternate Interface}).
581 @item RL_STATE_VIMOTION
582 Readline is reading the argument to a vi-mode "motion" command.
583 @item RL_STATE_MULTIKEY
584 Readline is reading a multiple-keystroke command.
585 @item RL_STATE_VICMDONCE
586 Readline has entered vi command (movement) mode at least one time during
587 the current call to @code{readline()}.
588 @item RL_STATE_DONE
589 Readline has read a key sequence bound to @code{accept-line}
590 and is about to return the line to the caller.
591 @end table
592
593 @end deftypevar
594
595 @deftypevar {int} rl_explicit_arg
596 Set to a non-zero value if an explicit numeric argument was specified by
597 the user. Only valid in a bindable command function.
598 @end deftypevar
599
600 @deftypevar {int} rl_numeric_arg
601 Set to the value of any numeric argument explicitly specified by the user
602 before executing the current Readline function. Only valid in a bindable
603 command function.
604 @end deftypevar
605
606 @deftypevar {int} rl_editing_mode
607 Set to a value denoting Readline's current editing mode. A value of
608 @var{1} means Readline is currently in emacs mode; @var{0}
609 means that vi mode is active.
610 @end deftypevar
611
612
613 @node Readline Convenience Functions
614 @section Readline Convenience Functions
615
616 @menu
617 * Function Naming:: How to give a function you write a name.
618 * Keymaps:: Making keymaps.
619 * Binding Keys:: Changing Keymaps.
620 * Associating Function Names and Bindings:: Translate function names to
621 key sequences.
622 * Allowing Undoing:: How to make your functions undoable.
623 * Redisplay:: Functions to control line display.
624 * Modifying Text:: Functions to modify @code{rl_line_buffer}.
625 * Character Input:: Functions to read keyboard input.
626 * Terminal Management:: Functions to manage terminal settings.
627 * Utility Functions:: Generally useful functions and hooks.
628 * Miscellaneous Functions:: Functions that don't fall into any category.
629 * Alternate Interface:: Using Readline in a `callback' fashion.
630 * A Readline Example:: An example Readline function.
631 * Alternate Interface Example:: An example program using the alternate interface.
632 @end menu
633
634 @node Function Naming
635 @subsection Naming a Function
636
637 The user can dynamically change the bindings of keys while using
638 Readline. This is done by representing the function with a descriptive
639 name. The user is able to type the descriptive name when referring to
640 the function. Thus, in an init file, one might find
641
642 @example
643 Meta-Rubout: backward-kill-word
644 @end example
645
646 This binds the keystroke @key{Meta-Rubout} to the function
647 @emph{descriptively} named @code{backward-kill-word}. You, as the
648 programmer, should bind the functions you write to descriptive names as
649 well. Readline provides a function for doing that:
650
651 @deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key)
652 Add @var{name} to the list of named functions. Make @var{function} be
653 the function that gets called. If @var{key} is not -1, then bind it to
654 @var{function} using @code{rl_bind_key()}.
655 @end deftypefun
656
657 Using this function alone is sufficient for most applications.
658 It is the recommended way to add a few functions to the default
659 functions that Readline has built in.
660 If you need to do something other than adding a function to Readline,
661 you may need to use the underlying functions described below.
662
663 @node Keymaps
664 @subsection Selecting a Keymap
665
666 Key bindings take place on a @dfn{keymap}. The keymap is the
667 association between the keys that the user types and the functions that
668 get run. You can make your own keymaps, copy existing keymaps, and tell
669 Readline which keymap to use.
670
671 @deftypefun Keymap rl_make_bare_keymap (void)
672 Returns a new, empty keymap. The space for the keymap is allocated with
673 @code{malloc()}; the caller should free it by calling
674 @code{rl_free_keymap()} when done.
675 @end deftypefun
676
677 @deftypefun Keymap rl_copy_keymap (Keymap map)
678 Return a new keymap which is a copy of @var{map}.
679 @end deftypefun
680
681 @deftypefun Keymap rl_make_keymap (void)
682 Return a new keymap with the printing characters bound to rl_insert,
683 the lowercase Meta characters bound to run their equivalents, and
684 the Meta digits bound to produce numeric arguments.
685 @end deftypefun
686
687 @deftypefun void rl_discard_keymap (Keymap keymap)
688 Free the storage associated with the data in @var{keymap}.
689 The caller should free @var{keymap}.
690 @end deftypefun
691
692 @deftypefun void rl_free_keymap (Keymap keymap)
693 Free all storage associated with @var{keymap}. This calls
694 @code{rl_discard_keymap} to free subordindate keymaps and macros.
695 @end deftypefun
696
697 @deftypefun int rl_empty_keymap (Keymap keymap)
698 Return non-zero if there are no keys bound to functions in @var{keymap};
699 zero if there are any keys bound.
700 @end deftypefun
701
702 Readline has several internal keymaps. These functions allow you to
703 change which keymap is active.
704
705 @deftypefun Keymap rl_get_keymap (void)
706 Returns the currently active keymap.
707 @end deftypefun
708
709 @deftypefun void rl_set_keymap (Keymap keymap)
710 Makes @var{keymap} the currently active keymap.
711 @end deftypefun
712
713 @deftypefun Keymap rl_get_keymap_by_name (const char *name)
714 Return the keymap matching @var{name}. @var{name} is one which would
715 be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
716 @end deftypefun
717
718 @deftypefun {char *} rl_get_keymap_name (Keymap keymap)
719 Return the name matching @var{keymap}. @var{name} is one which would
720 be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
721 @end deftypefun
722
723 @deftypefun int rl_set_keymap_name (const char *name, Keymap keymap)
724 Set the name of @var{keymap}. This name will then be "registered" and
725 available for use in a @code{set keymap} inputrc directive
726 @pxref{Readline Init File}).
727 The @var{name} may not be one of Readline's builtin keymap names;
728 you may not add a different name for one of Readline's builtin keymaps.
729 You may replace the name associated with a given keymap by calling this
730 function more than once with the same @var{keymap} argument.
731 You may associate a registered @var{name} with a new keymap by calling this
732 function more than once with the same @var{name} argument.
733 There is no way to remove a named keymap once the name has been
734 registered.
735 Readline will make a copy of @var{name}.
736 The return value is greater than zero unless @var{name} is one of
737 Readline's builtin keymap names or @var{keymap} is one of Readline's
738 builtin keymaps.
739 @end deftypefun
740
741 @node Binding Keys
742 @subsection Binding Keys
743
744 Key sequences are associate with functions through the keymap.
745 Readline has several internal keymaps: @code{emacs_standard_keymap},
746 @code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
747 @code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
748 @code{emacs_standard_keymap} is the default, and the examples in
749 this manual assume that.
750
751 Since @code{readline()} installs a set of default key bindings the first
752 time it is called, there is always the danger that a custom binding
753 installed before the first call to @code{readline()} will be overridden.
754 An alternate mechanism is to install custom key bindings in an
755 initialization function assigned to the @code{rl_startup_hook} variable
756 (@pxref{Readline Variables}).
757
758 These functions manage key bindings.
759
760 @deftypefun int rl_bind_key (int key, rl_command_func_t *function)
761 Binds @var{key} to @var{function} in the currently active keymap.
762 Returns non-zero in the case of an invalid @var{key}.
763 @end deftypefun
764
765 @deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map)
766 Bind @var{key} to @var{function} in @var{map}.
767 Returns non-zero in the case of an invalid @var{key}.
768 @end deftypefun
769
770 @deftypefun int rl_bind_key_if_unbound (int key, rl_command_func_t *function)
771 Binds @var{key} to @var{function} if it is not already bound in the
772 currently active keymap.
773 Returns non-zero in the case of an invalid @var{key} or if @var{key} is
774 already bound.
775 @end deftypefun
776
777 @deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map)
778 Binds @var{key} to @var{function} if it is not already bound in @var{map}.
779 Returns non-zero in the case of an invalid @var{key} or if @var{key} is
780 already bound.
781 @end deftypefun
782
783 @deftypefun int rl_unbind_key (int key)
784 Bind @var{key} to the null function in the currently active keymap.
785 Returns non-zero in case of error.
786 @end deftypefun
787
788 @deftypefun int rl_unbind_key_in_map (int key, Keymap map)
789 Bind @var{key} to the null function in @var{map}.
790 Returns non-zero in case of error.
791 @end deftypefun
792
793 @deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map)
794 Unbind all keys that execute @var{function} in @var{map}.
795 @end deftypefun
796
797 @deftypefun int rl_unbind_command_in_map (const char *command, Keymap map)
798 Unbind all keys that are bound to @var{command} in @var{map}.
799 @end deftypefun
800
801 @deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function)
802 Bind the key sequence represented by the string @var{keyseq} to the function
803 @var{function}, beginning in the current keymap.
804 This makes new keymaps as necessary.
805 The return value is non-zero if @var{keyseq} is invalid.
806 @end deftypefun
807
808 @deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
809 Bind the key sequence represented by the string @var{keyseq} to the function
810 @var{function}. This makes new keymaps as necessary.
811 Initial bindings are performed in @var{map}.
812 The return value is non-zero if @var{keyseq} is invalid.
813 @end deftypefun
814
815 @deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map)
816 Equivalent to @code{rl_bind_keyseq_in_map}.
817 @end deftypefun
818
819 @deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function)
820 Binds @var{keyseq} to @var{function} if it is not already bound in the
821 currently active keymap.
822 Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
823 already bound.
824 @end deftypefun
825
826 @deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
827 Binds @var{keyseq} to @var{function} if it is not already bound in @var{map}.
828 Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
829 already bound.
830 @end deftypefun
831
832 @deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map)
833 Bind the key sequence represented by the string @var{keyseq} to the arbitrary
834 pointer @var{data}. @var{type} says what kind of data is pointed to by
835 @var{data}; this can be a function (@code{ISFUNC}), a macro
836 (@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as
837 necessary. The initial keymap in which to do bindings is @var{map}.
838 @end deftypefun
839
840 @deftypefun int rl_parse_and_bind (char *line)
841 Parse @var{line} as if it had been read from the @code{inputrc} file and
842 perform any key bindings and variable assignments found
843 (@pxref{Readline Init File}).
844 @end deftypefun
845
846 @deftypefun int rl_read_init_file (const char *filename)
847 Read keybindings and variable assignments from @var{filename}
848 (@pxref{Readline Init File}).
849 @end deftypefun
850
851 @node Associating Function Names and Bindings
852 @subsection Associating Function Names and Bindings
853
854 These functions allow you to find out what keys invoke named functions
855 and the functions invoked by a particular key sequence. You may also
856 associate a new function name with an arbitrary function.
857
858 @deftypefun {rl_command_func_t *} rl_named_function (const char *name)
859 Return the function with name @var{name}.
860 @end deftypefun
861
862 @deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type)
863 Return the function invoked by @var{keyseq} in keymap @var{map}.
864 If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is
865 not @code{NULL}, the type of the object is returned in the @code{int} variable
866 it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}).
867 It takes a "translated" key sequence and should not be used if the key sequence
868 can include NUL.
869 @end deftypefun
870
871 @deftypefun {rl_command_func_t *} rl_function_of_keyseq_len (const char *keyseq, size_t len, Keymap map, int *type)
872 Return the function invoked by @var{keyseq} of length @var{len}
873 in keymap @var{map}. Equivalent to @code{rl_function_of_keyseq} with the
874 addition of the @var{len} parameter.
875 It takes a "translated" key sequence and should be used if the key sequence
876 can include NUL.
877 @end deftypefun
878
879 @deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function)
880 Return an array of strings representing the key sequences used to
881 invoke @var{function} in the current keymap.
882 @end deftypefun
883
884 @deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map)
885 Return an array of strings representing the key sequences used to
886 invoke @var{function} in the keymap @var{map}.
887 @end deftypefun
888
889 @deftypefun void rl_function_dumper (int readable)
890 Print the readline function names and the key sequences currently
891 bound to them to @code{rl_outstream}. If @var{readable} is non-zero,
892 the list is formatted in such a way that it can be made part of an
893 @code{inputrc} file and re-read.
894 @end deftypefun
895
896 @deftypefun void rl_list_funmap_names (void)
897 Print the names of all bindable Readline functions to @code{rl_outstream}.
898 @end deftypefun
899
900 @deftypefun {const char **} rl_funmap_names (void)
901 Return a NULL terminated array of known function names. The array is
902 sorted. The array itself is allocated, but not the strings inside. You
903 should free the array, but not the pointers, using @code{free} or
904 @code{rl_free} when you are done.
905 @end deftypefun
906
907 @deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function)
908 Add @var{name} to the list of bindable Readline command names, and make
909 @var{function} the function to be called when @var{name} is invoked.
910 @end deftypefun
911
912 @node Allowing Undoing
913 @subsection Allowing Undoing
914
915 Supporting the undo command is a painless thing, and makes your
916 functions much more useful. It is certainly easy to try
917 something if you know you can undo it.
918
919 If your function simply inserts text once, or deletes text once, and
920 uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then
921 undoing is already done for you automatically.
922
923 If you do multiple insertions or multiple deletions, or any combination
924 of these operations, you should group them together into one operation.
925 This is done with @code{rl_begin_undo_group()} and
926 @code{rl_end_undo_group()}.
927
928 The types of events that can be undone are:
929
930 @smallexample
931 enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @};
932 @end smallexample
933
934 Notice that @code{UNDO_DELETE} means to insert some text, and
935 @code{UNDO_INSERT} means to delete some text. That is, the undo code
936 tells what to undo, not how to undo it. @code{UNDO_BEGIN} and
937 @code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and
938 @code{rl_end_undo_group()}.
939
940 @deftypefun int rl_begin_undo_group (void)
941 Begins saving undo information in a group construct. The undo
942 information usually comes from calls to @code{rl_insert_text()} and
943 @code{rl_delete_text()}, but could be the result of calls to
944 @code{rl_add_undo()}.
945 @end deftypefun
946
947 @deftypefun int rl_end_undo_group (void)
948 Closes the current undo group started with @code{rl_begin_undo_group
949 ()}. There should be one call to @code{rl_end_undo_group()}
950 for each call to @code{rl_begin_undo_group()}.
951 @end deftypefun
952
953 @deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
954 Remember how to undo an event (according to @var{what}). The affected
955 text runs from @var{start} to @var{end}, and encompasses @var{text}.
956 @end deftypefun
957
958 @deftypefun void rl_free_undo_list (void)
959 Free the existing undo list.
960 @end deftypefun
961
962 @deftypefun int rl_do_undo (void)
963 Undo the first thing on the undo list. Returns @code{0} if there was
964 nothing to undo, non-zero if something was undone.
965 @end deftypefun
966
967 Finally, if you neither insert nor delete text, but directly modify the
968 existing text (e.g., change its case), call @code{rl_modifying()}
969 once, just before you modify the text. You must supply the indices of
970 the text range that you are going to modify.
971
972 @deftypefun int rl_modifying (int start, int end)
973 Tell Readline to save the text between @var{start} and @var{end} as a
974 single undo unit. It is assumed that you will subsequently modify
975 that text.
976 @end deftypefun
977
978 @node Redisplay
979 @subsection Redisplay
980
981 @deftypefun void rl_redisplay (void)
982 Change what's displayed on the screen to reflect the current contents
983 of @code{rl_line_buffer}.
984 @end deftypefun
985
986 @deftypefun int rl_forced_update_display (void)
987 Force the line to be updated and redisplayed, whether or not
988 Readline thinks the screen display is correct.
989 @end deftypefun
990
991 @deftypefun int rl_on_new_line (void)
992 Tell the update functions that we have moved onto a new (empty) line,
993 usually after outputting a newline.
994 @end deftypefun
995
996 @deftypefun int rl_on_new_line_with_prompt (void)
997 Tell the update functions that we have moved onto a new line, with
998 @var{rl_prompt} already displayed.
999 This could be used by applications that want to output the prompt string
1000 themselves, but still need Readline to know the prompt string length for
1001 redisplay.
1002 It should be used after setting @var{rl_already_prompted}.
1003 @end deftypefun
1004
1005 @deftypefun int rl_clear_visible_line (void)
1006 Clear the screen lines corresponding to the current line's contents.
1007 @end deftypefun
1008
1009 @deftypefun int rl_reset_line_state (void)
1010 Reset the display state to a clean state and redisplay the current line
1011 starting on a new line.
1012 @end deftypefun
1013
1014 @deftypefun int rl_crlf (void)
1015 Move the cursor to the start of the next screen line.
1016 @end deftypefun
1017
1018 @deftypefun int rl_show_char (int c)
1019 Display character @var{c} on @code{rl_outstream}.
1020 If Readline has not been set to display meta characters directly, this
1021 will convert meta characters to a meta-prefixed key sequence.
1022 This is intended for use by applications which wish to do their own
1023 redisplay.
1024 @end deftypefun
1025
1026 @deftypefun int rl_message (const char *, @dots{})
1027 The arguments are a format string as would be supplied to @code{printf},
1028 possibly containing conversion specifications such as @samp{%d}, and
1029 any additional arguments necessary to satisfy the conversion specifications.
1030 The resulting string is displayed in the @dfn{echo area}. The echo area
1031 is also used to display numeric arguments and search strings.
1032 You should call @code{rl_save_prompt} to save the prompt information
1033 before calling this function.
1034 @end deftypefun
1035
1036 @deftypefun int rl_clear_message (void)
1037 Clear the message in the echo area. If the prompt was saved with a call to
1038 @code{rl_save_prompt} before the last call to @code{rl_message},
1039 call @code{rl_restore_prompt} before calling this function.
1040 @end deftypefun
1041
1042 @deftypefun void rl_save_prompt (void)
1043 Save the local Readline prompt display state in preparation for
1044 displaying a new message in the message area with @code{rl_message()}.
1045 @end deftypefun
1046
1047 @deftypefun void rl_restore_prompt (void)
1048 Restore the local Readline prompt display state saved by the most
1049 recent call to @code{rl_save_prompt}.
1050 if @code{rl_save_prompt} was called to save the prompt before a call
1051 to @code{rl_message}, this function should be called before the
1052 corresponding call to @code{rl_clear_message}.
1053 @end deftypefun
1054
1055 @deftypefun int rl_expand_prompt (char *prompt)
1056 Expand any special character sequences in @var{prompt} and set up the
1057 local Readline prompt redisplay variables.
1058 This function is called by @code{readline()}. It may also be called to
1059 expand the primary prompt if the @code{rl_on_new_line_with_prompt()}
1060 function or @code{rl_already_prompted} variable is used.
1061 It returns the number of visible characters on the last line of the
1062 (possibly multi-line) prompt.
1063 Applications may indicate that the prompt contains characters that take
1064 up no physical screen space when displayed by bracketing a sequence of
1065 such characters with the special markers @code{RL_PROMPT_START_IGNORE}
1066 and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}). This may
1067 be used to embed terminal-specific escape sequences in prompts.
1068 @end deftypefun
1069
1070 @deftypefun int rl_set_prompt (const char *prompt)
1071 Make Readline use @var{prompt} for subsequent redisplay. This calls
1072 @code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt}
1073 to the result.
1074 @end deftypefun
1075
1076 @node Modifying Text
1077 @subsection Modifying Text
1078
1079 @deftypefun int rl_insert_text (const char *text)
1080 Insert @var{text} into the line at the current cursor position.
1081 Returns the number of characters inserted.
1082 @end deftypefun
1083
1084 @deftypefun int rl_delete_text (int start, int end)
1085 Delete the text between @var{start} and @var{end} in the current line.
1086 Returns the number of characters deleted.
1087 @end deftypefun
1088
1089 @deftypefun {char *} rl_copy_text (int start, int end)
1090 Return a copy of the text between @var{start} and @var{end} in
1091 the current line.
1092 @end deftypefun
1093
1094 @deftypefun int rl_kill_text (int start, int end)
1095 Copy the text between @var{start} and @var{end} in the current line
1096 to the kill ring, appending or prepending to the last kill if the
1097 last command was a kill command. The text is deleted.
1098 If @var{start} is less than @var{end},
1099 the text is appended, otherwise prepended. If the last command was
1100 not a kill, a new kill ring slot is used.
1101 @end deftypefun
1102
1103 @deftypefun int rl_push_macro_input (char *macro)
1104 Cause @var{macro} to be inserted into the line, as if it had been invoked
1105 by a key bound to a macro. Not especially useful; use
1106 @code{rl_insert_text()} instead.
1107 @end deftypefun
1108
1109 @node Character Input
1110 @subsection Character Input
1111
1112 @deftypefun int rl_read_key (void)
1113 Return the next character available from Readline's current input stream.
1114 This handles input inserted into
1115 the input stream via @var{rl_pending_input} (@pxref{Readline Variables})
1116 and @code{rl_stuff_char()}, macros, and characters read from the keyboard.
1117 While waiting for input, this function will call any function assigned to
1118 the @code{rl_event_hook} variable.
1119 @end deftypefun
1120
1121 @deftypefun int rl_getc (FILE *stream)
1122 Return the next character available from @var{stream}, which is assumed to
1123 be the keyboard.
1124 @end deftypefun
1125
1126 @deftypefun int rl_stuff_char (int c)
1127 Insert @var{c} into the Readline input stream. It will be "read"
1128 before Readline attempts to read characters from the terminal with
1129 @code{rl_read_key()}. Up to 512 characters may be pushed back.
1130 @code{rl_stuff_char} returns 1 if the character was successfully inserted;
1131 0 otherwise.
1132 @end deftypefun
1133
1134 @deftypefun int rl_execute_next (int c)
1135 Make @var{c} be the next command to be executed when @code{rl_read_key()}
1136 is called. This sets @var{rl_pending_input}.
1137 @end deftypefun
1138
1139 @deftypefun int rl_clear_pending_input (void)
1140 Unset @var{rl_pending_input}, effectively negating the effect of any
1141 previous call to @code{rl_execute_next()}. This works only if the
1142 pending input has not already been read with @code{rl_read_key()}.
1143 @end deftypefun
1144
1145 @deftypefun int rl_set_keyboard_input_timeout (int u)
1146 While waiting for keyboard input in @code{rl_read_key()}, Readline will
1147 wait for @var{u} microseconds for input before calling any function
1148 assigned to @code{rl_event_hook}. @var{u} must be greater than or equal
1149 to zero (a zero-length timeout is equivalent to a poll).
1150 The default waiting period is one-tenth of a second.
1151 Returns the old timeout value.
1152 @end deftypefun
1153
1154 @node Terminal Management
1155 @subsection Terminal Management
1156
1157 @deftypefun void rl_prep_terminal (int meta_flag)
1158 Modify the terminal settings for Readline's use, so @code{readline()}
1159 can read a single character at a time from the keyboard.
1160 The @var{meta_flag} argument should be non-zero if Readline should
1161 read eight-bit input.
1162 @end deftypefun
1163
1164 @deftypefun void rl_deprep_terminal (void)
1165 Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in
1166 the state in which it was before the most recent call to
1167 @code{rl_prep_terminal()}.
1168 @end deftypefun
1169
1170 @deftypefun void rl_tty_set_default_bindings (Keymap kmap)
1171 Read the operating system's terminal editing characters (as would be
1172 displayed by @code{stty}) to their Readline equivalents.
1173 The bindings are performed in @var{kmap}.
1174 @end deftypefun
1175
1176 @deftypefun void rl_tty_unset_default_bindings (Keymap kmap)
1177 Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so
1178 that the terminal editing characters are bound to @code{rl_insert}.
1179 The bindings are performed in @var{kmap}.
1180 @end deftypefun
1181
1182 @deftypefun int rl_tty_set_echoing (int value)
1183 Set Readline's idea of whether or not it is echoing output to its output
1184 stream (@var{rl_outstream}). If @var{value} is 0, Readline does not display
1185 output to @var{rl_outstream}; any other value enables output. The initial
1186 value is set when Readline initializes the terminal settings.
1187 This function returns the previous value.
1188 @end deftypefun
1189
1190 @deftypefun int rl_reset_terminal (const char *terminal_name)
1191 Reinitialize Readline's idea of the terminal settings using
1192 @var{terminal_name} as the terminal type (e.g., @code{vt100}).
1193 If @var{terminal_name} is @code{NULL}, the value of the @code{TERM}
1194 environment variable is used.
1195 @end deftypefun
1196
1197 @node Utility Functions
1198 @subsection Utility Functions
1199
1200 @deftypefun int rl_save_state (struct readline_state *sp)
1201 Save a snapshot of Readline's internal state to @var{sp}.
1202 The contents of the @var{readline_state} structure are documented
1203 in @file{readline.h}.
1204 The caller is responsible for allocating the structure.
1205 @end deftypefun
1206
1207 @deftypefun int rl_restore_state (struct readline_state *sp)
1208 Restore Readline's internal state to that stored in @var{sp}, which must
1209 have been saved by a call to @code{rl_save_state}.
1210 The contents of the @var{readline_state} structure are documented
1211 in @file{readline.h}.
1212 The caller is responsible for freeing the structure.
1213 @end deftypefun
1214
1215 @deftypefun void rl_free (void *mem)
1216 Deallocate the memory pointed to by @var{mem}. @var{mem} must have been
1217 allocated by @code{malloc}.
1218 @end deftypefun
1219
1220 @deftypefun void rl_replace_line (const char *text, int clear_undo)
1221 Replace the contents of @code{rl_line_buffer} with @var{text}.
1222 The point and mark are preserved, if possible.
1223 If @var{clear_undo} is non-zero, the undo list associated with the
1224 current line is cleared.
1225 @end deftypefun
1226
1227 @deftypefun void rl_extend_line_buffer (int len)
1228 Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
1229 characters, possibly reallocating it if necessary.
1230 @end deftypefun
1231
1232 @deftypefun int rl_initialize (void)
1233 Initialize or re-initialize Readline's internal state.
1234 It's not strictly necessary to call this; @code{readline()} calls it before
1235 reading any input.
1236 @end deftypefun
1237
1238 @deftypefun int rl_ding (void)
1239 Ring the terminal bell, obeying the setting of @code{bell-style}.
1240 @end deftypefun
1241
1242 @deftypefun int rl_alphabetic (int c)
1243 Return 1 if @var{c} is an alphabetic character.
1244 @end deftypefun
1245
1246 @deftypefun void rl_display_match_list (char **matches, int len, int max)
1247 A convenience function for displaying a list of strings in
1248 columnar format on Readline's output stream. @code{matches} is the list
1249 of strings, in argv format, such as a list of completion matches.
1250 @code{len} is the number of strings in @code{matches}, and @code{max}
1251 is the length of the longest string in @code{matches}. This function uses
1252 the setting of @code{print-completions-horizontally} to select how the
1253 matches are displayed (@pxref{Readline Init File Syntax}).
1254 When displaying completions, this function sets the number of columns used
1255 for display to the value of @code{completion-display-width}, the value of
1256 the environment variable @env{COLUMNS}, or the screen width, in that order.
1257 @end deftypefun
1258
1259 The following are implemented as macros, defined in @code{chardefs.h}.
1260 Applications should refrain from using them.
1261
1262 @deftypefun int _rl_uppercase_p (int c)
1263 Return 1 if @var{c} is an uppercase alphabetic character.
1264 @end deftypefun
1265
1266 @deftypefun int _rl_lowercase_p (int c)
1267 Return 1 if @var{c} is a lowercase alphabetic character.
1268 @end deftypefun
1269
1270 @deftypefun int _rl_digit_p (int c)
1271 Return 1 if @var{c} is a numeric character.
1272 @end deftypefun
1273
1274 @deftypefun int _rl_to_upper (int c)
1275 If @var{c} is a lowercase alphabetic character, return the corresponding
1276 uppercase character.
1277 @end deftypefun
1278
1279 @deftypefun int _rl_to_lower (int c)
1280 If @var{c} is an uppercase alphabetic character, return the corresponding
1281 lowercase character.
1282 @end deftypefun
1283
1284 @deftypefun int _rl_digit_value (int c)
1285 If @var{c} is a number, return the value it represents.
1286 @end deftypefun
1287
1288 @node Miscellaneous Functions
1289 @subsection Miscellaneous Functions
1290
1291 @deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map)
1292 Bind the key sequence @var{keyseq} to invoke the macro @var{macro}.
1293 The binding is performed in @var{map}. When @var{keyseq} is invoked, the
1294 @var{macro} will be inserted into the line. This function is deprecated;
1295 use @code{rl_generic_bind()} instead.
1296 @end deftypefun
1297
1298 @deftypefun void rl_macro_dumper (int readable)
1299 Print the key sequences bound to macros and their values, using
1300 the current keymap, to @code{rl_outstream}.
1301 If @var{readable} is non-zero, the list is formatted in such a way
1302 that it can be made part of an @code{inputrc} file and re-read.
1303 @end deftypefun
1304
1305 @deftypefun int rl_variable_bind (const char *variable, const char *value)
1306 Make the Readline variable @var{variable} have @var{value}.
1307 This behaves as if the readline command
1308 @samp{set @var{variable} @var{value}} had been executed in an @code{inputrc}
1309 file (@pxref{Readline Init File Syntax}).
1310 @end deftypefun
1311
1312 @deftypefun {char *} rl_variable_value (const char *variable)
1313 Return a string representing the value of the Readline variable @var{variable}.
1314 For boolean variables, this string is either @samp{on} or @samp{off}.
1315 @end deftypefun
1316
1317 @deftypefun void rl_variable_dumper (int readable)
1318 Print the readline variable names and their current values
1319 to @code{rl_outstream}.
1320 If @var{readable} is non-zero, the list is formatted in such a way
1321 that it can be made part of an @code{inputrc} file and re-read.
1322 @end deftypefun
1323
1324 @deftypefun int rl_set_paren_blink_timeout (int u)
1325 Set the time interval (in microseconds) that Readline waits when showing
1326 a balancing character when @code{blink-matching-paren} has been enabled.
1327 @end deftypefun
1328
1329 @deftypefun {char *} rl_get_termcap (const char *cap)
1330 Retrieve the string value of the termcap capability @var{cap}.
1331 Readline fetches the termcap entry for the current terminal name and
1332 uses those capabilities to move around the screen line and perform other
1333 terminal-specific operations, like erasing a line. Readline does not
1334 use all of a terminal's capabilities, and this function will return
1335 values for only those capabilities Readline uses.
1336 @end deftypefun
1337
1338 @deftypefun {void} rl_clear_history (void)
1339 Clear the history list by deleting all of the entries, in the same manner
1340 as the History library's @code{clear_history()} function.
1341 This differs from @code{clear_history} because it frees private data
1342 Readline saves in the history list.
1343 @end deftypefun
1344
1345 @node Alternate Interface
1346 @subsection Alternate Interface
1347
1348 An alternate interface is available to plain @code{readline()}. Some
1349 applications need to interleave keyboard I/O with file, device, or
1350 window system I/O, typically by using a main loop to @code{select()}
1351 on various file descriptors. To accommodate this need, readline can
1352 also be invoked as a `callback' function from an event loop. There
1353 are functions available to make this easy.
1354
1355 @deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler)
1356 Set up the terminal for readline I/O and display the initial
1357 expanded value of @var{prompt}. Save the value of @var{lhandler} to
1358 use as a handler function to call when a complete line of input has been
1359 entered.
1360 The handler function receives the text of the line as an argument.
1361 As with @code{readline()}, the handler function should @code{free} the
1362 line when it it finished with it.
1363 @end deftypefun
1364
1365 @deftypefun void rl_callback_read_char (void)
1366 Whenever an application determines that keyboard input is available, it
1367 should call @code{rl_callback_read_char()}, which will read the next
1368 character from the current input source.
1369 If that character completes the line, @code{rl_callback_read_char} will
1370 invoke the @var{lhandler} function installed by
1371 @code{rl_callback_handler_install} to process the line.
1372 Before calling the @var{lhandler} function, the terminal settings are
1373 reset to the values they had before calling
1374 @code{rl_callback_handler_install}.
1375 If the @var{lhandler} function returns,
1376 and the line handler remains installed,
1377 the terminal settings are modified for Readline's use again.
1378 @code{EOF} is indicated by calling @var{lhandler} with a
1379 @code{NULL} line.
1380 @end deftypefun
1381
1382 @deftypefun void rl_callback_sigcleanup (void)
1383 Clean up any internal state the callback interface uses to maintain state
1384 between calls to rl_callback_read_char (e.g., the state of any active
1385 incremental searches). This is intended to be used by applications that
1386 wish to perform their own signal handling; Readline's internal signal handler
1387 calls this when appropriate.
1388 @end deftypefun
1389
1390 @deftypefun void rl_callback_handler_remove (void)
1391 Restore the terminal to its initial state and remove the line handler.
1392 You may call this function from within a callback as well as independently.
1393 If the @var{lhandler} installed by @code{rl_callback_handler_install}
1394 does not exit the program, either this function or the function referred
1395 to by the value of @code{rl_deprep_term_function} should be called before
1396 the program exits to reset the terminal settings.
1397 @end deftypefun
1398
1399 @node A Readline Example
1400 @subsection A Readline Example
1401
1402 Here is a function which changes lowercase characters to their uppercase
1403 equivalents, and uppercase characters to lowercase. If
1404 this function was bound to @samp{M-c}, then typing @samp{M-c} would
1405 change the case of the character under point. Typing @samp{M-1 0 M-c}
1406 would change the case of the following 10 characters, leaving the cursor on
1407 the last character changed.
1408
1409 @example
1410 /* Invert the case of the COUNT following characters. */
1411 int
1412 invert_case_line (count, key)
1413 int count, key;
1414 @{
1415 register int start, end, i;
1416
1417 start = rl_point;
1418
1419 if (rl_point >= rl_end)
1420 return (0);
1421
1422 if (count < 0)
1423 @{
1424 direction = -1;
1425 count = -count;
1426 @}
1427 else
1428 direction = 1;
1429
1430 /* Find the end of the range to modify. */
1431 end = start + (count * direction);
1432
1433 /* Force it to be within range. */
1434 if (end > rl_end)
1435 end = rl_end;
1436 else if (end < 0)
1437 end = 0;
1438
1439 if (start == end)
1440 return (0);
1441
1442 if (start > end)
1443 @{
1444 int temp = start;
1445 start = end;
1446 end = temp;
1447 @}
1448
1449 /* Tell readline that we are modifying the line,
1450 so it will save the undo information. */
1451 rl_modifying (start, end);
1452
1453 for (i = start; i != end; i++)
1454 @{
1455 if (_rl_uppercase_p (rl_line_buffer[i]))
1456 rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
1457 else if (_rl_lowercase_p (rl_line_buffer[i]))
1458 rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
1459 @}
1460 /* Move point to on top of the last character changed. */
1461 rl_point = (direction == 1) ? end - 1 : start;
1462 return (0);
1463 @}
1464 @end example
1465
1466 @node Alternate Interface Example
1467 @subsection Alternate Interface Example
1468
1469 Here is a complete program that illustrates Readline's alternate interface.
1470 It reads lines from the terminal and displays them, providing the
1471 standard history and TAB completion functions.
1472 It understands the EOF character or "exit" to exit the program.
1473
1474 @example
1475 /* Standard include files. stdio.h is required. */
1476 #include <stdlib.h>
1477 #include <string.h>
1478 #include <unistd.h>
1479 #include <locale.h>
1480
1481 /* Used for select(2) */
1482 #include <sys/types.h>
1483 #include <sys/select.h>
1484
1485 #include <signal.h>
1486
1487 #include <stdio.h>
1488
1489 /* Standard readline include files. */
1490 #include <readline/readline.h>
1491 #include <readline/history.h>
1492
1493 static void cb_linehandler (char *);
1494 static void sighandler (int);
1495
1496 int running;
1497 int sigwinch_received;
1498 const char *prompt = "rltest$ ";
1499
1500 /* Handle SIGWINCH and window size changes when readline is not active and
1501 reading a character. */
1502 static void
1503 sighandler (int sig)
1504 @{
1505 sigwinch_received = 1;
1506 @}
1507
1508 /* Callback function called for each line when accept-line executed, EOF
1509 seen, or EOF character read. This sets a flag and returns; it could
1510 also call exit(3). */
1511 static void
1512 cb_linehandler (char *line)
1513 @{
1514 /* Can use ^D (stty eof) or `exit' to exit. */
1515 if (line == NULL || strcmp (line, "exit") == 0)
1516 @{
1517 if (line == 0)
1518 printf ("\n");
1519 printf ("exit\n");
1520 /* This function needs to be called to reset the terminal settings,
1521 and calling it from the line handler keeps one extra prompt from
1522 being displayed. */
1523 rl_callback_handler_remove ();
1524
1525 running = 0;
1526 @}
1527 else
1528 @{
1529 if (*line)
1530 add_history (line);
1531 printf ("input line: %s\n", line);
1532 free (line);
1533 @}
1534 @}
1535
1536 int
1537 main (int c, char **v)
1538 @{
1539 fd_set fds;
1540 int r;
1541
1542 /* Set the default locale values according to environment variables. */
1543 setlocale (LC_ALL, "");
1544
1545 /* Handle window size changes when readline is not active and reading
1546 characters. */
1547 signal (SIGWINCH, sighandler);
1548
1549 /* Install the line handler. */
1550 rl_callback_handler_install (prompt, cb_linehandler);
1551
1552 /* Enter a simple event loop. This waits until something is available
1553 to read on readline's input stream (defaults to standard input) and
1554 calls the builtin character read callback to read it. It does not
1555 have to modify the user's terminal settings. */
1556 running = 1;
1557 while (running)
1558 @{
1559 FD_ZERO (&fds);
1560 FD_SET (fileno (rl_instream), &fds);
1561
1562 r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
1563 if (r < 0 && errno != EINTR)
1564 @{
1565 perror ("rltest: select");
1566 rl_callback_handler_remove ();
1567 break;
1568 @}
1569 if (sigwinch_received)
1570 @{
1571 rl_resize_terminal ();
1572 sigwinch_received = 0;
1573 @}
1574 if (r < 0)
1575 continue;
1576
1577 if (FD_ISSET (fileno (rl_instream), &fds))
1578 rl_callback_read_char ();
1579 @}
1580
1581 printf ("rltest: Event loop has exited\n");
1582 return 0;
1583 @}
1584 @end example
1585
1586 @node Readline Signal Handling
1587 @section Readline Signal Handling
1588
1589 Signals are asynchronous events sent to a process by the Unix kernel,
1590 sometimes on behalf of another process. They are intended to indicate
1591 exceptional events, like a user pressing the interrupt key on his terminal,
1592 or a network connection being broken. There is a class of signals that can
1593 be sent to the process currently reading input from the keyboard. Since
1594 Readline changes the terminal attributes when it is called, it needs to
1595 perform special processing when such a signal is received in order to
1596 restore the terminal to a sane state, or provide application writers with
1597 functions to do so manually.
1598
1599 Readline contains an internal signal handler that is installed for a
1600 number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
1601 @code{SIGHUP},
1602 @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
1603 When one of these signals is received, the signal handler
1604 will reset the terminal attributes to those that were in effect before
1605 @code{readline()} was called, reset the signal handling to what it was
1606 before @code{readline()} was called, and resend the signal to the calling
1607 application.
1608 If and when the calling application's signal handler returns, Readline
1609 will reinitialize the terminal and continue to accept input.
1610 When a @code{SIGINT} is received, the Readline signal handler performs
1611 some additional work, which will cause any partially-entered line to be
1612 aborted (see the description of @code{rl_free_line_state()} below).
1613
1614 There is an additional Readline signal handler, for @code{SIGWINCH}, which
1615 the kernel sends to a process whenever the terminal's size changes (for
1616 example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH}
1617 handler updates Readline's internal screen size information, and then calls
1618 any @code{SIGWINCH} signal handler the calling application has installed.
1619 Readline calls the application's @code{SIGWINCH} signal handler without
1620 resetting the terminal to its original state. If the application's signal
1621 handler does more than update its idea of the terminal size and return (for
1622 example, a @code{longjmp} back to a main processing loop), it @emph{must}
1623 call @code{rl_cleanup_after_signal()} (described below), to restore the
1624 terminal state.
1625
1626 When an application is using the callback interface
1627 (@pxref{Alternate Interface}), Readline installs signal handlers only for
1628 the duration of the call to @code{rl_callback_read_char}. Applications
1629 using the callback interface should be prepared to clean up Readline's
1630 state if they wish to handle the signal before the line handler completes
1631 and restores the terminal state.
1632
1633 If an application using the callback interface wishes to have Readline
1634 install its signal handlers at the time the application calls
1635 @code{rl_callback_handler_install} and remove them only when a complete
1636 line of input has been read, it should set the
1637 @code{rl_persistent_signal_handlers} variable to a non-zero value.
1638 This allows an application to defer all of the handling of the signals
1639 Readline catches to Readline.
1640 Applications should use this variable with care; it can result in Readline
1641 catching signals and not acting on them (or allowing the application to react
1642 to them) until the application calls @code{rl_callback_read_char}. This
1643 can result in an application becoming less responsive to keyboard signals
1644 like SIGINT.
1645 If an application does not want or need to perform any signal handling, or
1646 does not need to do any processing between calls to @code{rl_callback_read_char},
1647 setting this variable may be desirable.
1648
1649 Readline provides two variables that allow application writers to
1650 control whether or not it will catch certain signals and act on them
1651 when they are received. It is important that applications change the
1652 values of these variables only when calling @code{readline()}, not in
1653 a signal handler, so Readline's internal signal state is not corrupted.
1654
1655 @deftypevar int rl_catch_signals
1656 If this variable is non-zero, Readline will install signal handlers for
1657 @code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM},
1658 @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.
1659
1660 The default value of @code{rl_catch_signals} is 1.
1661 @end deftypevar
1662
1663 @deftypevar int rl_catch_sigwinch
1664 If this variable is set to a non-zero value,
1665 Readline will install a signal handler for @code{SIGWINCH}.
1666
1667 The default value of @code{rl_catch_sigwinch} is 1.
1668 @end deftypevar
1669
1670 @deftypevar int rl_persistent_signal_handlers
1671 If an application using the callback interface wishes Readline's signal
1672 handlers to be installed and active during the set of calls to
1673 @code{rl_callback_read_char} that constitutes an entire single line,
1674 it should set this variable to a non-zero value.
1675
1676 The default value of @code{rl_persistent_signal_handlers} is 0.
1677 @end deftypevar
1678
1679 @deftypevar int rl_change_environment
1680 If this variable is set to a non-zero value,
1681 and Readline is handling @code{SIGWINCH}, Readline will modify the
1682 @var{LINES} and @var{COLUMNS} environment variables upon receipt of a
1683 @code{SIGWINCH}
1684
1685 The default value of @code{rl_change_environment} is 1.
1686 @end deftypevar
1687
1688 If an application does not wish to have Readline catch any signals, or
1689 to handle signals other than those Readline catches (@code{SIGHUP},
1690 for example),
1691 Readline provides convenience functions to do the necessary terminal
1692 and internal state cleanup upon receipt of a signal.
1693
1694 @deftypefun int rl_pending_signal (void)
1695 Return the signal number of the most recent signal Readline received but
1696 has not yet handled, or 0 if there is no pending signal.
1697 @end deftypefun
1698
1699 @deftypefun void rl_cleanup_after_signal (void)
1700 This function will reset the state of the terminal to what it was before
1701 @code{readline()} was called, and remove the Readline signal handlers for
1702 all signals, depending on the values of @code{rl_catch_signals} and
1703 @code{rl_catch_sigwinch}.
1704 @end deftypefun
1705
1706 @deftypefun void rl_free_line_state (void)
1707 This will free any partial state associated with the current input line
1708 (undo information, any partial history entry, any partially-entered
1709 keyboard macro, and any partially-entered numeric argument). This
1710 should be called before @code{rl_cleanup_after_signal()}. The
1711 Readline signal handler for @code{SIGINT} calls this to abort the
1712 current input line.
1713 @end deftypefun
1714
1715 @deftypefun void rl_reset_after_signal (void)
1716 This will reinitialize the terminal and reinstall any Readline signal
1717 handlers, depending on the values of @code{rl_catch_signals} and
1718 @code{rl_catch_sigwinch}.
1719 @end deftypefun
1720
1721 If an application wants to force Readline to handle any signals that
1722 have arrived while it has been executing, @code{rl_check_signals()}
1723 will call Readline's internal signal handler if there are any pending
1724 signals. This is primarily intended for those applications that use
1725 a custom @code{rl_getc_function} (@pxref{Readline Variables}) and wish
1726 to handle signals received while waiting for input.
1727
1728 @deftypefun void rl_check_signals (void)
1729 If there are any pending signals, call Readline's internal signal handling
1730 functions to process them. @code{rl_pending_signal()} can be used independently
1731 to determine whether or not there are any pending signals.
1732 @end deftypefun
1733
1734 If an application does not wish Readline to catch @code{SIGWINCH}, it may
1735 call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force
1736 Readline to update its idea of the terminal size when a @code{SIGWINCH}
1737 is received.
1738
1739 @deftypefun void rl_echo_signal_char (int sig)
1740 If an application wishes to install its own signal handlers, but still
1741 have readline display characters that generate signals, calling this
1742 function with @var{sig} set to @code{SIGINT}, @code{SIGQUIT}, or
1743 @code{SIGTSTP} will display the character generating that signal.
1744 @end deftypefun
1745
1746 @deftypefun void rl_resize_terminal (void)
1747 Update Readline's internal screen size by reading values from the kernel.
1748 @end deftypefun
1749
1750 @deftypefun void rl_set_screen_size (int rows, int cols)
1751 Set Readline's idea of the terminal size to @var{rows} rows and
1752 @var{cols} columns. If either @var{rows} or @var{columns} is less than
1753 or equal to 0, Readline's idea of that terminal dimension is unchanged.
1754 @end deftypefun
1755
1756 If an application does not want to install a @code{SIGWINCH} handler, but
1757 is still interested in the screen dimensions, Readline's idea of the screen
1758 size may be queried.
1759
1760 @deftypefun void rl_get_screen_size (int *rows, int *cols)
1761 Return Readline's idea of the terminal's size in the
1762 variables pointed to by the arguments.
1763 @end deftypefun
1764
1765 @deftypefun void rl_reset_screen_size (void)
1766 Cause Readline to reobtain the screen size and recalculate its dimensions.
1767 @end deftypefun
1768
1769 The following functions install and remove Readline's signal handlers.
1770
1771 @deftypefun int rl_set_signals (void)
1772 Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
1773 @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
1774 @code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
1775 @code{rl_catch_signals} and @code{rl_catch_sigwinch}.
1776 @end deftypefun
1777
1778 @deftypefun int rl_clear_signals (void)
1779 Remove all of the Readline signal handlers installed by
1780 @code{rl_set_signals()}.
1781 @end deftypefun
1782
1783 @node Custom Completers
1784 @section Custom Completers
1785 @cindex application-specific completion functions
1786
1787 Typically, a program that reads commands from the user has a way of
1788 disambiguating commands and data. If your program is one of these, then
1789 it can provide completion for commands, data, or both.
1790 The following sections describe how your program and Readline
1791 cooperate to provide this service.
1792
1793 @menu
1794 * How Completing Works:: The logic used to do completion.
1795 * Completion Functions:: Functions provided by Readline.
1796 * Completion Variables:: Variables which control completion.
1797 * A Short Completion Example:: An example of writing completer subroutines.
1798 @end menu
1799
1800 @node How Completing Works
1801 @subsection How Completing Works
1802
1803 In order to complete some text, the full list of possible completions
1804 must be available. That is, it is not possible to accurately
1805 expand a partial word without knowing all of the possible words
1806 which make sense in that context. The Readline library provides
1807 the user interface to completion, and two of the most common
1808 completion functions: filename and username. For completing other types
1809 of text, you must write your own completion function. This section
1810 describes exactly what such functions must do, and provides an example.
1811
1812 There are three major functions used to perform completion:
1813
1814 @enumerate
1815 @item
1816 The user-interface function @code{rl_complete()}. This function is
1817 called with the same arguments as other bindable Readline functions:
1818 @var{count} and @var{invoking_key}.
1819 It isolates the word to be completed and calls
1820 @code{rl_completion_matches()} to generate a list of possible completions.
1821 It then either lists the possible completions, inserts the possible
1822 completions, or actually performs the
1823 completion, depending on which behavior is desired.
1824
1825 @item
1826 The internal function @code{rl_completion_matches()} uses an
1827 application-supplied @dfn{generator} function to generate the list of
1828 possible matches, and then returns the array of these matches.
1829 The caller should place the address of its generator function in
1830 @code{rl_completion_entry_function}.
1831
1832 @item
1833 The generator function is called repeatedly from
1834 @code{rl_completion_matches()}, returning a string each time. The
1835 arguments to the generator function are @var{text} and @var{state}.
1836 @var{text} is the partial word to be completed. @var{state} is zero the
1837 first time the function is called, allowing the generator to perform
1838 any necessary initialization, and a positive non-zero integer for
1839 each subsequent call. The generator function returns
1840 @code{(char *)NULL} to inform @code{rl_completion_matches()} that there are
1841 no more possibilities left. Usually the generator function computes the
1842 list of possible completions when @var{state} is zero, and returns them
1843 one at a time on subsequent calls. Each string the generator function
1844 returns as a match must be allocated with @code{malloc()}; Readline
1845 frees the strings when it has finished with them.
1846 Such a generator function is referred to as an
1847 @dfn{application-specific completion function}.
1848
1849 @end enumerate
1850
1851 @deftypefun int rl_complete (int ignore, int invoking_key)
1852 Complete the word at or before point. You have supplied the function
1853 that does the initial simple matching selection algorithm (see
1854 @code{rl_completion_matches()}). The default is to do filename completion.
1855 @end deftypefun
1856
1857 @deftypevar {rl_compentry_func_t *} rl_completion_entry_function
1858 This is a pointer to the generator function for
1859 @code{rl_completion_matches()}.
1860 If the value of @code{rl_completion_entry_function} is
1861 @code{NULL} then the default filename generator
1862 function, @code{rl_filename_completion_function()}, is used.
1863 An @dfn{application-specific completion function} is a function whose
1864 address is assigned to @code{rl_completion_entry_function} and whose
1865 return values are used to generate possible completions.
1866 @end deftypevar
1867
1868 @node Completion Functions
1869 @subsection Completion Functions
1870
1871 Here is the complete list of callable completion functions present in
1872 Readline.
1873
1874 @deftypefun int rl_complete_internal (int what_to_do)
1875 Complete the word at or before point. @var{what_to_do} says what to do
1876 with the completion. A value of @samp{?} means list the possible
1877 completions. @samp{TAB} means do standard completion. @samp{*} means
1878 insert all of the possible completions. @samp{!} means to display
1879 all of the possible completions, if there is more than one, as well as
1880 performing partial completion. @samp{@@} is similar to @samp{!}, but
1881 possible completions are not listed if the possible completions share
1882 a common prefix.
1883 @end deftypefun
1884
1885 @deftypefun int rl_complete (int ignore, int invoking_key)
1886 Complete the word at or before point. You have supplied the function
1887 that does the initial simple matching selection algorithm (see
1888 @code{rl_completion_matches()} and @code{rl_completion_entry_function}).
1889 The default is to do filename
1890 completion. This calls @code{rl_complete_internal()} with an
1891 argument depending on @var{invoking_key}.
1892 @end deftypefun
1893
1894 @deftypefun int rl_possible_completions (int count, int invoking_key)
1895 List the possible completions. See description of @code{rl_complete
1896 ()}. This calls @code{rl_complete_internal()} with an argument of
1897 @samp{?}.
1898 @end deftypefun
1899
1900 @deftypefun int rl_insert_completions (int count, int invoking_key)
1901 Insert the list of possible completions into the line, deleting the
1902 partially-completed word. See description of @code{rl_complete()}.
1903 This calls @code{rl_complete_internal()} with an argument of @samp{*}.
1904 @end deftypefun
1905
1906 @deftypefun int rl_completion_mode (rl_command_func_t *cfunc)
1907 Returns the appropriate value to pass to @code{rl_complete_internal()}
1908 depending on whether @var{cfunc} was called twice in succession and
1909 the values of the @code{show-all-if-ambiguous} and
1910 @code{show-all-if-unmodified} variables.
1911 Application-specific completion functions may use this function to present
1912 the same interface as @code{rl_complete()}.
1913 @end deftypefun
1914
1915 @deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)
1916 Returns an array of strings which is a list of completions for
1917 @var{text}. If there are no completions, returns @code{NULL}.
1918 The first entry in the returned array is the substitution for @var{text}.
1919 The remaining entries are the possible completions. The array is
1920 terminated with a @code{NULL} pointer.
1921
1922 @var{entry_func} is a function of two args, and returns a
1923 @code{char *}. The first argument is @var{text}. The second is a
1924 state argument; it is zero on the first call, and non-zero on subsequent
1925 calls. @var{entry_func} returns a @code{NULL} pointer to the caller
1926 when there are no more matches.
1927 @end deftypefun
1928
1929 @deftypefun {char *} rl_filename_completion_function (const char *text, int state)
1930 A generator function for filename completion in the general case.
1931 @var{text} is a partial filename.
1932 The Bash source is a useful reference for writing application-specific
1933 completion functions (the Bash completion functions call this and other
1934 Readline functions).
1935 @end deftypefun
1936
1937 @deftypefun {char *} rl_username_completion_function (const char *text, int state)
1938 A completion generator for usernames. @var{text} contains a partial
1939 username preceded by a random character (usually @samp{~}). As with all
1940 completion generators, @var{state} is zero on the first call and non-zero
1941 for subsequent calls.
1942 @end deftypefun
1943
1944 @node Completion Variables
1945 @subsection Completion Variables
1946
1947 @deftypevar {rl_compentry_func_t *} rl_completion_entry_function
1948 A pointer to the generator function for @code{rl_completion_matches()}.
1949 @code{NULL} means to use @code{rl_filename_completion_function()},
1950 the default filename completer.
1951 @end deftypevar
1952
1953 @deftypevar {rl_completion_func_t *} rl_attempted_completion_function
1954 A pointer to an alternative function to create matches.
1955 The function is called with @var{text}, @var{start}, and @var{end}.
1956 @var{start} and @var{end} are indices in @code{rl_line_buffer} defining
1957 the boundaries of @var{text}, which is a character string.
1958 If this function exists and returns @code{NULL}, or if this variable is
1959 set to @code{NULL}, then @code{rl_complete()} will call the value of
1960 @code{rl_completion_entry_function} to generate matches, otherwise the
1961 array of strings returned will be used.
1962 If this function sets the @code{rl_attempted_completion_over}
1963 variable to a non-zero value, Readline will not perform its default
1964 completion even if this function returns no matches.
1965 @end deftypevar
1966
1967 @deftypevar {rl_quote_func_t *} rl_filename_quoting_function
1968 A pointer to a function that will quote a filename in an
1969 application-specific fashion. This is called if filename completion is being
1970 attempted and one of the characters in @code{rl_filename_quote_characters}
1971 appears in a completed filename. The function is called with
1972 @var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text}
1973 is the filename to be quoted. The @var{match_type} is either
1974 @code{SINGLE_MATCH}, if there is only one completion match, or
1975 @code{MULT_MATCH}. Some functions use this to decide whether or not to
1976 insert a closing quote character. The @var{quote_pointer} is a pointer
1977 to any opening quote character the user typed. Some functions choose
1978 to reset this character.
1979 @end deftypevar
1980
1981 @deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function
1982 A pointer to a function that will remove application-specific quoting
1983 characters from a filename before completion is attempted, so those
1984 characters do not interfere with matching the text against names in
1985 the filesystem. It is called with @var{text}, the text of the word
1986 to be dequoted, and @var{quote_char}, which is the quoting character
1987 that delimits the filename (usually @samp{'} or @samp{"}). If
1988 @var{quote_char} is zero, the filename was not in an embedded string.
1989 @end deftypevar
1990
1991 @deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p
1992 A pointer to a function to call that determines whether or not a specific
1993 character in the line buffer is quoted, according to whatever quoting
1994 mechanism the program calling Readline uses. The function is called with
1995 two arguments: @var{text}, the text of the line, and @var{index}, the
1996 index of the character in the line. It is used to decide whether a
1997 character found in @code{rl_completer_word_break_characters} should be
1998 used to break words for the completer.
1999 @end deftypevar
2000
2001 @deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function
2002 This function, if defined, is called by the completer when real filename
2003 completion is done, after all the matching names have been generated.
2004 It is passed a @code{NULL} terminated array of matches.
2005 The first element (@code{matches[0]}) is the
2006 maximal substring common to all matches. This function can
2007 re-arrange the list of matches as required, but each element deleted
2008 from the array must be freed.
2009 @end deftypevar
2010
2011 @deftypevar {rl_icppfunc_t *} rl_directory_completion_hook
2012 This function, if defined, is allowed to modify the directory portion
2013 of filenames Readline completes.
2014 It could be used to expand symbolic links or shell variables in pathnames.
2015 It is called with the address of a string (the current directory name) as an
2016 argument, and may modify that string.
2017 If the string is replaced with a new string, the old value should be freed.
2018 Any modified directory name should have a trailing slash.
2019 The modified value will be used as part of the completion, replacing
2020 the directory portion of the pathname the user typed.
2021 At the least, even if no other expansion is performed, this function should
2022 remove any quote characters from the directory name, because its result will
2023 be passed directly to @code{opendir()}.
2024
2025 The directory completion hook returns an integer that should be non-zero if
2026 the function modifies its directory argument.
2027 The function should not modify the directory argument if it returns 0.
2028 @end deftypevar
2029
2030 @deftypevar {rl_icppfunc_t *} rl_directory_rewrite_hook;
2031 If non-zero, this is the address of a function to call when completing
2032 a directory name. This function takes the address of the directory name
2033 to be modified as an argument. Unlike @code{rl_directory_completion_hook},
2034 it only modifies the directory name used in @code{opendir}, not what is
2035 displayed when the possible completions are printed or inserted. It is
2036 called before rl_directory_completion_hook.
2037 At the least, even if no other expansion is performed, this function should
2038 remove any quote characters from the directory name, because its result will
2039 be passed directly to @code{opendir()}.
2040
2041 The directory rewrite hook returns an integer that should be non-zero if
2042 the function modfies its directory argument.
2043 The function should not modify the directory argument if it returns 0.
2044 @end deftypevar
2045
2046 @deftypevar {rl_icppfunc_t *} rl_filename_stat_hook
2047 If non-zero, this is the address of a function for the completer to
2048 call before deciding which character to append to a completed name.
2049 This function modifies its filename name argument, and the modified value
2050 is passed to @code{stat()} to determine the file's type and characteristics.
2051 This function does not need to remove quote characters from the filename.
2052
2053 The stat hook returns an integer that should be non-zero if
2054 the function modfies its directory argument.
2055 The function should not modify the directory argument if it returns 0.
2056 @end deftypevar
2057
2058 @deftypevar {rl_dequote_func_t *} rl_filename_rewrite_hook
2059 If non-zero, this is the address of a function called when reading
2060 directory entries from the filesystem for completion and comparing
2061 them to the partial word to be completed. The function should
2062 perform any necessary application or system-specific conversion on
2063 the filename, such as converting between character sets or converting
2064 from a filesystem format to a character input format.
2065 The function takes two arguments: @var{fname}, the filename to be converted,
2066 and @var{fnlen}, its length in bytes.
2067 It must either return its first argument (if no conversion takes place)
2068 or the converted filename in newly-allocated memory. The converted
2069 form is used to compare against the word to be completed, and, if it
2070 matches, is added to the list of matches. Readline will free the
2071 allocated string.
2072 @end deftypevar
2073
2074 @deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook
2075 If non-zero, then this is the address of a function to call when
2076 completing a word would normally display the list of possible matches.
2077 This function is called in lieu of Readline displaying the list.
2078 It takes three arguments:
2079 (@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
2080 where @var{matches} is the array of matching strings,
2081 @var{num_matches} is the number of strings in that array, and
2082 @var{max_length} is the length of the longest string in that array.
2083 Readline provides a convenience function, @code{rl_display_match_list},
2084 that takes care of doing the display to Readline's output stream.
2085 You may call that function from this hook.
2086 @end deftypevar
2087
2088 @deftypevar {const char *} rl_basic_word_break_characters
2089 The basic list of characters that signal a break between words for the
2090 completer routine. The default value of this variable is the characters
2091 which break words for completion in Bash:
2092 @code{" \t\n\"\\'`@@$><=;|&@{("}.
2093 @end deftypevar
2094
2095 @deftypevar {const char *} rl_basic_quote_characters
2096 A list of quote characters which can cause a word break.
2097 @end deftypevar
2098
2099 @deftypevar {const char *} rl_completer_word_break_characters
2100 The list of characters that signal a break between words for
2101 @code{rl_complete_internal()}. The default list is the value of
2102 @code{rl_basic_word_break_characters}.
2103 @end deftypevar
2104
2105 @deftypevar {rl_cpvfunc_t *} rl_completion_word_break_hook
2106 If non-zero, this is the address of a function to call when Readline is
2107 deciding where to separate words for word completion. It should return
2108 a character string like @code{rl_completer_word_break_characters} to be
2109 used to perform the current completion. The function may choose to set
2110 @code{rl_completer_word_break_characters} itself. If the function
2111 returns @code{NULL}, @code{rl_completer_word_break_characters} is used.
2112 @end deftypevar
2113
2114 @deftypevar {const char *} rl_completer_quote_characters
2115 A list of characters which can be used to quote a substring of the line.
2116 Completion occurs on the entire substring, and within the substring
2117 @code{rl_completer_word_break_characters} are treated as any other character,
2118 unless they also appear within this list.
2119 @end deftypevar
2120
2121 @deftypevar {const char *} rl_filename_quote_characters
2122 A list of characters that cause a filename to be quoted by the completer
2123 when they appear in a completed filename. The default is the null string.
2124 @end deftypevar
2125
2126 @deftypevar {const char *} rl_special_prefixes
2127 The list of characters that are word break characters, but should be
2128 left in @var{text} when it is passed to the completion function.
2129 Programs can use this to help determine what kind of completing to do.
2130 For instance, Bash sets this variable to "$@@" so that it can complete
2131 shell variables and hostnames.
2132 @end deftypevar
2133
2134 @deftypevar int rl_completion_query_items
2135 Up to this many items will be displayed in response to a
2136 possible-completions call. After that, readline asks the user if she is sure
2137 she wants to see them all. The default value is 100. A negative value
2138 indicates that Readline should never ask the user.
2139 @end deftypevar
2140
2141 @deftypevar {int} rl_completion_append_character
2142 When a single completion alternative matches at the end of the command
2143 line, this character is appended to the inserted completion text. The
2144 default is a space character (@samp{ }). Setting this to the null
2145 character (@samp{\0}) prevents anything being appended automatically.
2146 This can be changed in application-specific completion functions to
2147 provide the ``most sensible word separator character'' according to
2148 an application-specific command line syntax specification.
2149 It is set to the default before any application-specific completion function
2150 is called, and may only be changed within such a function.
2151 @end deftypevar
2152
2153 @deftypevar int rl_completion_suppress_append
2154 If non-zero, @var{rl_completion_append_character} is not appended to
2155 matches at the end of the command line, as described above.
2156 It is set to 0 before any application-specific completion function
2157 is called, and may only be changed within such a function.
2158 @end deftypevar
2159
2160 @deftypevar int rl_completion_quote_character
2161 When Readline is completing quoted text, as delimited by one of the
2162 characters in @var{rl_completer_quote_characters}, it sets this variable
2163 to the quoting character found.
2164 This is set before any application-specific completion function is called.
2165 @end deftypevar
2166
2167 @deftypevar int rl_completion_suppress_quote
2168 If non-zero, Readline does not append a matching quote character when
2169 performing completion on a quoted string.
2170 It is set to 0 before any application-specific completion function
2171 is called, and may only be changed within such a function.
2172 @end deftypevar
2173
2174 @deftypevar int rl_completion_found_quote
2175 When Readline is completing quoted text, it sets this variable
2176 to a non-zero value if the word being completed contains or is delimited
2177 by any quoting characters, including backslashes.
2178 This is set before any application-specific completion function is called.
2179 @end deftypevar
2180
2181 @deftypevar int rl_completion_mark_symlink_dirs
2182 If non-zero, a slash will be appended to completed filenames that are
2183 symbolic links to directory names, subject to the value of the
2184 user-settable @var{mark-directories} variable.
2185 This variable exists so that application-specific completion functions
2186 can override the user's global preference (set via the
2187 @var{mark-symlinked-directories} Readline variable) if appropriate.
2188 This variable is set to the user's preference before any
2189 application-specific completion function is called, so unless that
2190 function modifies the value, the user's preferences are honored.
2191 @end deftypevar
2192
2193 @deftypevar int rl_ignore_completion_duplicates
2194 If non-zero, then duplicates in the matches are removed.
2195 The default is 1.
2196 @end deftypevar
2197
2198 @deftypevar int rl_filename_completion_desired
2199 Non-zero means that the results of the matches are to be treated as
2200 filenames. This is @emph{always} zero when completion is attempted,
2201 and can only be changed
2202 within an application-specific completion function. If it is set to a
2203 non-zero value by such a function, directory names have a slash appended
2204 and Readline attempts to quote completed filenames if they contain any
2205 characters in @code{rl_filename_quote_characters} and
2206 @code{rl_filename_quoting_desired} is set to a non-zero value.
2207 @end deftypevar
2208
2209 @deftypevar int rl_filename_quoting_desired
2210 Non-zero means that the results of the matches are to be quoted using
2211 double quotes (or an application-specific quoting mechanism) if the
2212 completed filename contains any characters in
2213 @code{rl_filename_quote_chars}. This is @emph{always} non-zero
2214 when completion is attempted, and can only be changed within an
2215 application-specific completion function.
2216 The quoting is effected via a call to the function pointed to
2217 by @code{rl_filename_quoting_function}.
2218 @end deftypevar
2219
2220 @deftypevar int rl_attempted_completion_over
2221 If an application-specific completion function assigned to
2222 @code{rl_attempted_completion_function} sets this variable to a non-zero
2223 value, Readline will not perform its default filename completion even
2224 if the application's completion function returns no matches.
2225 It should be set only by an application's completion function.
2226 @end deftypevar
2227
2228 @deftypevar int rl_sort_completion_matches
2229 If an application sets this variable to 0, Readline will not sort the
2230 list of completions (which implies that it cannot remove any duplicate
2231 completions). The default value is 1, which means that Readline will
2232 sort the completions and, depending on the value of
2233 @code{rl_ignore_completion_duplicates}, will attempt to remove duplicate
2234 matches.
2235 @end deftypevar
2236
2237 @deftypevar int rl_completion_type
2238 Set to a character describing the type of completion Readline is currently
2239 attempting; see the description of @code{rl_complete_internal()}
2240 (@pxref{Completion Functions}) for the list of characters.
2241 This is set to the appropriate value before any application-specific
2242 completion function is called, allowing such functions to present
2243 the same interface as @code{rl_complete()}.
2244 @end deftypevar
2245
2246 @deftypevar int rl_completion_invoking_key
2247 Set to the final character in the key sequence that invoked one of the
2248 completion functions that call @code{rl_complete_internal()}. This is
2249 set to the appropriate value before any application-specific completion
2250 function is called.
2251 @end deftypevar
2252
2253 @deftypevar int rl_inhibit_completion
2254 If this variable is non-zero, completion is inhibited. The completion
2255 character will be inserted as any other bound to @code{self-insert}.
2256 @end deftypevar
2257
2258 @node A Short Completion Example
2259 @subsection A Short Completion Example
2260
2261 Here is a small application demonstrating the use of the GNU Readline
2262 library. It is called @code{fileman}, and the source code resides in
2263 @file{examples/fileman.c}. This sample application provides
2264 completion of command names, line editing features, and access to the
2265 history list.
2266
2267 @page
2268 @smallexample
2269 /* fileman.c -- A tiny application which demonstrates how to use the
2270 GNU Readline library. This application interactively allows users
2271 to manipulate files and their modes. */
2272
2273 #ifdef HAVE_CONFIG_H
2274 # include <config.h>
2275 #endif
2276
2277 #include <sys/types.h>
2278 #ifdef HAVE_SYS_FILE_H
2279 # include <sys/file.h>
2280 #endif
2281 #include <sys/stat.h>
2282
2283 #ifdef HAVE_UNISTD_H
2284 # include <unistd.h>
2285 #endif
2286
2287 #include <fcntl.h>
2288 #include <stdio.h>
2289 #include <errno.h>
2290
2291 #if defined (HAVE_STRING_H)
2292 # include <string.h>
2293 #else /* !HAVE_STRING_H */
2294 # include <strings.h>
2295 #endif /* !HAVE_STRING_H */
2296
2297 #ifdef HAVE_STDLIB_H
2298 # include <stdlib.h>
2299 #endif
2300
2301 #include <time.h>
2302
2303 #include <readline/readline.h>
2304 #include <readline/history.h>
2305
2306 extern char *xmalloc PARAMS((size_t));
2307
2308 /* The names of functions that actually do the manipulation. */
2309 int com_list PARAMS((char *));
2310 int com_view PARAMS((char *));
2311 int com_rename PARAMS((char *));
2312 int com_stat PARAMS((char *));
2313 int com_pwd PARAMS((char *));
2314 int com_delete PARAMS((char *));
2315 int com_help PARAMS((char *));
2316 int com_cd PARAMS((char *));
2317 int com_quit PARAMS((char *));
2318
2319 /* A structure which contains information on the commands this program
2320 can understand. */
2321
2322 typedef struct @{
2323 char *name; /* User printable name of the function. */
2324 rl_icpfunc_t *func; /* Function to call to do the job. */
2325 char *doc; /* Documentation for this function. */
2326 @} COMMAND;
2327
2328 COMMAND commands[] = @{
2329 @{ "cd", com_cd, "Change to directory DIR" @},
2330 @{ "delete", com_delete, "Delete FILE" @},
2331 @{ "help", com_help, "Display this text" @},
2332 @{ "?", com_help, "Synonym for `help'" @},
2333 @{ "list", com_list, "List files in DIR" @},
2334 @{ "ls", com_list, "Synonym for `list'" @},
2335 @{ "pwd", com_pwd, "Print the current working directory" @},
2336 @{ "quit", com_quit, "Quit using Fileman" @},
2337 @{ "rename", com_rename, "Rename FILE to NEWNAME" @},
2338 @{ "stat", com_stat, "Print out statistics on FILE" @},
2339 @{ "view", com_view, "View the contents of FILE" @},
2340 @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @}
2341 @};
2342
2343 /* Forward declarations. */
2344 char *stripwhite ();
2345 COMMAND *find_command ();
2346
2347 /* The name of this program, as taken from argv[0]. */
2348 char *progname;
2349
2350 /* When non-zero, this global means the user is done using this program. */
2351 int done;
2352
2353 char *
2354 dupstr (s)
2355 char *s;
2356 @{
2357 char *r;
2358
2359 r = xmalloc (strlen (s) + 1);
2360 strcpy (r, s);
2361 return (r);
2362 @}
2363
2364 main (argc, argv)
2365 int argc;
2366 char **argv;
2367 @{
2368 char *line, *s;
2369
2370 progname = argv[0];
2371
2372 initialize_readline (); /* Bind our completer. */
2373
2374 /* Loop reading and executing lines until the user quits. */
2375 for ( ; done == 0; )
2376 @{
2377 line = readline ("FileMan: ");
2378
2379 if (!line)
2380 break;
2381
2382 /* Remove leading and trailing whitespace from the line.
2383 Then, if there is anything left, add it to the history list
2384 and execute it. */
2385 s = stripwhite (line);
2386
2387 if (*s)
2388 @{
2389 add_history (s);
2390 execute_line (s);
2391 @}
2392
2393 free (line);
2394 @}
2395 exit (0);
2396 @}
2397
2398 /* Execute a command line. */
2399 int
2400 execute_line (line)
2401 char *line;
2402 @{
2403 register int i;
2404 COMMAND *command;
2405 char *word;
2406
2407 /* Isolate the command word. */
2408 i = 0;
2409 while (line[i] && whitespace (line[i]))
2410 i++;
2411 word = line + i;
2412
2413 while (line[i] && !whitespace (line[i]))
2414 i++;
2415
2416 if (line[i])
2417 line[i++] = '\0';
2418
2419 command = find_command (word);
2420
2421 if (!command)
2422 @{
2423 fprintf (stderr, "%s: No such command for FileMan.\n", word);
2424 return (-1);
2425 @}
2426
2427 /* Get argument to command, if any. */
2428 while (whitespace (line[i]))
2429 i++;
2430
2431 word = line + i;
2432
2433 /* Call the function. */
2434 return ((*(command->func)) (word));
2435 @}
2436
2437 /* Look up NAME as the name of a command, and return a pointer to that
2438 command. Return a NULL pointer if NAME isn't a command name. */
2439 COMMAND *
2440 find_command (name)
2441 char *name;
2442 @{
2443 register int i;
2444
2445 for (i = 0; commands[i].name; i++)
2446 if (strcmp (name, commands[i].name) == 0)
2447 return (&commands[i]);
2448
2449 return ((COMMAND *)NULL);
2450 @}
2451
2452 /* Strip whitespace from the start and end of STRING. Return a pointer
2453 into STRING. */
2454 char *
2455 stripwhite (string)
2456 char *string;
2457 @{
2458 register char *s, *t;
2459
2460 for (s = string; whitespace (*s); s++)
2461 ;
2462
2463 if (*s == 0)
2464 return (s);
2465
2466 t = s + strlen (s) - 1;
2467 while (t > s && whitespace (*t))
2468 t--;
2469 *++t = '\0';
2470
2471 return s;
2472 @}
2473
2474 /* **************************************************************** */
2475 /* */
2476 /* Interface to Readline Completion */
2477 /* */
2478 /* **************************************************************** */
2479
2480 char *command_generator PARAMS((const char *, int));
2481 char **fileman_completion PARAMS((const char *, int, int));
2482
2483 /* Tell the GNU Readline library how to complete. We want to try to complete
2484 on command names if this is the first word in the line, or on filenames
2485 if not. */
2486 initialize_readline ()
2487 @{
2488 /* Allow conditional parsing of the ~/.inputrc file. */
2489 rl_readline_name = "FileMan";
2490
2491 /* Tell the completer that we want a crack first. */
2492 rl_attempted_completion_function = fileman_completion;
2493 @}
2494
2495 /* Attempt to complete on the contents of TEXT. START and END bound the
2496 region of rl_line_buffer that contains the word to complete. TEXT is
2497 the word to complete. We can use the entire contents of rl_line_buffer
2498 in case we want to do some simple parsing. Return the array of matches,
2499 or NULL if there aren't any. */
2500 char **
2501 fileman_completion (text, start, end)
2502 const char *text;
2503 int start, end;
2504 @{
2505 char **matches;
2506
2507 matches = (char **)NULL;
2508
2509 /* If this word is at the start of the line, then it is a command
2510 to complete. Otherwise it is the name of a file in the current
2511 directory. */
2512 if (start == 0)
2513 matches = rl_completion_matches (text, command_generator);
2514
2515 return (matches);
2516 @}
2517
2518 /* Generator function for command completion. STATE lets us know whether
2519 to start from scratch; without any state (i.e. STATE == 0), then we
2520 start at the top of the list. */
2521 char *
2522 command_generator (text, state)
2523 const char *text;
2524 int state;
2525 @{
2526 static int list_index, len;
2527 char *name;
2528
2529 /* If this is a new word to complete, initialize now. This includes
2530 saving the length of TEXT for efficiency, and initializing the index
2531 variable to 0. */
2532 if (!state)
2533 @{
2534 list_index = 0;
2535 len = strlen (text);
2536 @}
2537
2538 /* Return the next name which partially matches from the command list. */
2539 while (name = commands[list_index].name)
2540 @{
2541 list_index++;
2542
2543 if (strncmp (name, text, len) == 0)
2544 return (dupstr(name));
2545 @}
2546
2547 /* If no names matched, then return NULL. */
2548 return ((char *)NULL);
2549 @}
2550
2551 /* **************************************************************** */
2552 /* */
2553 /* FileMan Commands */
2554 /* */
2555 /* **************************************************************** */
2556
2557 /* String to pass to system (). This is for the LIST, VIEW and RENAME
2558 commands. */
2559 static char syscom[1024];
2560
2561 /* List the file(s) named in arg. */
2562 com_list (arg)
2563 char *arg;
2564 @{
2565 if (!arg)
2566 arg = "";
2567
2568 sprintf (syscom, "ls -FClg %s", arg);
2569 return (system (syscom));
2570 @}
2571
2572 com_view (arg)
2573 char *arg;
2574 @{
2575 if (!valid_argument ("view", arg))
2576 return 1;
2577
2578 #if defined (__MSDOS__)
2579 /* more.com doesn't grok slashes in pathnames */
2580 sprintf (syscom, "less %s", arg);
2581 #else
2582 sprintf (syscom, "more %s", arg);
2583 #endif
2584 return (system (syscom));
2585 @}
2586
2587 com_rename (arg)
2588 char *arg;
2589 @{
2590 too_dangerous ("rename");
2591 return (1);
2592 @}
2593
2594 com_stat (arg)
2595 char *arg;
2596 @{
2597 struct stat finfo;
2598
2599 if (!valid_argument ("stat", arg))
2600 return (1);
2601
2602 if (stat (arg, &finfo) == -1)
2603 @{
2604 perror (arg);
2605 return (1);
2606 @}
2607
2608 printf ("Statistics for `%s':\n", arg);
2609
2610 printf ("%s has %d link%s, and is %d byte%s in length.\n",
2611 arg,
2612 finfo.st_nlink,
2613 (finfo.st_nlink == 1) ? "" : "s",
2614 finfo.st_size,
2615 (finfo.st_size == 1) ? "" : "s");
2616 printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
2617 printf (" Last access at: %s", ctime (&finfo.st_atime));
2618 printf (" Last modified at: %s", ctime (&finfo.st_mtime));
2619 return (0);
2620 @}
2621
2622 com_delete (arg)
2623 char *arg;
2624 @{
2625 too_dangerous ("delete");
2626 return (1);
2627 @}
2628
2629 /* Print out help for ARG, or for all of the commands if ARG is
2630 not present. */
2631 com_help (arg)
2632 char *arg;
2633 @{
2634 register int i;
2635 int printed = 0;
2636
2637 for (i = 0; commands[i].name; i++)
2638 @{
2639 if (!*arg || (strcmp (arg, commands[i].name) == 0))
2640 @{
2641 printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
2642 printed++;
2643 @}
2644 @}
2645
2646 if (!printed)
2647 @{
2648 printf ("No commands match `%s'. Possibilties are:\n", arg);
2649
2650 for (i = 0; commands[i].name; i++)
2651 @{
2652 /* Print in six columns. */
2653 if (printed == 6)
2654 @{
2655 printed = 0;
2656 printf ("\n");
2657 @}
2658
2659 printf ("%s\t", commands[i].name);
2660 printed++;
2661 @}
2662
2663 if (printed)
2664 printf ("\n");
2665 @}
2666 return (0);
2667 @}
2668
2669 /* Change to the directory ARG. */
2670 com_cd (arg)
2671 char *arg;
2672 @{
2673 if (chdir (arg) == -1)
2674 @{
2675 perror (arg);
2676 return 1;
2677 @}
2678
2679 com_pwd ("");
2680 return (0);
2681 @}
2682
2683 /* Print out the current working directory. */
2684 com_pwd (ignore)
2685 char *ignore;
2686 @{
2687 char dir[1024], *s;
2688
2689 s = getcwd (dir, sizeof(dir) - 1);
2690 if (s == 0)
2691 @{
2692 printf ("Error getting pwd: %s\n", dir);
2693 return 1;
2694 @}
2695
2696 printf ("Current directory is %s\n", dir);
2697 return 0;
2698 @}
2699
2700 /* The user wishes to quit using this program. Just set DONE non-zero. */
2701 com_quit (arg)
2702 char *arg;
2703 @{
2704 done = 1;
2705 return (0);
2706 @}
2707
2708 /* Function which tells you that you can't do this. */
2709 too_dangerous (caller)
2710 char *caller;
2711 @{
2712 fprintf (stderr,
2713 "%s: Too dangerous for me to distribute. Write it yourself.\n",
2714 caller);
2715 @}
2716
2717 /* Return non-zero if ARG is a valid argument for CALLER, else print
2718 an error message and return zero. */
2719 int
2720 valid_argument (caller, arg)
2721 char *caller, *arg;
2722 @{
2723 if (!arg || !*arg)
2724 @{
2725 fprintf (stderr, "%s: Argument required.\n", caller);
2726 return (0);
2727 @}
2728
2729 return (1);
2730 @}
2731 @end smallexample
This page took 0.099157 seconds and 4 git commands to generate.