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