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