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