1136644Sache@comment %**start of header (This is for running Texinfo on a region.) 2136644Sache@setfilename rltech.info 3136644Sache@comment %**end of header (This is for running Texinfo on a region.) 4136644Sache@setchapternewpage odd 5136644Sache 6136644Sache@ifinfo 7136644SacheThis document describes the GNU Readline Library, a utility for aiding 8157184Sachein the consistency of user interface across discrete programs that need 9136644Sacheto provide a command line interface. 10136644Sache 11165670SacheCopyright (C) 1988-2006 Free Software Foundation, Inc. 12136644Sache 13136644SachePermission is granted to make and distribute verbatim copies of 14136644Sachethis manual provided the copyright notice and this permission notice 15136644Sachepare preserved on all copies. 16136644Sache 17136644Sache@ignore 18136644SachePermission is granted to process this file through TeX and print the 19136644Sacheresults, provided the printed document carries copying permission 20136644Sachenotice identical to this one except for the removal of this paragraph 21136644Sache(this paragraph not being relevant to the printed manual). 22136644Sache@end ignore 23136644Sache 24136644SachePermission is granted to copy and distribute modified versions of this 25136644Sachemanual under the conditions for verbatim copying, provided that the entire 26136644Sacheresulting derived work is distributed under the terms of a permission 27136644Sachenotice identical to this one. 28136644Sache 29136644SachePermission is granted to copy and distribute translations of this manual 30136644Sacheinto another language, under the above conditions for modified versions, 31136644Sacheexcept that this permission notice may be stated in a translation approved 32136644Sacheby the Foundation. 33136644Sache@end ifinfo 34136644Sache 35136644Sache@node Programming with GNU Readline 36136644Sache@chapter Programming with GNU Readline 37136644Sache 38136644SacheThis chapter describes the interface between the @sc{gnu} Readline Library and 39136644Sacheother programs. If you are a programmer, and you wish to include the 40136644Sachefeatures found in @sc{gnu} Readline 41136644Sachesuch as completion, line editing, and interactive history manipulation 42136644Sachein your own programs, this section is for you. 43136644Sache 44136644Sache@menu 45136644Sache* Basic Behavior:: Using the default behavior of Readline. 46136644Sache* Custom Functions:: Adding your own functions to Readline. 47136644Sache* Readline Variables:: Variables accessible to custom 48136644Sache functions. 49136644Sache* Readline Convenience Functions:: Functions which Readline supplies to 50136644Sache aid in writing your own custom 51136644Sache functions. 52136644Sache* Readline Signal Handling:: How Readline behaves when it receives signals. 53136644Sache* Custom Completers:: Supplanting or supplementing Readline's 54136644Sache completion functions. 55136644Sache@end menu 56136644Sache 57136644Sache@node Basic Behavior 58136644Sache@section Basic Behavior 59136644Sache 60136644SacheMany programs provide a command line interface, such as @code{mail}, 61136644Sache@code{ftp}, and @code{sh}. For such programs, the default behaviour of 62136644SacheReadline is sufficient. This section describes how to use Readline in 63136644Sachethe simplest way possible, perhaps to replace calls in your code to 64136644Sache@code{gets()} or @code{fgets()}. 65136644Sache 66136644Sache@findex readline 67136644Sache@cindex readline, function 68136644Sache 69136644SacheThe function @code{readline()} prints a prompt @var{prompt} 70136644Sacheand then reads and returns a single line of text from the user. 71136644SacheIf @var{prompt} is @code{NULL} or the empty string, no prompt is displayed. 72136644SacheThe line @code{readline} returns is allocated with @code{malloc()}; 73136644Sachethe caller should @code{free()} the line when it has finished with it. 74136644SacheThe declaration for @code{readline} in ANSI C is 75136644Sache 76136644Sache@example 77136644Sache@code{char *readline (const char *@var{prompt});} 78136644Sache@end example 79136644Sache 80136644Sache@noindent 81136644SacheSo, one might say 82136644Sache@example 83136644Sache@code{char *line = readline ("Enter a line: ");} 84136644Sache@end example 85136644Sache@noindent 86136644Sachein order to read a line of text from the user. 87136644SacheThe line returned has the final newline removed, so only the 88136644Sachetext remains. 89136644Sache 90136644SacheIf @code{readline} encounters an @code{EOF} while reading the line, and the 91136644Sacheline is empty at that point, then @code{(char *)NULL} is returned. 92136644SacheOtherwise, the line is ended just as if a newline had been typed. 93136644Sache 94136644SacheIf you want the user to be able to get at the line later, (with 95136644Sache@key{C-p} for example), you must call @code{add_history()} to save the 96136644Sacheline away in a @dfn{history} list of such lines. 97136644Sache 98136644Sache@example 99136644Sache@code{add_history (line)}; 100136644Sache@end example 101136644Sache 102136644Sache@noindent 103136644SacheFor full details on the GNU History Library, see the associated manual. 104136644Sache 105136644SacheIt is preferable to avoid saving empty lines on the history list, since 106136644Sacheusers rarely have a burning need to reuse a blank line. Here is 107136644Sachea function which usefully replaces the standard @code{gets()} library 108136644Sachefunction, and has the advantage of no static buffer to overflow: 109136644Sache 110136644Sache@example 111136644Sache/* A static variable for holding the line. */ 112136644Sachestatic char *line_read = (char *)NULL; 113136644Sache 114136644Sache/* Read a string, and return a pointer to it. 115136644Sache Returns NULL on EOF. */ 116136644Sachechar * 117136644Sacherl_gets () 118136644Sache@{ 119136644Sache /* If the buffer has already been allocated, 120136644Sache return the memory to the free pool. */ 121136644Sache if (line_read) 122136644Sache @{ 123136644Sache free (line_read); 124136644Sache line_read = (char *)NULL; 125136644Sache @} 126136644Sache 127136644Sache /* Get a line from the user. */ 128136644Sache line_read = readline (""); 129136644Sache 130136644Sache /* If the line has any text in it, 131136644Sache save it on the history. */ 132136644Sache if (line_read && *line_read) 133136644Sache add_history (line_read); 134136644Sache 135136644Sache return (line_read); 136136644Sache@} 137136644Sache@end example 138136644Sache 139136644SacheThis function gives the user the default behaviour of @key{TAB} 140136644Sachecompletion: completion on file names. If you do not want Readline to 141136644Sachecomplete on filenames, you can change the binding of the @key{TAB} key 142136644Sachewith @code{rl_bind_key()}. 143136644Sache 144136644Sache@example 145136644Sache@code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});} 146136644Sache@end example 147136644Sache 148136644Sache@code{rl_bind_key()} takes two arguments: @var{key} is the character that 149136644Sacheyou want to bind, and @var{function} is the address of the function to 150136644Sachecall when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert()} 151136644Sachemakes @key{TAB} insert itself. 152136644Sache@code{rl_bind_key()} returns non-zero if @var{key} is not a valid 153136644SacheASCII character code (between 0 and 255). 154136644Sache 155136644SacheThus, to disable the default @key{TAB} behavior, the following suffices: 156136644Sache@example 157136644Sache@code{rl_bind_key ('\t', rl_insert);} 158136644Sache@end example 159136644Sache 160136644SacheThis code should be executed once at the start of your program; you 161136644Sachemight write a function called @code{initialize_readline()} which 162136644Sacheperforms this and other desired initializations, such as installing 163136644Sachecustom completers (@pxref{Custom Completers}). 164136644Sache 165136644Sache@node Custom Functions 166136644Sache@section Custom Functions 167136644Sache 168136644SacheReadline provides many functions for manipulating the text of 169136644Sachethe line, but it isn't possible to anticipate the needs of all 170136644Sacheprograms. This section describes the various functions and variables 171136644Sachedefined within the Readline library which allow a user program to add 172136644Sachecustomized functionality to Readline. 173136644Sache 174136644SacheBefore declaring any functions that customize Readline's behavior, or 175136644Sacheusing any functionality Readline provides in other code, an 176136644Sacheapplication writer should include the file @code{<readline/readline.h>} 177136644Sachein any file that uses Readline's features. Since some of the definitions 178136644Sachein @code{readline.h} use the @code{stdio} library, the file 179136644Sache@code{<stdio.h>} should be included before @code{readline.h}. 180136644Sache 181136644Sache@code{readline.h} defines a C preprocessor variable that should 182136644Sachebe treated as an integer, @code{RL_READLINE_VERSION}, which may 183136644Sachebe used to conditionally compile application code depending on 184136644Sachethe installed Readline version. The value is a hexadecimal 185136644Sacheencoding of the major and minor version numbers of the library, 186136644Sacheof the form 0x@var{MMmm}. @var{MM} is the two-digit major 187136644Sacheversion number; @var{mm} is the two-digit minor version number. 188136644SacheFor Readline 4.2, for example, the value of 189136644Sache@code{RL_READLINE_VERSION} would be @code{0x0402}. 190136644Sache 191136644Sache@menu 192136644Sache* Readline Typedefs:: C declarations to make code readable. 193136644Sache* Function Writing:: Variables and calling conventions. 194136644Sache@end menu 195136644Sache 196136644Sache@node Readline Typedefs 197136644Sache@subsection Readline Typedefs 198136644Sache 199136644SacheFor readabilty, we declare a number of new object types, all pointers 200136644Sacheto functions. 201136644Sache 202136644SacheThe reason for declaring these new types is to make it easier to write 203136644Sachecode describing pointers to C functions with appropriately prototyped 204136644Sachearguments and return values. 205136644Sache 206136644SacheFor instance, say we want to declare a variable @var{func} as a pointer 207136644Sacheto a function which takes two @code{int} arguments and returns an 208136644Sache@code{int} (this is the type of all of the Readline bindable functions). 209136644SacheInstead of the classic C declaration 210136644Sache 211136644Sache@code{int (*func)();} 212136644Sache 213136644Sache@noindent 214136644Sacheor the ANSI-C style declaration 215136644Sache 216136644Sache@code{int (*func)(int, int);} 217136644Sache 218136644Sache@noindent 219136644Sachewe may write 220136644Sache 221136644Sache@code{rl_command_func_t *func;} 222136644Sache 223136644SacheThe full list of function pointer types available is 224136644Sache 225136644Sache@table @code 226136644Sache@item typedef int rl_command_func_t (int, int); 227136644Sache 228136644Sache@item typedef char *rl_compentry_func_t (const char *, int); 229136644Sache 230136644Sache@item typedef char **rl_completion_func_t (const char *, int, int); 231136644Sache 232136644Sache@item typedef char *rl_quote_func_t (char *, int, char *); 233136644Sache 234136644Sache@item typedef char *rl_dequote_func_t (char *, int); 235136644Sache 236136644Sache@item typedef int rl_compignore_func_t (char **); 237136644Sache 238136644Sache@item typedef void rl_compdisp_func_t (char **, int, int); 239136644Sache 240136644Sache@item typedef int rl_hook_func_t (void); 241136644Sache 242136644Sache@item typedef int rl_getc_func_t (FILE *); 243136644Sache 244136644Sache@item typedef int rl_linebuf_func_t (char *, int); 245136644Sache 246136644Sache@item typedef int rl_intfunc_t (int); 247136644Sache@item #define rl_ivoidfunc_t rl_hook_func_t 248136644Sache@item typedef int rl_icpfunc_t (char *); 249136644Sache@item typedef int rl_icppfunc_t (char **); 250136644Sache 251136644Sache@item typedef void rl_voidfunc_t (void); 252136644Sache@item typedef void rl_vintfunc_t (int); 253136644Sache@item typedef void rl_vcpfunc_t (char *); 254136644Sache@item typedef void rl_vcppfunc_t (char **); 255136644Sache 256136644Sache@end table 257136644Sache 258136644Sache@node Function Writing 259136644Sache@subsection Writing a New Function 260136644Sache 261136644SacheIn order to write new functions for Readline, you need to know the 262136644Sachecalling conventions for keyboard-invoked functions, and the names of the 263136644Sachevariables that describe the current state of the line read so far. 264136644Sache 265136644SacheThe calling sequence for a command @code{foo} looks like 266136644Sache 267136644Sache@example 268136644Sache@code{int foo (int count, int key)} 269136644Sache@end example 270136644Sache 271136644Sache@noindent 272136644Sachewhere @var{count} is the numeric argument (or 1 if defaulted) and 273136644Sache@var{key} is the key that invoked this function. 274136644Sache 275136644SacheIt is completely up to the function as to what should be done with the 276136644Sachenumeric argument. Some functions use it as a repeat count, some 277136644Sacheas a flag, and others to choose alternate behavior (refreshing the current 278136644Sacheline as opposed to refreshing the screen, for example). Some choose to 279136644Sacheignore it. In general, if a 280136644Sachefunction uses the numeric argument as a repeat count, it should be able 281136644Sacheto do something useful with both negative and positive arguments. 282136644SacheAt the very least, it should be aware that it can be passed a 283136644Sachenegative argument. 284136644Sache 285136644SacheA command function should return 0 if its action completes successfully, 286136644Sacheand a non-zero value if some error occurs. 287157184SacheThis is the convention obeyed by all of the builtin Readline bindable 288157184Sachecommand functions. 289136644Sache 290136644Sache@node Readline Variables 291136644Sache@section Readline Variables 292136644Sache 293136644SacheThese variables are available to function writers. 294136644Sache 295136644Sache@deftypevar {char *} rl_line_buffer 296136644SacheThis is the line gathered so far. You are welcome to modify the 297136644Sachecontents of the line, but see @ref{Allowing Undoing}. The 298136644Sachefunction @code{rl_extend_line_buffer} is available to increase 299136644Sachethe memory allocated to @code{rl_line_buffer}. 300136644Sache@end deftypevar 301136644Sache 302136644Sache@deftypevar int rl_point 303136644SacheThe offset of the current cursor position in @code{rl_line_buffer} 304136644Sache(the @emph{point}). 305136644Sache@end deftypevar 306136644Sache 307136644Sache@deftypevar int rl_end 308136644SacheThe number of characters present in @code{rl_line_buffer}. When 309136644Sache@code{rl_point} is at the end of the line, @code{rl_point} and 310136644Sache@code{rl_end} are equal. 311136644Sache@end deftypevar 312136644Sache 313136644Sache@deftypevar int rl_mark 314136644SacheThe @var{mark} (saved position) in the current line. If set, the mark 315136644Sacheand point define a @emph{region}. 316136644Sache@end deftypevar 317136644Sache 318136644Sache@deftypevar int rl_done 319136644SacheSetting this to a non-zero value causes Readline to return the current 320136644Sacheline immediately. 321136644Sache@end deftypevar 322136644Sache 323136644Sache@deftypevar int rl_num_chars_to_read 324136644SacheSetting this to a positive value before calling @code{readline()} causes 325136644SacheReadline to return after accepting that many characters, rather 326136644Sachethan reading up to a character bound to @code{accept-line}. 327136644Sache@end deftypevar 328136644Sache 329136644Sache@deftypevar int rl_pending_input 330136644SacheSetting this to a value makes it the next keystroke read. This is a 331136644Sacheway to stuff a single character into the input stream. 332136644Sache@end deftypevar 333136644Sache 334136644Sache@deftypevar int rl_dispatching 335136644SacheSet to a non-zero value if a function is being called from a key binding; 336136644Sachezero otherwise. Application functions can test this to discover whether 337136644Sachethey were called directly or by Readline's dispatching mechanism. 338136644Sache@end deftypevar 339136644Sache 340136644Sache@deftypevar int rl_erase_empty_line 341136644SacheSetting this to a non-zero value causes Readline to completely erase 342136644Sachethe current line, including any prompt, any time a newline is typed as 343136644Sachethe only character on an otherwise-empty line. The cursor is moved to 344136644Sachethe beginning of the newly-blank line. 345136644Sache@end deftypevar 346136644Sache 347136644Sache@deftypevar {char *} rl_prompt 348136644SacheThe prompt Readline uses. This is set from the argument to 349136644Sache@code{readline()}, and should not be assigned to directly. 350136644SacheThe @code{rl_set_prompt()} function (@pxref{Redisplay}) may 351136644Sachebe used to modify the prompt string after calling @code{readline()}. 352136644Sache@end deftypevar 353136644Sache 354136644Sache@deftypevar int rl_already_prompted 355136644SacheIf an application wishes to display the prompt itself, rather than have 356136644SacheReadline do it the first time @code{readline()} is called, it should set 357136644Sachethis variable to a non-zero value after displaying the prompt. 358136644SacheThe prompt must also be passed as the argument to @code{readline()} so 359136644Sachethe redisplay functions can update the display properly. 360136644SacheThe calling application is responsible for managing the value; Readline 361136644Sachenever sets it. 362136644Sache@end deftypevar 363136644Sache 364136644Sache@deftypevar {const char *} rl_library_version 365136644SacheThe version number of this revision of the library. 366136644Sache@end deftypevar 367136644Sache 368136644Sache@deftypevar int rl_readline_version 369136644SacheAn integer encoding the current version of the library. The encoding is 370136644Sacheof the form 0x@var{MMmm}, where @var{MM} is the two-digit major version 371136644Sachenumber, and @var{mm} is the two-digit minor version number. 372136644SacheFor example, for Readline-4.2, @code{rl_readline_version} would have the 373136644Sachevalue 0x0402. 374136644Sache@end deftypevar 375136644Sache 376136644Sache@deftypevar {int} rl_gnu_readline_p 377136644SacheAlways set to 1, denoting that this is @sc{gnu} readline rather than some 378136644Sacheemulation. 379136644Sache@end deftypevar 380136644Sache 381136644Sache@deftypevar {const char *} rl_terminal_name 382136644SacheThe terminal type, used for initialization. If not set by the application, 383136644SacheReadline sets this to the value of the @env{TERM} environment variable 384136644Sachethe first time it is called. 385136644Sache@end deftypevar 386136644Sache 387136644Sache@deftypevar {const char *} rl_readline_name 388136644SacheThis variable is set to a unique name by each application using Readline. 389136644SacheThe value allows conditional parsing of the inputrc file 390136644Sache(@pxref{Conditional Init Constructs}). 391136644Sache@end deftypevar 392136644Sache 393136644Sache@deftypevar {FILE *} rl_instream 394136644SacheThe stdio stream from which Readline reads input. 395136644SacheIf @code{NULL}, Readline defaults to @var{stdin}. 396136644Sache@end deftypevar 397136644Sache 398136644Sache@deftypevar {FILE *} rl_outstream 399136644SacheThe stdio stream to which Readline performs output. 400136644SacheIf @code{NULL}, Readline defaults to @var{stdout}. 401136644Sache@end deftypevar 402136644Sache 403157184Sache@deftypevar int rl_prefer_env_winsize 404157184SacheIf non-zero, Readline gives values found in the @env{LINES} and 405157184Sache@env{COLUMNS} environment variables greater precedence than values fetched 406157184Sachefrom the kernel when computing the screen dimensions. 407157184Sache@end deftypevar 408157184Sache 409136644Sache@deftypevar {rl_command_func_t *} rl_last_func 410136644SacheThe address of the last command function Readline executed. May be used to 411136644Sachetest whether or not a function is being executed twice in succession, for 412136644Sacheexample. 413136644Sache@end deftypevar 414136644Sache 415136644Sache@deftypevar {rl_hook_func_t *} rl_startup_hook 416136644SacheIf non-zero, this is the address of a function to call just 417136644Sachebefore @code{readline} prints the first prompt. 418136644Sache@end deftypevar 419136644Sache 420136644Sache@deftypevar {rl_hook_func_t *} rl_pre_input_hook 421136644SacheIf non-zero, this is the address of a function to call after 422136644Sachethe first prompt has been printed and just before @code{readline} 423136644Sachestarts reading input characters. 424136644Sache@end deftypevar 425136644Sache 426136644Sache@deftypevar {rl_hook_func_t *} rl_event_hook 427136644SacheIf non-zero, this is the address of a function to call periodically 428136644Sachewhen Readline is waiting for terminal input. 429136644SacheBy default, this will be called at most ten times a second if there 430136644Sacheis no keyboard input. 431136644Sache@end deftypevar 432136644Sache 433136644Sache@deftypevar {rl_getc_func_t *} rl_getc_function 434136644SacheIf non-zero, Readline will call indirectly through this pointer 435136644Sacheto get a character from the input stream. By default, it is set to 436136644Sache@code{rl_getc}, the default Readline character input function 437136644Sache(@pxref{Character Input}). 438136644Sache@end deftypevar 439136644Sache 440136644Sache@deftypevar {rl_voidfunc_t *} rl_redisplay_function 441136644SacheIf non-zero, Readline will call indirectly through this pointer 442136644Sacheto update the display with the current contents of the editing buffer. 443136644SacheBy default, it is set to @code{rl_redisplay}, the default Readline 444136644Sacheredisplay function (@pxref{Redisplay}). 445136644Sache@end deftypevar 446136644Sache 447136644Sache@deftypevar {rl_vintfunc_t *} rl_prep_term_function 448136644SacheIf non-zero, Readline will call indirectly through this pointer 449136644Sacheto initialize the terminal. The function takes a single argument, an 450136644Sache@code{int} flag that says whether or not to use eight-bit characters. 451136644SacheBy default, this is set to @code{rl_prep_terminal} 452136644Sache(@pxref{Terminal Management}). 453136644Sache@end deftypevar 454136644Sache 455136644Sache@deftypevar {rl_voidfunc_t *} rl_deprep_term_function 456136644SacheIf non-zero, Readline will call indirectly through this pointer 457136644Sacheto reset the terminal. This function should undo the effects of 458136644Sache@code{rl_prep_term_function}. 459136644SacheBy default, this is set to @code{rl_deprep_terminal} 460136644Sache(@pxref{Terminal Management}). 461136644Sache@end deftypevar 462136644Sache 463136644Sache@deftypevar {Keymap} rl_executing_keymap 464136644SacheThis variable is set to the keymap (@pxref{Keymaps}) in which the 465136644Sachecurrently executing readline function was found. 466136644Sache@end deftypevar 467136644Sache 468136644Sache@deftypevar {Keymap} rl_binding_keymap 469136644SacheThis variable is set to the keymap (@pxref{Keymaps}) in which the 470136644Sachelast key binding occurred. 471136644Sache@end deftypevar 472136644Sache 473136644Sache@deftypevar {char *} rl_executing_macro 474136644SacheThis variable is set to the text of any currently-executing macro. 475136644Sache@end deftypevar 476136644Sache 477136644Sache@deftypevar {int} rl_readline_state 478136644SacheA variable with bit values that encapsulate the current Readline state. 479136644SacheA bit is set with the @code{RL_SETSTATE} macro, and unset with the 480136644Sache@code{RL_UNSETSTATE} macro. Use the @code{RL_ISSTATE} macro to test 481136644Sachewhether a particular state bit is set. Current state bits include: 482136644Sache 483136644Sache@table @code 484136644Sache@item RL_STATE_NONE 485136644SacheReadline has not yet been called, nor has it begun to intialize. 486136644Sache@item RL_STATE_INITIALIZING 487136644SacheReadline is initializing its internal data structures. 488136644Sache@item RL_STATE_INITIALIZED 489136644SacheReadline has completed its initialization. 490136644Sache@item RL_STATE_TERMPREPPED 491136644SacheReadline has modified the terminal modes to do its own input and redisplay. 492136644Sache@item RL_STATE_READCMD 493136644SacheReadline is reading a command from the keyboard. 494136644Sache@item RL_STATE_METANEXT 495136644SacheReadline is reading more input after reading the meta-prefix character. 496136644Sache@item RL_STATE_DISPATCHING 497136644SacheReadline is dispatching to a command. 498136644Sache@item RL_STATE_MOREINPUT 499136644SacheReadline is reading more input while executing an editing command. 500136644Sache@item RL_STATE_ISEARCH 501136644SacheReadline is performing an incremental history search. 502136644Sache@item RL_STATE_NSEARCH 503136644SacheReadline is performing a non-incremental history search. 504136644Sache@item RL_STATE_SEARCH 505136644SacheReadline is searching backward or forward through the history for a string. 506136644Sache@item RL_STATE_NUMERICARG 507136644SacheReadline is reading a numeric argument. 508136644Sache@item RL_STATE_MACROINPUT 509136644SacheReadline is currently getting its input from a previously-defined keyboard 510136644Sachemacro. 511136644Sache@item RL_STATE_MACRODEF 512136644SacheReadline is currently reading characters defining a keyboard macro. 513136644Sache@item RL_STATE_OVERWRITE 514136644SacheReadline is in overwrite mode. 515136644Sache@item RL_STATE_COMPLETING 516136644SacheReadline is performing word completion. 517136644Sache@item RL_STATE_SIGHANDLER 518136644SacheReadline is currently executing the readline signal handler. 519136644Sache@item RL_STATE_UNDOING 520136644SacheReadline is performing an undo. 521136644Sache@item RL_STATE_DONE 522136644SacheReadline has read a key sequence bound to @code{accept-line} 523136644Sacheand is about to return the line to the caller. 524136644Sache@end table 525136644Sache 526136644Sache@end deftypevar 527136644Sache 528136644Sache@deftypevar {int} rl_explicit_arg 529136644SacheSet to a non-zero value if an explicit numeric argument was specified by 530136644Sachethe user. Only valid in a bindable command function. 531136644Sache@end deftypevar 532136644Sache 533136644Sache@deftypevar {int} rl_numeric_arg 534136644SacheSet to the value of any numeric argument explicitly specified by the user 535136644Sachebefore executing the current Readline function. Only valid in a bindable 536136644Sachecommand function. 537136644Sache@end deftypevar 538136644Sache 539136644Sache@deftypevar {int} rl_editing_mode 540136644SacheSet to a value denoting Readline's current editing mode. A value of 541136644Sache@var{1} means Readline is currently in emacs mode; @var{0} 542136644Sachemeans that vi mode is active. 543136644Sache@end deftypevar 544136644Sache 545136644Sache 546136644Sache@node Readline Convenience Functions 547136644Sache@section Readline Convenience Functions 548136644Sache 549136644Sache@menu 550136644Sache* Function Naming:: How to give a function you write a name. 551136644Sache* Keymaps:: Making keymaps. 552136644Sache* Binding Keys:: Changing Keymaps. 553136644Sache* Associating Function Names and Bindings:: Translate function names to 554136644Sache key sequences. 555136644Sache* Allowing Undoing:: How to make your functions undoable. 556136644Sache* Redisplay:: Functions to control line display. 557136644Sache* Modifying Text:: Functions to modify @code{rl_line_buffer}. 558136644Sache* Character Input:: Functions to read keyboard input. 559136644Sache* Terminal Management:: Functions to manage terminal settings. 560136644Sache* Utility Functions:: Generally useful functions and hooks. 561136644Sache* Miscellaneous Functions:: Functions that don't fall into any category. 562136644Sache* Alternate Interface:: Using Readline in a `callback' fashion. 563136644Sache* A Readline Example:: An example Readline function. 564136644Sache@end menu 565136644Sache 566136644Sache@node Function Naming 567136644Sache@subsection Naming a Function 568136644Sache 569136644SacheThe user can dynamically change the bindings of keys while using 570136644SacheReadline. This is done by representing the function with a descriptive 571136644Sachename. The user is able to type the descriptive name when referring to 572136644Sachethe function. Thus, in an init file, one might find 573136644Sache 574136644Sache@example 575136644SacheMeta-Rubout: backward-kill-word 576136644Sache@end example 577136644Sache 578136644SacheThis binds the keystroke @key{Meta-Rubout} to the function 579136644Sache@emph{descriptively} named @code{backward-kill-word}. You, as the 580136644Sacheprogrammer, should bind the functions you write to descriptive names as 581136644Sachewell. Readline provides a function for doing that: 582136644Sache 583136644Sache@deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key) 584136644SacheAdd @var{name} to the list of named functions. Make @var{function} be 585136644Sachethe function that gets called. If @var{key} is not -1, then bind it to 586136644Sache@var{function} using @code{rl_bind_key()}. 587136644Sache@end deftypefun 588136644Sache 589136644SacheUsing this function alone is sufficient for most applications. 590136644SacheIt is the recommended way to add a few functions to the default 591136644Sachefunctions that Readline has built in. 592136644SacheIf you need to do something other than adding a function to Readline, 593136644Sacheyou may need to use the underlying functions described below. 594136644Sache 595136644Sache@node Keymaps 596136644Sache@subsection Selecting a Keymap 597136644Sache 598136644SacheKey bindings take place on a @dfn{keymap}. The keymap is the 599136644Sacheassociation between the keys that the user types and the functions that 600136644Sacheget run. You can make your own keymaps, copy existing keymaps, and tell 601136644SacheReadline which keymap to use. 602136644Sache 603136644Sache@deftypefun Keymap rl_make_bare_keymap (void) 604136644SacheReturns a new, empty keymap. The space for the keymap is allocated with 605136644Sache@code{malloc()}; the caller should free it by calling 606136644Sache@code{rl_discard_keymap()} when done. 607136644Sache@end deftypefun 608136644Sache 609136644Sache@deftypefun Keymap rl_copy_keymap (Keymap map) 610136644SacheReturn a new keymap which is a copy of @var{map}. 611136644Sache@end deftypefun 612136644Sache 613136644Sache@deftypefun Keymap rl_make_keymap (void) 614136644SacheReturn a new keymap with the printing characters bound to rl_insert, 615136644Sachethe lowercase Meta characters bound to run their equivalents, and 616136644Sachethe Meta digits bound to produce numeric arguments. 617136644Sache@end deftypefun 618136644Sache 619136644Sache@deftypefun void rl_discard_keymap (Keymap keymap) 620136644SacheFree the storage associated with @var{keymap}. 621136644Sache@end deftypefun 622136644Sache 623136644SacheReadline has several internal keymaps. These functions allow you to 624136644Sachechange which keymap is active. 625136644Sache 626136644Sache@deftypefun Keymap rl_get_keymap (void) 627136644SacheReturns the currently active keymap. 628136644Sache@end deftypefun 629136644Sache 630136644Sache@deftypefun void rl_set_keymap (Keymap keymap) 631136644SacheMakes @var{keymap} the currently active keymap. 632136644Sache@end deftypefun 633136644Sache 634136644Sache@deftypefun Keymap rl_get_keymap_by_name (const char *name) 635136644SacheReturn the keymap matching @var{name}. @var{name} is one which would 636136644Sachebe supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}). 637136644Sache@end deftypefun 638136644Sache 639136644Sache@deftypefun {char *} rl_get_keymap_name (Keymap keymap) 640136644SacheReturn the name matching @var{keymap}. @var{name} is one which would 641136644Sachebe supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}). 642136644Sache@end deftypefun 643136644Sache 644136644Sache@node Binding Keys 645136644Sache@subsection Binding Keys 646136644Sache 647136644SacheKey sequences are associate with functions through the keymap. 648136644SacheReadline has several internal keymaps: @code{emacs_standard_keymap}, 649136644Sache@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap}, 650136644Sache@code{vi_movement_keymap}, and @code{vi_insertion_keymap}. 651136644Sache@code{emacs_standard_keymap} is the default, and the examples in 652136644Sachethis manual assume that. 653136644Sache 654136644SacheSince @code{readline()} installs a set of default key bindings the first 655136644Sachetime it is called, there is always the danger that a custom binding 656136644Sacheinstalled before the first call to @code{readline()} will be overridden. 657136644SacheAn alternate mechanism is to install custom key bindings in an 658136644Sacheinitialization function assigned to the @code{rl_startup_hook} variable 659136644Sache(@pxref{Readline Variables}). 660136644Sache 661136644SacheThese functions manage key bindings. 662136644Sache 663136644Sache@deftypefun int rl_bind_key (int key, rl_command_func_t *function) 664136644SacheBinds @var{key} to @var{function} in the currently active keymap. 665136644SacheReturns non-zero in the case of an invalid @var{key}. 666136644Sache@end deftypefun 667136644Sache 668136644Sache@deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map) 669136644SacheBind @var{key} to @var{function} in @var{map}. 670136644SacheReturns non-zero in the case of an invalid @var{key}. 671136644Sache@end deftypefun 672136644Sache 673136644Sache@deftypefun int rl_bind_key_if_unbound (int key, rl_command_func_t *function) 674136644SacheBinds @var{key} to @var{function} if it is not already bound in the 675136644Sachecurrently active keymap. 676136644SacheReturns non-zero in the case of an invalid @var{key} or if @var{key} is 677136644Sachealready bound. 678136644Sache@end deftypefun 679136644Sache 680136644Sache@deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map) 681136644SacheBinds @var{key} to @var{function} if it is not already bound in @var{map}. 682136644SacheReturns non-zero in the case of an invalid @var{key} or if @var{key} is 683136644Sachealready bound. 684136644Sache@end deftypefun 685136644Sache 686136644Sache@deftypefun int rl_unbind_key (int key) 687136644SacheBind @var{key} to the null function in the currently active keymap. 688136644SacheReturns non-zero in case of error. 689136644Sache@end deftypefun 690136644Sache 691136644Sache@deftypefun int rl_unbind_key_in_map (int key, Keymap map) 692136644SacheBind @var{key} to the null function in @var{map}. 693136644SacheReturns non-zero in case of error. 694136644Sache@end deftypefun 695136644Sache 696136644Sache@deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map) 697136644SacheUnbind all keys that execute @var{function} in @var{map}. 698136644Sache@end deftypefun 699136644Sache 700136644Sache@deftypefun int rl_unbind_command_in_map (const char *command, Keymap map) 701136644SacheUnbind all keys that are bound to @var{command} in @var{map}. 702136644Sache@end deftypefun 703136644Sache 704136644Sache@deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function) 705136644SacheBind the key sequence represented by the string @var{keyseq} to the function 706136644Sache@var{function}, beginning in the current keymap. 707136644SacheThis makes new keymaps as necessary. 708136644SacheThe return value is non-zero if @var{keyseq} is invalid. 709136644Sache@end deftypefun 710136644Sache 711136644Sache@deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map) 712136644SacheBind the key sequence represented by the string @var{keyseq} to the function 713136644Sache@var{function}. This makes new keymaps as necessary. 714136644SacheInitial bindings are performed in @var{map}. 715136644SacheThe return value is non-zero if @var{keyseq} is invalid. 716136644Sache@end deftypefun 717136644Sache 718136644Sache@deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map) 719136644SacheEquivalent to @code{rl_bind_keyseq_in_map}. 720136644Sache@end deftypefun 721136644Sache 722136644Sache@deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function) 723136644SacheBinds @var{keyseq} to @var{function} if it is not already bound in the 724136644Sachecurrently active keymap. 725136644SacheReturns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is 726136644Sachealready bound. 727136644Sache@end deftypefun 728136644Sache 729136644Sache@deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map) 730136644SacheBinds @var{keyseq} to @var{function} if it is not already bound in @var{map}. 731136644SacheReturns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is 732136644Sachealready bound. 733136644Sache@end deftypefun 734136644Sache 735136644Sache@deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map) 736136644SacheBind the key sequence represented by the string @var{keyseq} to the arbitrary 737136644Sachepointer @var{data}. @var{type} says what kind of data is pointed to by 738136644Sache@var{data}; this can be a function (@code{ISFUNC}), a macro 739136644Sache(@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as 740136644Sachenecessary. The initial keymap in which to do bindings is @var{map}. 741136644Sache@end deftypefun 742136644Sache 743136644Sache@deftypefun int rl_parse_and_bind (char *line) 744136644SacheParse @var{line} as if it had been read from the @code{inputrc} file and 745136644Sacheperform any key bindings and variable assignments found 746136644Sache(@pxref{Readline Init File}). 747136644Sache@end deftypefun 748136644Sache 749136644Sache@deftypefun int rl_read_init_file (const char *filename) 750136644SacheRead keybindings and variable assignments from @var{filename} 751136644Sache(@pxref{Readline Init File}). 752136644Sache@end deftypefun 753136644Sache 754136644Sache@node Associating Function Names and Bindings 755136644Sache@subsection Associating Function Names and Bindings 756136644Sache 757136644SacheThese functions allow you to find out what keys invoke named functions 758136644Sacheand the functions invoked by a particular key sequence. You may also 759136644Sacheassociate a new function name with an arbitrary function. 760136644Sache 761136644Sache@deftypefun {rl_command_func_t *} rl_named_function (const char *name) 762136644SacheReturn the function with name @var{name}. 763136644Sache@end deftypefun 764136644Sache 765136644Sache@deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type) 766136644SacheReturn the function invoked by @var{keyseq} in keymap @var{map}. 767136644SacheIf @var{map} is @code{NULL}, the current keymap is used. If @var{type} is 768136644Sachenot @code{NULL}, the type of the object is returned in the @code{int} variable 769136644Sacheit points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}). 770136644Sache@end deftypefun 771136644Sache 772136644Sache@deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function) 773136644SacheReturn an array of strings representing the key sequences used to 774136644Sacheinvoke @var{function} in the current keymap. 775136644Sache@end deftypefun 776136644Sache 777136644Sache@deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map) 778136644SacheReturn an array of strings representing the key sequences used to 779136644Sacheinvoke @var{function} in the keymap @var{map}. 780136644Sache@end deftypefun 781136644Sache 782136644Sache@deftypefun void rl_function_dumper (int readable) 783136644SachePrint the readline function names and the key sequences currently 784136644Sachebound to them to @code{rl_outstream}. If @var{readable} is non-zero, 785136644Sachethe list is formatted in such a way that it can be made part of an 786136644Sache@code{inputrc} file and re-read. 787136644Sache@end deftypefun 788136644Sache 789136644Sache@deftypefun void rl_list_funmap_names (void) 790136644SachePrint the names of all bindable Readline functions to @code{rl_outstream}. 791136644Sache@end deftypefun 792136644Sache 793136644Sache@deftypefun {const char **} rl_funmap_names (void) 794136644SacheReturn a NULL terminated array of known function names. The array is 795136644Sachesorted. The array itself is allocated, but not the strings inside. You 796136644Sacheshould @code{free()} the array when you are done, but not the pointers. 797136644Sache@end deftypefun 798136644Sache 799136644Sache@deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function) 800136644SacheAdd @var{name} to the list of bindable Readline command names, and make 801136644Sache@var{function} the function to be called when @var{name} is invoked. 802136644Sache@end deftypefun 803136644Sache 804136644Sache@node Allowing Undoing 805136644Sache@subsection Allowing Undoing 806136644Sache 807136644SacheSupporting the undo command is a painless thing, and makes your 808136644Sachefunctions much more useful. It is certainly easy to try 809136644Sachesomething if you know you can undo it. 810136644Sache 811136644SacheIf your function simply inserts text once, or deletes text once, and 812136644Sacheuses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then 813136644Sacheundoing is already done for you automatically. 814136644Sache 815136644SacheIf you do multiple insertions or multiple deletions, or any combination 816136644Sacheof these operations, you should group them together into one operation. 817136644SacheThis is done with @code{rl_begin_undo_group()} and 818136644Sache@code{rl_end_undo_group()}. 819136644Sache 820136644SacheThe types of events that can be undone are: 821136644Sache 822136644Sache@smallexample 823136644Sacheenum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @}; 824136644Sache@end smallexample 825136644Sache 826136644SacheNotice that @code{UNDO_DELETE} means to insert some text, and 827136644Sache@code{UNDO_INSERT} means to delete some text. That is, the undo code 828136644Sachetells what to undo, not how to undo it. @code{UNDO_BEGIN} and 829136644Sache@code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and 830136644Sache@code{rl_end_undo_group()}. 831136644Sache 832136644Sache@deftypefun int rl_begin_undo_group (void) 833136644SacheBegins saving undo information in a group construct. The undo 834136644Sacheinformation usually comes from calls to @code{rl_insert_text()} and 835136644Sache@code{rl_delete_text()}, but could be the result of calls to 836136644Sache@code{rl_add_undo()}. 837136644Sache@end deftypefun 838136644Sache 839136644Sache@deftypefun int rl_end_undo_group (void) 840136644SacheCloses the current undo group started with @code{rl_begin_undo_group 841136644Sache()}. There should be one call to @code{rl_end_undo_group()} 842136644Sachefor each call to @code{rl_begin_undo_group()}. 843136644Sache@end deftypefun 844136644Sache 845136644Sache@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text) 846136644SacheRemember how to undo an event (according to @var{what}). The affected 847136644Sachetext runs from @var{start} to @var{end}, and encompasses @var{text}. 848136644Sache@end deftypefun 849136644Sache 850136644Sache@deftypefun void rl_free_undo_list (void) 851136644SacheFree the existing undo list. 852136644Sache@end deftypefun 853136644Sache 854136644Sache@deftypefun int rl_do_undo (void) 855136644SacheUndo the first thing on the undo list. Returns @code{0} if there was 856136644Sachenothing to undo, non-zero if something was undone. 857136644Sache@end deftypefun 858136644Sache 859136644SacheFinally, if you neither insert nor delete text, but directly modify the 860136644Sacheexisting text (e.g., change its case), call @code{rl_modifying()} 861136644Sacheonce, just before you modify the text. You must supply the indices of 862136644Sachethe text range that you are going to modify. 863136644Sache 864136644Sache@deftypefun int rl_modifying (int start, int end) 865136644SacheTell Readline to save the text between @var{start} and @var{end} as a 866136644Sachesingle undo unit. It is assumed that you will subsequently modify 867136644Sachethat text. 868136644Sache@end deftypefun 869136644Sache 870136644Sache@node Redisplay 871136644Sache@subsection Redisplay 872136644Sache 873136644Sache@deftypefun void rl_redisplay (void) 874136644SacheChange what's displayed on the screen to reflect the current contents 875136644Sacheof @code{rl_line_buffer}. 876136644Sache@end deftypefun 877136644Sache 878136644Sache@deftypefun int rl_forced_update_display (void) 879136644SacheForce the line to be updated and redisplayed, whether or not 880136644SacheReadline thinks the screen display is correct. 881136644Sache@end deftypefun 882136644Sache 883136644Sache@deftypefun int rl_on_new_line (void) 884136644SacheTell the update functions that we have moved onto a new (empty) line, 885136644Sacheusually after ouputting a newline. 886136644Sache@end deftypefun 887136644Sache 888136644Sache@deftypefun int rl_on_new_line_with_prompt (void) 889136644SacheTell the update functions that we have moved onto a new line, with 890136644Sache@var{rl_prompt} already displayed. 891136644SacheThis could be used by applications that want to output the prompt string 892136644Sachethemselves, but still need Readline to know the prompt string length for 893136644Sacheredisplay. 894136644SacheIt should be used after setting @var{rl_already_prompted}. 895136644Sache@end deftypefun 896136644Sache 897136644Sache@deftypefun int rl_reset_line_state (void) 898136644SacheReset the display state to a clean state and redisplay the current line 899136644Sachestarting on a new line. 900136644Sache@end deftypefun 901136644Sache 902136644Sache@deftypefun int rl_crlf (void) 903136644SacheMove the cursor to the start of the next screen line. 904136644Sache@end deftypefun 905136644Sache 906136644Sache@deftypefun int rl_show_char (int c) 907136644SacheDisplay character @var{c} on @code{rl_outstream}. 908136644SacheIf Readline has not been set to display meta characters directly, this 909136644Sachewill convert meta characters to a meta-prefixed key sequence. 910136644SacheThis is intended for use by applications which wish to do their own 911136644Sacheredisplay. 912136644Sache@end deftypefun 913136644Sache 914136644Sache@deftypefun int rl_message (const char *, @dots{}) 915136644SacheThe arguments are a format string as would be supplied to @code{printf}, 916136644Sachepossibly containing conversion specifications such as @samp{%d}, and 917136644Sacheany additional arguments necessary to satisfy the conversion specifications. 918136644SacheThe resulting string is displayed in the @dfn{echo area}. The echo area 919136644Sacheis also used to display numeric arguments and search strings. 920157184SacheYou should call @code{rl_save_prompt} to save the prompt information 921157184Sachebefore calling this function. 922136644Sache@end deftypefun 923136644Sache 924136644Sache@deftypefun int rl_clear_message (void) 925157184SacheClear the message in the echo area. If the prompt was saved with a call to 926157184Sache@code{rl_save_prompt} before the last call to @code{rl_message}, 927157184Sachecall @code{rl_restore_prompt} before calling this function. 928136644Sache@end deftypefun 929136644Sache 930136644Sache@deftypefun void rl_save_prompt (void) 931136644SacheSave the local Readline prompt display state in preparation for 932136644Sachedisplaying a new message in the message area with @code{rl_message()}. 933136644Sache@end deftypefun 934136644Sache 935136644Sache@deftypefun void rl_restore_prompt (void) 936136644SacheRestore the local Readline prompt display state saved by the most 937136644Sacherecent call to @code{rl_save_prompt}. 938157184Sacheif @code{rl_save_prompt} was called to save the prompt before a call 939157184Sacheto @code{rl_message}, this function should be called before the 940157184Sachecorresponding call to @code{rl_clear_message}. 941136644Sache@end deftypefun 942136644Sache 943136644Sache@deftypefun int rl_expand_prompt (char *prompt) 944136644SacheExpand any special character sequences in @var{prompt} and set up the 945136644Sachelocal Readline prompt redisplay variables. 946136644SacheThis function is called by @code{readline()}. It may also be called to 947136644Sacheexpand the primary prompt if the @code{rl_on_new_line_with_prompt()} 948136644Sachefunction or @code{rl_already_prompted} variable is used. 949136644SacheIt returns the number of visible characters on the last line of the 950136644Sache(possibly multi-line) prompt. 951136644SacheApplications may indicate that the prompt contains characters that take 952136644Sacheup no physical screen space when displayed by bracketing a sequence of 953136644Sachesuch characters with the special markers @code{RL_PROMPT_START_IGNORE} 954136644Sacheand @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}. This may 955136644Sachebe used to embed terminal-specific escape sequences in prompts. 956136644Sache@end deftypefun 957136644Sache 958136644Sache@deftypefun int rl_set_prompt (const char *prompt) 959136644SacheMake Readline use @var{prompt} for subsequent redisplay. This calls 960136644Sache@code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt} 961136644Sacheto the result. 962136644Sache@end deftypefun 963136644Sache 964136644Sache@node Modifying Text 965136644Sache@subsection Modifying Text 966136644Sache 967136644Sache@deftypefun int rl_insert_text (const char *text) 968136644SacheInsert @var{text} into the line at the current cursor position. 969136644SacheReturns the number of characters inserted. 970136644Sache@end deftypefun 971136644Sache 972136644Sache@deftypefun int rl_delete_text (int start, int end) 973136644SacheDelete the text between @var{start} and @var{end} in the current line. 974136644SacheReturns the number of characters deleted. 975136644Sache@end deftypefun 976136644Sache 977136644Sache@deftypefun {char *} rl_copy_text (int start, int end) 978136644SacheReturn a copy of the text between @var{start} and @var{end} in 979136644Sachethe current line. 980136644Sache@end deftypefun 981136644Sache 982136644Sache@deftypefun int rl_kill_text (int start, int end) 983136644SacheCopy the text between @var{start} and @var{end} in the current line 984136644Sacheto the kill ring, appending or prepending to the last kill if the 985136644Sachelast command was a kill command. The text is deleted. 986136644SacheIf @var{start} is less than @var{end}, 987136644Sachethe text is appended, otherwise prepended. If the last command was 988136644Sachenot a kill, a new kill ring slot is used. 989136644Sache@end deftypefun 990136644Sache 991136644Sache@deftypefun int rl_push_macro_input (char *macro) 992136644SacheCause @var{macro} to be inserted into the line, as if it had been invoked 993136644Sacheby a key bound to a macro. Not especially useful; use 994136644Sache@code{rl_insert_text()} instead. 995136644Sache@end deftypefun 996136644Sache 997136644Sache@node Character Input 998136644Sache@subsection Character Input 999136644Sache 1000136644Sache@deftypefun int rl_read_key (void) 1001136644SacheReturn the next character available from Readline's current input stream. 1002136644SacheThis handles input inserted into 1003136644Sachethe input stream via @var{rl_pending_input} (@pxref{Readline Variables}) 1004136644Sacheand @code{rl_stuff_char()}, macros, and characters read from the keyboard. 1005136644SacheWhile waiting for input, this function will call any function assigned to 1006136644Sachethe @code{rl_event_hook} variable. 1007136644Sache@end deftypefun 1008136644Sache 1009136644Sache@deftypefun int rl_getc (FILE *stream) 1010136644SacheReturn the next character available from @var{stream}, which is assumed to 1011136644Sachebe the keyboard. 1012136644Sache@end deftypefun 1013136644Sache 1014136644Sache@deftypefun int rl_stuff_char (int c) 1015136644SacheInsert @var{c} into the Readline input stream. It will be "read" 1016136644Sachebefore Readline attempts to read characters from the terminal with 1017136644Sache@code{rl_read_key()}. Up to 512 characters may be pushed back. 1018136644Sache@code{rl_stuff_char} returns 1 if the character was successfully inserted; 1019136644Sache0 otherwise. 1020136644Sache@end deftypefun 1021136644Sache 1022136644Sache@deftypefun int rl_execute_next (int c) 1023136644SacheMake @var{c} be the next command to be executed when @code{rl_read_key()} 1024136644Sacheis called. This sets @var{rl_pending_input}. 1025136644Sache@end deftypefun 1026136644Sache 1027136644Sache@deftypefun int rl_clear_pending_input (void) 1028136644SacheUnset @var{rl_pending_input}, effectively negating the effect of any 1029136644Sacheprevious call to @code{rl_execute_next()}. This works only if the 1030136644Sachepending input has not already been read with @code{rl_read_key()}. 1031136644Sache@end deftypefun 1032136644Sache 1033136644Sache@deftypefun int rl_set_keyboard_input_timeout (int u) 1034136644SacheWhile waiting for keyboard input in @code{rl_read_key()}, Readline will 1035136644Sachewait for @var{u} microseconds for input before calling any function 1036165670Sacheassigned to @code{rl_event_hook}. @var{u} must be greater than or equal 1037165670Sacheto zero (a zero-length timeout is equivalent to a poll). 1038165670SacheThe default waiting period is one-tenth of a second. 1039165670SacheReturns the old timeout value. 1040136644Sache@end deftypefun 1041136644Sache 1042136644Sache@node Terminal Management 1043136644Sache@subsection Terminal Management 1044136644Sache 1045136644Sache@deftypefun void rl_prep_terminal (int meta_flag) 1046136644SacheModify the terminal settings for Readline's use, so @code{readline()} 1047136644Sachecan read a single character at a time from the keyboard. 1048136644SacheThe @var{meta_flag} argument should be non-zero if Readline should 1049136644Sacheread eight-bit input. 1050136644Sache@end deftypefun 1051136644Sache 1052136644Sache@deftypefun void rl_deprep_terminal (void) 1053136644SacheUndo the effects of @code{rl_prep_terminal()}, leaving the terminal in 1054136644Sachethe state in which it was before the most recent call to 1055136644Sache@code{rl_prep_terminal()}. 1056136644Sache@end deftypefun 1057136644Sache 1058136644Sache@deftypefun void rl_tty_set_default_bindings (Keymap kmap) 1059136644SacheRead the operating system's terminal editing characters (as would be 1060136644Sachedisplayed by @code{stty}) to their Readline equivalents. 1061136644SacheThe bindings are performed in @var{kmap}. 1062136644Sache@end deftypefun 1063136644Sache 1064136644Sache@deftypefun void rl_tty_unset_default_bindings (Keymap kmap) 1065136644SacheReset the bindings manipulated by @code{rl_tty_set_default_bindings} so 1066136644Sachethat the terminal editing characters are bound to @code{rl_insert}. 1067136644SacheThe bindings are performed in @var{kmap}. 1068136644Sache@end deftypefun 1069136644Sache 1070136644Sache@deftypefun int rl_reset_terminal (const char *terminal_name) 1071136644SacheReinitialize Readline's idea of the terminal settings using 1072136644Sache@var{terminal_name} as the terminal type (e.g., @code{vt100}). 1073136644SacheIf @var{terminal_name} is @code{NULL}, the value of the @code{TERM} 1074136644Sacheenvironment variable is used. 1075136644Sache@end deftypefun 1076136644Sache 1077136644Sache@node Utility Functions 1078136644Sache@subsection Utility Functions 1079136644Sache 1080136644Sache@deftypefun void rl_replace_line (const char *text, int clear_undo) 1081136644SacheReplace the contents of @code{rl_line_buffer} with @var{text}. 1082136644SacheThe point and mark are preserved, if possible. 1083136644SacheIf @var{clear_undo} is non-zero, the undo list associated with the 1084136644Sachecurrent line is cleared. 1085136644Sache@end deftypefun 1086136644Sache 1087136644Sache@deftypefun int rl_extend_line_buffer (int len) 1088136644SacheEnsure that @code{rl_line_buffer} has enough space to hold @var{len} 1089136644Sachecharacters, possibly reallocating it if necessary. 1090136644Sache@end deftypefun 1091136644Sache 1092136644Sache@deftypefun int rl_initialize (void) 1093136644SacheInitialize or re-initialize Readline's internal state. 1094136644SacheIt's not strictly necessary to call this; @code{readline()} calls it before 1095136644Sachereading any input. 1096136644Sache@end deftypefun 1097136644Sache 1098136644Sache@deftypefun int rl_ding (void) 1099136644SacheRing the terminal bell, obeying the setting of @code{bell-style}. 1100136644Sache@end deftypefun 1101136644Sache 1102136644Sache@deftypefun int rl_alphabetic (int c) 1103136644SacheReturn 1 if @var{c} is an alphabetic character. 1104136644Sache@end deftypefun 1105136644Sache 1106136644Sache@deftypefun void rl_display_match_list (char **matches, int len, int max) 1107136644SacheA convenience function for displaying a list of strings in 1108136644Sachecolumnar format on Readline's output stream. @code{matches} is the list 1109136644Sacheof strings, in argv format, such as a list of completion matches. 1110136644Sache@code{len} is the number of strings in @code{matches}, and @code{max} 1111136644Sacheis the length of the longest string in @code{matches}. This function uses 1112136644Sachethe setting of @code{print-completions-horizontally} to select how the 1113136644Sachematches are displayed (@pxref{Readline Init File Syntax}). 1114136644Sache@end deftypefun 1115136644Sache 1116136644SacheThe following are implemented as macros, defined in @code{chardefs.h}. 1117136644SacheApplications should refrain from using them. 1118136644Sache 1119136644Sache@deftypefun int _rl_uppercase_p (int c) 1120136644SacheReturn 1 if @var{c} is an uppercase alphabetic character. 1121136644Sache@end deftypefun 1122136644Sache 1123136644Sache@deftypefun int _rl_lowercase_p (int c) 1124136644SacheReturn 1 if @var{c} is a lowercase alphabetic character. 1125136644Sache@end deftypefun 1126136644Sache 1127136644Sache@deftypefun int _rl_digit_p (int c) 1128136644SacheReturn 1 if @var{c} is a numeric character. 1129136644Sache@end deftypefun 1130136644Sache 1131136644Sache@deftypefun int _rl_to_upper (int c) 1132136644SacheIf @var{c} is a lowercase alphabetic character, return the corresponding 1133136644Sacheuppercase character. 1134136644Sache@end deftypefun 1135136644Sache 1136136644Sache@deftypefun int _rl_to_lower (int c) 1137136644SacheIf @var{c} is an uppercase alphabetic character, return the corresponding 1138136644Sachelowercase character. 1139136644Sache@end deftypefun 1140136644Sache 1141136644Sache@deftypefun int _rl_digit_value (int c) 1142136644SacheIf @var{c} is a number, return the value it represents. 1143136644Sache@end deftypefun 1144136644Sache 1145136644Sache@node Miscellaneous Functions 1146136644Sache@subsection Miscellaneous Functions 1147136644Sache 1148136644Sache@deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map) 1149136644SacheBind the key sequence @var{keyseq} to invoke the macro @var{macro}. 1150136644SacheThe binding is performed in @var{map}. When @var{keyseq} is invoked, the 1151136644Sache@var{macro} will be inserted into the line. This function is deprecated; 1152136644Sacheuse @code{rl_generic_bind()} instead. 1153136644Sache@end deftypefun 1154136644Sache 1155136644Sache@deftypefun void rl_macro_dumper (int readable) 1156136644SachePrint the key sequences bound to macros and their values, using 1157136644Sachethe current keymap, to @code{rl_outstream}. 1158136644SacheIf @var{readable} is non-zero, the list is formatted in such a way 1159136644Sachethat it can be made part of an @code{inputrc} file and re-read. 1160136644Sache@end deftypefun 1161136644Sache 1162136644Sache@deftypefun int rl_variable_bind (const char *variable, const char *value) 1163136644SacheMake the Readline variable @var{variable} have @var{value}. 1164136644SacheThis behaves as if the readline command 1165136644Sache@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc} 1166136644Sachefile (@pxref{Readline Init File Syntax}). 1167136644Sache@end deftypefun 1168136644Sache 1169157184Sache@deftypefun {char *} rl_variable_value (const char *variable) 1170157184SacheReturn a string representing the value of the Readline variable @var{variable}. 1171157184SacheFor boolean variables, this string is either @samp{on} or @samp{off}. 1172157184Sache@end deftypefun 1173157184Sache 1174136644Sache@deftypefun void rl_variable_dumper (int readable) 1175136644SachePrint the readline variable names and their current values 1176136644Sacheto @code{rl_outstream}. 1177136644SacheIf @var{readable} is non-zero, the list is formatted in such a way 1178136644Sachethat it can be made part of an @code{inputrc} file and re-read. 1179136644Sache@end deftypefun 1180136644Sache 1181136644Sache@deftypefun int rl_set_paren_blink_timeout (int u) 1182136644SacheSet the time interval (in microseconds) that Readline waits when showing 1183136644Sachea balancing character when @code{blink-matching-paren} has been enabled. 1184136644Sache@end deftypefun 1185136644Sache 1186136644Sache@deftypefun {char *} rl_get_termcap (const char *cap) 1187136644SacheRetrieve the string value of the termcap capability @var{cap}. 1188136644SacheReadline fetches the termcap entry for the current terminal name and 1189136644Sacheuses those capabilities to move around the screen line and perform other 1190136644Sacheterminal-specific operations, like erasing a line. Readline does not 1191136644Sacheuse all of a terminal's capabilities, and this function will return 1192136644Sachevalues for only those capabilities Readline uses. 1193136644Sache@end deftypefun 1194136644Sache 1195136644Sache@node Alternate Interface 1196136644Sache@subsection Alternate Interface 1197136644Sache 1198136644SacheAn alternate interface is available to plain @code{readline()}. Some 1199136644Sacheapplications need to interleave keyboard I/O with file, device, or 1200136644Sachewindow system I/O, typically by using a main loop to @code{select()} 1201136644Sacheon various file descriptors. To accomodate this need, readline can 1202136644Sachealso be invoked as a `callback' function from an event loop. There 1203136644Sacheare functions available to make this easy. 1204136644Sache 1205136644Sache@deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler) 1206136644SacheSet up the terminal for readline I/O and display the initial 1207136644Sacheexpanded value of @var{prompt}. Save the value of @var{lhandler} to 1208136644Sacheuse as a function to call when a complete line of input has been entered. 1209136644SacheThe function takes the text of the line as an argument. 1210136644Sache@end deftypefun 1211136644Sache 1212136644Sache@deftypefun void rl_callback_read_char (void) 1213136644SacheWhenever an application determines that keyboard input is available, it 1214136644Sacheshould call @code{rl_callback_read_char()}, which will read the next 1215136644Sachecharacter from the current input source. 1216136644SacheIf that character completes the line, @code{rl_callback_read_char} will 1217136644Sacheinvoke the @var{lhandler} function saved by @code{rl_callback_handler_install} 1218136644Sacheto process the line. 1219136644SacheBefore calling the @var{lhandler} function, the terminal settings are 1220136644Sachereset to the values they had before calling 1221136644Sache@code{rl_callback_handler_install}. 1222136644SacheIf the @var{lhandler} function returns, 1223136644Sachethe terminal settings are modified for Readline's use again. 1224136644Sache@code{EOF} is indicated by calling @var{lhandler} with a 1225136644Sache@code{NULL} line. 1226136644Sache@end deftypefun 1227136644Sache 1228136644Sache@deftypefun void rl_callback_handler_remove (void) 1229136644SacheRestore the terminal to its initial state and remove the line handler. 1230136644SacheThis may be called from within a callback as well as independently. 1231136644SacheIf the @var{lhandler} installed by @code{rl_callback_handler_install} 1232136644Sachedoes not exit the program, either this function or the function referred 1233136644Sacheto by the value of @code{rl_deprep_term_function} should be called before 1234136644Sachethe program exits to reset the terminal settings. 1235136644Sache@end deftypefun 1236136644Sache 1237136644Sache@node A Readline Example 1238136644Sache@subsection A Readline Example 1239136644Sache 1240136644SacheHere is a function which changes lowercase characters to their uppercase 1241136644Sacheequivalents, and uppercase characters to lowercase. If 1242136644Sachethis function was bound to @samp{M-c}, then typing @samp{M-c} would 1243136644Sachechange the case of the character under point. Typing @samp{M-1 0 M-c} 1244136644Sachewould change the case of the following 10 characters, leaving the cursor on 1245136644Sachethe last character changed. 1246136644Sache 1247136644Sache@example 1248136644Sache/* Invert the case of the COUNT following characters. */ 1249136644Sacheint 1250136644Sacheinvert_case_line (count, key) 1251136644Sache int count, key; 1252136644Sache@{ 1253136644Sache register int start, end, i; 1254136644Sache 1255136644Sache start = rl_point; 1256136644Sache 1257136644Sache if (rl_point >= rl_end) 1258136644Sache return (0); 1259136644Sache 1260136644Sache if (count < 0) 1261136644Sache @{ 1262136644Sache direction = -1; 1263136644Sache count = -count; 1264136644Sache @} 1265136644Sache else 1266136644Sache direction = 1; 1267136644Sache 1268136644Sache /* Find the end of the range to modify. */ 1269136644Sache end = start + (count * direction); 1270136644Sache 1271136644Sache /* Force it to be within range. */ 1272136644Sache if (end > rl_end) 1273136644Sache end = rl_end; 1274136644Sache else if (end < 0) 1275136644Sache end = 0; 1276136644Sache 1277136644Sache if (start == end) 1278136644Sache return (0); 1279136644Sache 1280136644Sache if (start > end) 1281136644Sache @{ 1282136644Sache int temp = start; 1283136644Sache start = end; 1284136644Sache end = temp; 1285136644Sache @} 1286136644Sache 1287136644Sache /* Tell readline that we are modifying the line, 1288136644Sache so it will save the undo information. */ 1289136644Sache rl_modifying (start, end); 1290136644Sache 1291136644Sache for (i = start; i != end; i++) 1292136644Sache @{ 1293136644Sache if (_rl_uppercase_p (rl_line_buffer[i])) 1294136644Sache rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]); 1295136644Sache else if (_rl_lowercase_p (rl_line_buffer[i])) 1296136644Sache rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]); 1297136644Sache @} 1298136644Sache /* Move point to on top of the last character changed. */ 1299136644Sache rl_point = (direction == 1) ? end - 1 : start; 1300136644Sache return (0); 1301136644Sache@} 1302136644Sache@end example 1303136644Sache 1304136644Sache@node Readline Signal Handling 1305136644Sache@section Readline Signal Handling 1306136644Sache 1307136644SacheSignals are asynchronous events sent to a process by the Unix kernel, 1308136644Sachesometimes on behalf of another process. They are intended to indicate 1309136644Sacheexceptional events, like a user pressing the interrupt key on his terminal, 1310136644Sacheor a network connection being broken. There is a class of signals that can 1311136644Sachebe sent to the process currently reading input from the keyboard. Since 1312136644SacheReadline changes the terminal attributes when it is called, it needs to 1313136644Sacheperform special processing when such a signal is received in order to 1314136644Sacherestore the terminal to a sane state, or provide application writers with 1315136644Sachefunctions to do so manually. 1316136644Sache 1317136644SacheReadline contains an internal signal handler that is installed for a 1318136644Sachenumber of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, 1319136644Sache@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}). 1320136644SacheWhen one of these signals is received, the signal handler 1321136644Sachewill reset the terminal attributes to those that were in effect before 1322136644Sache@code{readline()} was called, reset the signal handling to what it was 1323136644Sachebefore @code{readline()} was called, and resend the signal to the calling 1324136644Sacheapplication. 1325136644SacheIf and when the calling application's signal handler returns, Readline 1326136644Sachewill reinitialize the terminal and continue to accept input. 1327136644SacheWhen a @code{SIGINT} is received, the Readline signal handler performs 1328136644Sachesome additional work, which will cause any partially-entered line to be 1329136644Sacheaborted (see the description of @code{rl_free_line_state()} below). 1330136644Sache 1331136644SacheThere is an additional Readline signal handler, for @code{SIGWINCH}, which 1332136644Sachethe kernel sends to a process whenever the terminal's size changes (for 1333136644Sacheexample, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH} 1334136644Sachehandler updates Readline's internal screen size information, and then calls 1335136644Sacheany @code{SIGWINCH} signal handler the calling application has installed. 1336136644SacheReadline calls the application's @code{SIGWINCH} signal handler without 1337136644Sacheresetting the terminal to its original state. If the application's signal 1338136644Sachehandler does more than update its idea of the terminal size and return (for 1339136644Sacheexample, a @code{longjmp} back to a main processing loop), it @emph{must} 1340136644Sachecall @code{rl_cleanup_after_signal()} (described below), to restore the 1341136644Sacheterminal state. 1342136644Sache 1343136644SacheReadline provides two variables that allow application writers to 1344136644Sachecontrol whether or not it will catch certain signals and act on them 1345136644Sachewhen they are received. It is important that applications change the 1346136644Sachevalues of these variables only when calling @code{readline()}, not in 1347136644Sachea signal handler, so Readline's internal signal state is not corrupted. 1348136644Sache 1349136644Sache@deftypevar int rl_catch_signals 1350136644SacheIf this variable is non-zero, Readline will install signal handlers for 1351136644Sache@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGALRM}, 1352136644Sache@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}. 1353136644Sache 1354136644SacheThe default value of @code{rl_catch_signals} is 1. 1355136644Sache@end deftypevar 1356136644Sache 1357136644Sache@deftypevar int rl_catch_sigwinch 1358136644SacheIf this variable is non-zero, Readline will install a signal handler for 1359136644Sache@code{SIGWINCH}. 1360136644Sache 1361136644SacheThe default value of @code{rl_catch_sigwinch} is 1. 1362136644Sache@end deftypevar 1363136644Sache 1364136644SacheIf an application does not wish to have Readline catch any signals, or 1365136644Sacheto handle signals other than those Readline catches (@code{SIGHUP}, 1366136644Sachefor example), 1367136644SacheReadline provides convenience functions to do the necessary terminal 1368136644Sacheand internal state cleanup upon receipt of a signal. 1369136644Sache 1370136644Sache@deftypefun void rl_cleanup_after_signal (void) 1371136644SacheThis function will reset the state of the terminal to what it was before 1372136644Sache@code{readline()} was called, and remove the Readline signal handlers for 1373136644Sacheall signals, depending on the values of @code{rl_catch_signals} and 1374136644Sache@code{rl_catch_sigwinch}. 1375136644Sache@end deftypefun 1376136644Sache 1377136644Sache@deftypefun void rl_free_line_state (void) 1378136644SacheThis will free any partial state associated with the current input line 1379136644Sache(undo information, any partial history entry, any partially-entered 1380136644Sachekeyboard macro, and any partially-entered numeric argument). This 1381136644Sacheshould be called before @code{rl_cleanup_after_signal()}. The 1382136644SacheReadline signal handler for @code{SIGINT} calls this to abort the 1383136644Sachecurrent input line. 1384136644Sache@end deftypefun 1385136644Sache 1386136644Sache@deftypefun void rl_reset_after_signal (void) 1387136644SacheThis will reinitialize the terminal and reinstall any Readline signal 1388136644Sachehandlers, depending on the values of @code{rl_catch_signals} and 1389136644Sache@code{rl_catch_sigwinch}. 1390136644Sache@end deftypefun 1391136644Sache 1392136644SacheIf an application does not wish Readline to catch @code{SIGWINCH}, it may 1393136644Sachecall @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force 1394136644SacheReadline to update its idea of the terminal size when a @code{SIGWINCH} 1395136644Sacheis received. 1396136644Sache 1397136644Sache@deftypefun void rl_resize_terminal (void) 1398136644SacheUpdate Readline's internal screen size by reading values from the kernel. 1399136644Sache@end deftypefun 1400136644Sache 1401136644Sache@deftypefun void rl_set_screen_size (int rows, int cols) 1402136644SacheSet Readline's idea of the terminal size to @var{rows} rows and 1403157184Sache@var{cols} columns. If either @var{rows} or @var{columns} is less than 1404157184Sacheor equal to 0, Readline's idea of that terminal dimension is unchanged. 1405136644Sache@end deftypefun 1406136644Sache 1407136644SacheIf an application does not want to install a @code{SIGWINCH} handler, but 1408136644Sacheis still interested in the screen dimensions, Readline's idea of the screen 1409136644Sachesize may be queried. 1410136644Sache 1411136644Sache@deftypefun void rl_get_screen_size (int *rows, int *cols) 1412136644SacheReturn Readline's idea of the terminal's size in the 1413136644Sachevariables pointed to by the arguments. 1414136644Sache@end deftypefun 1415136644Sache 1416157184Sache@deftypefun void rl_reset_screen_size (void) 1417157184SacheCause Readline to reobtain the screen size and recalculate its dimensions. 1418157184Sache@end deftypefun 1419157184Sache 1420136644SacheThe following functions install and remove Readline's signal handlers. 1421136644Sache 1422136644Sache@deftypefun int rl_set_signals (void) 1423136644SacheInstall Readline's signal handler for @code{SIGINT}, @code{SIGQUIT}, 1424136644Sache@code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, 1425136644Sache@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of 1426136644Sache@code{rl_catch_signals} and @code{rl_catch_sigwinch}. 1427136644Sache@end deftypefun 1428136644Sache 1429136644Sache@deftypefun int rl_clear_signals (void) 1430136644SacheRemove all of the Readline signal handlers installed by 1431136644Sache@code{rl_set_signals()}. 1432136644Sache@end deftypefun 1433136644Sache 1434136644Sache@node Custom Completers 1435136644Sache@section Custom Completers 1436136644Sache@cindex application-specific completion functions 1437136644Sache 1438136644SacheTypically, a program that reads commands from the user has a way of 1439136644Sachedisambiguating commands and data. If your program is one of these, then 1440136644Sacheit can provide completion for commands, data, or both. 1441136644SacheThe following sections describe how your program and Readline 1442136644Sachecooperate to provide this service. 1443136644Sache 1444136644Sache@menu 1445136644Sache* How Completing Works:: The logic used to do completion. 1446136644Sache* Completion Functions:: Functions provided by Readline. 1447136644Sache* Completion Variables:: Variables which control completion. 1448136644Sache* A Short Completion Example:: An example of writing completer subroutines. 1449136644Sache@end menu 1450136644Sache 1451136644Sache@node How Completing Works 1452136644Sache@subsection How Completing Works 1453136644Sache 1454136644SacheIn order to complete some text, the full list of possible completions 1455136644Sachemust be available. That is, it is not possible to accurately 1456136644Sacheexpand a partial word without knowing all of the possible words 1457136644Sachewhich make sense in that context. The Readline library provides 1458136644Sachethe user interface to completion, and two of the most common 1459136644Sachecompletion functions: filename and username. For completing other types 1460136644Sacheof text, you must write your own completion function. This section 1461136644Sachedescribes exactly what such functions must do, and provides an example. 1462136644Sache 1463136644SacheThere are three major functions used to perform completion: 1464136644Sache 1465136644Sache@enumerate 1466136644Sache@item 1467136644SacheThe user-interface function @code{rl_complete()}. This function is 1468136644Sachecalled with the same arguments as other bindable Readline functions: 1469136644Sache@var{count} and @var{invoking_key}. 1470136644SacheIt isolates the word to be completed and calls 1471136644Sache@code{rl_completion_matches()} to generate a list of possible completions. 1472136644SacheIt then either lists the possible completions, inserts the possible 1473136644Sachecompletions, or actually performs the 1474136644Sachecompletion, depending on which behavior is desired. 1475136644Sache 1476136644Sache@item 1477136644SacheThe internal function @code{rl_completion_matches()} uses an 1478136644Sacheapplication-supplied @dfn{generator} function to generate the list of 1479136644Sachepossible matches, and then returns the array of these matches. 1480136644SacheThe caller should place the address of its generator function in 1481136644Sache@code{rl_completion_entry_function}. 1482136644Sache 1483136644Sache@item 1484136644SacheThe generator function is called repeatedly from 1485136644Sache@code{rl_completion_matches()}, returning a string each time. The 1486136644Sachearguments to the generator function are @var{text} and @var{state}. 1487136644Sache@var{text} is the partial word to be completed. @var{state} is zero the 1488136644Sachefirst time the function is called, allowing the generator to perform 1489136644Sacheany necessary initialization, and a positive non-zero integer for 1490136644Sacheeach subsequent call. The generator function returns 1491136644Sache@code{(char *)NULL} to inform @code{rl_completion_matches()} that there are 1492136644Sacheno more possibilities left. Usually the generator function computes the 1493136644Sachelist of possible completions when @var{state} is zero, and returns them 1494136644Sacheone at a time on subsequent calls. Each string the generator function 1495136644Sachereturns as a match must be allocated with @code{malloc()}; Readline 1496136644Sachefrees the strings when it has finished with them. 1497136644SacheSuch a generator function is referred to as an 1498136644Sache@dfn{application-specific completion function}. 1499136644Sache 1500136644Sache@end enumerate 1501136644Sache 1502136644Sache@deftypefun int rl_complete (int ignore, int invoking_key) 1503136644SacheComplete the word at or before point. You have supplied the function 1504136644Sachethat does the initial simple matching selection algorithm (see 1505136644Sache@code{rl_completion_matches()}). The default is to do filename completion. 1506136644Sache@end deftypefun 1507136644Sache 1508136644Sache@deftypevar {rl_compentry_func_t *} rl_completion_entry_function 1509136644SacheThis is a pointer to the generator function for 1510136644Sache@code{rl_completion_matches()}. 1511136644SacheIf the value of @code{rl_completion_entry_function} is 1512136644Sache@code{NULL} then the default filename generator 1513136644Sachefunction, @code{rl_filename_completion_function()}, is used. 1514136644SacheAn @dfn{application-specific completion function} is a function whose 1515136644Sacheaddress is assigned to @code{rl_completion_entry_function} and whose 1516136644Sachereturn values are used to generate possible completions. 1517136644Sache@end deftypevar 1518136644Sache 1519136644Sache@node Completion Functions 1520136644Sache@subsection Completion Functions 1521136644Sache 1522136644SacheHere is the complete list of callable completion functions present in 1523136644SacheReadline. 1524136644Sache 1525136644Sache@deftypefun int rl_complete_internal (int what_to_do) 1526136644SacheComplete the word at or before point. @var{what_to_do} says what to do 1527136644Sachewith the completion. A value of @samp{?} means list the possible 1528136644Sachecompletions. @samp{TAB} means do standard completion. @samp{*} means 1529136644Sacheinsert all of the possible completions. @samp{!} means to display 1530136644Sacheall of the possible completions, if there is more than one, as well as 1531136644Sacheperforming partial completion. @samp{@@} is similar to @samp{!}, but 1532136644Sachepossible completions are not listed if the possible completions share 1533136644Sachea common prefix. 1534136644Sache@end deftypefun 1535136644Sache 1536136644Sache@deftypefun int rl_complete (int ignore, int invoking_key) 1537136644SacheComplete the word at or before point. You have supplied the function 1538136644Sachethat does the initial simple matching selection algorithm (see 1539136644Sache@code{rl_completion_matches()} and @code{rl_completion_entry_function}). 1540136644SacheThe default is to do filename 1541136644Sachecompletion. This calls @code{rl_complete_internal()} with an 1542136644Sacheargument depending on @var{invoking_key}. 1543136644Sache@end deftypefun 1544136644Sache 1545136644Sache@deftypefun int rl_possible_completions (int count, int invoking_key) 1546136644SacheList the possible completions. See description of @code{rl_complete 1547136644Sache()}. This calls @code{rl_complete_internal()} with an argument of 1548136644Sache@samp{?}. 1549136644Sache@end deftypefun 1550136644Sache 1551136644Sache@deftypefun int rl_insert_completions (int count, int invoking_key) 1552136644SacheInsert the list of possible completions into the line, deleting the 1553136644Sachepartially-completed word. See description of @code{rl_complete()}. 1554136644SacheThis calls @code{rl_complete_internal()} with an argument of @samp{*}. 1555136644Sache@end deftypefun 1556136644Sache 1557136644Sache@deftypefun int rl_completion_mode (rl_command_func_t *cfunc) 1558136644SacheReturns the apppriate value to pass to @code{rl_complete_internal()} 1559136644Sachedepending on whether @var{cfunc} was called twice in succession and 1560136644Sachethe values of the @code{show-all-if-ambiguous} and 1561136644Sache@code{show-all-if-unmodified} variables. 1562136644SacheApplication-specific completion functions may use this function to present 1563136644Sachethe same interface as @code{rl_complete()}. 1564136644Sache@end deftypefun 1565136644Sache 1566136644Sache@deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func) 1567136644SacheReturns an array of strings which is a list of completions for 1568136644Sache@var{text}. If there are no completions, returns @code{NULL}. 1569136644SacheThe first entry in the returned array is the substitution for @var{text}. 1570136644SacheThe remaining entries are the possible completions. The array is 1571136644Sacheterminated with a @code{NULL} pointer. 1572136644Sache 1573136644Sache@var{entry_func} is a function of two args, and returns a 1574136644Sache@code{char *}. The first argument is @var{text}. The second is a 1575136644Sachestate argument; it is zero on the first call, and non-zero on subsequent 1576136644Sachecalls. @var{entry_func} returns a @code{NULL} pointer to the caller 1577136644Sachewhen there are no more matches. 1578136644Sache@end deftypefun 1579136644Sache 1580136644Sache@deftypefun {char *} rl_filename_completion_function (const char *text, int state) 1581136644SacheA generator function for filename completion in the general case. 1582136644Sache@var{text} is a partial filename. 1583136644SacheThe Bash source is a useful reference for writing application-specific 1584136644Sachecompletion functions (the Bash completion functions call this and other 1585136644SacheReadline functions). 1586136644Sache@end deftypefun 1587136644Sache 1588136644Sache@deftypefun {char *} rl_username_completion_function (const char *text, int state) 1589136644SacheA completion generator for usernames. @var{text} contains a partial 1590136644Sacheusername preceded by a random character (usually @samp{~}). As with all 1591136644Sachecompletion generators, @var{state} is zero on the first call and non-zero 1592136644Sachefor subsequent calls. 1593136644Sache@end deftypefun 1594136644Sache 1595136644Sache@node Completion Variables 1596136644Sache@subsection Completion Variables 1597136644Sache 1598136644Sache@deftypevar {rl_compentry_func_t *} rl_completion_entry_function 1599136644SacheA pointer to the generator function for @code{rl_completion_matches()}. 1600136644Sache@code{NULL} means to use @code{rl_filename_completion_function()}, 1601136644Sachethe default filename completer. 1602136644Sache@end deftypevar 1603136644Sache 1604136644Sache@deftypevar {rl_completion_func_t *} rl_attempted_completion_function 1605136644SacheA pointer to an alternative function to create matches. 1606136644SacheThe function is called with @var{text}, @var{start}, and @var{end}. 1607136644Sache@var{start} and @var{end} are indices in @code{rl_line_buffer} defining 1608136644Sachethe boundaries of @var{text}, which is a character string. 1609136644SacheIf this function exists and returns @code{NULL}, or if this variable is 1610136644Sacheset to @code{NULL}, then @code{rl_complete()} will call the value of 1611136644Sache@code{rl_completion_entry_function} to generate matches, otherwise the 1612136644Sachearray of strings returned will be used. 1613136644SacheIf this function sets the @code{rl_attempted_completion_over} 1614136644Sachevariable to a non-zero value, Readline will not perform its default 1615136644Sachecompletion even if this function returns no matches. 1616136644Sache@end deftypevar 1617136644Sache 1618136644Sache@deftypevar {rl_quote_func_t *} rl_filename_quoting_function 1619136644SacheA pointer to a function that will quote a filename in an 1620136644Sacheapplication-specific fashion. This is called if filename completion is being 1621136644Sacheattempted and one of the characters in @code{rl_filename_quote_characters} 1622136644Sacheappears in a completed filename. The function is called with 1623136644Sache@var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text} 1624136644Sacheis the filename to be quoted. The @var{match_type} is either 1625136644Sache@code{SINGLE_MATCH}, if there is only one completion match, or 1626136644Sache@code{MULT_MATCH}. Some functions use this to decide whether or not to 1627136644Sacheinsert a closing quote character. The @var{quote_pointer} is a pointer 1628136644Sacheto any opening quote character the user typed. Some functions choose 1629136644Sacheto reset this character. 1630136644Sache@end deftypevar 1631136644Sache 1632136644Sache@deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function 1633136644SacheA pointer to a function that will remove application-specific quoting 1634136644Sachecharacters from a filename before completion is attempted, so those 1635136644Sachecharacters do not interfere with matching the text against names in 1636136644Sachethe filesystem. It is called with @var{text}, the text of the word 1637136644Sacheto be dequoted, and @var{quote_char}, which is the quoting character 1638136644Sachethat delimits the filename (usually @samp{'} or @samp{"}). If 1639136644Sache@var{quote_char} is zero, the filename was not in an embedded string. 1640136644Sache@end deftypevar 1641136644Sache 1642136644Sache@deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p 1643136644SacheA pointer to a function to call that determines whether or not a specific 1644136644Sachecharacter in the line buffer is quoted, according to whatever quoting 1645136644Sachemechanism the program calling Readline uses. The function is called with 1646136644Sachetwo arguments: @var{text}, the text of the line, and @var{index}, the 1647136644Sacheindex of the character in the line. It is used to decide whether a 1648136644Sachecharacter found in @code{rl_completer_word_break_characters} should be 1649136644Sacheused to break words for the completer. 1650136644Sache@end deftypevar 1651136644Sache 1652136644Sache@deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function 1653136644SacheThis function, if defined, is called by the completer when real filename 1654136644Sachecompletion is done, after all the matching names have been generated. 1655136644SacheIt is passed a @code{NULL} terminated array of matches. 1656136644SacheThe first element (@code{matches[0]}) is the 1657136644Sachemaximal substring common to all matches. This function can 1658136644Sachere-arrange the list of matches as required, but each element deleted 1659136644Sachefrom the array must be freed. 1660136644Sache@end deftypevar 1661136644Sache 1662136644Sache@deftypevar {rl_icppfunc_t *} rl_directory_completion_hook 1663136644SacheThis function, if defined, is allowed to modify the directory portion 1664136644Sacheof filenames Readline completes. It is called with the address of a 1665136644Sachestring (the current directory name) as an argument, and may modify that string. 1666136644SacheIf the string is replaced with a new string, the old value should be freed. 1667136644SacheAny modified directory name should have a trailing slash. 1668136644SacheThe modified value will be displayed as part of the completion, replacing 1669136644Sachethe directory portion of the pathname the user typed. 1670136644SacheIt returns an integer that should be non-zero if the function modifies 1671136644Sacheits directory argument. 1672136644SacheIt could be used to expand symbolic links or shell variables in pathnames. 1673165670SacheAt the least, even if no other expansion is performed, this function should 1674165670Sacheremove any quote characters from the directory name, because its result will 1675165670Sachebe passed directly to @code{opendir()}. 1676136644Sache@end deftypevar 1677136644Sache 1678136644Sache@deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook 1679136644SacheIf non-zero, then this is the address of a function to call when 1680136644Sachecompleting a word would normally display the list of possible matches. 1681136644SacheThis function is called in lieu of Readline displaying the list. 1682136644SacheIt takes three arguments: 1683136644Sache(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length}) 1684136644Sachewhere @var{matches} is the array of matching strings, 1685136644Sache@var{num_matches} is the number of strings in that array, and 1686136644Sache@var{max_length} is the length of the longest string in that array. 1687136644SacheReadline provides a convenience function, @code{rl_display_match_list}, 1688136644Sachethat takes care of doing the display to Readline's output stream. That 1689136644Sachefunction may be called from this hook. 1690136644Sache@end deftypevar 1691136644Sache 1692136644Sache@deftypevar {const char *} rl_basic_word_break_characters 1693136644SacheThe basic list of characters that signal a break between words for the 1694136644Sachecompleter routine. The default value of this variable is the characters 1695136644Sachewhich break words for completion in Bash: 1696136644Sache@code{" \t\n\"\\'`@@$><=;|&@{("}. 1697136644Sache@end deftypevar 1698136644Sache 1699136644Sache@deftypevar {const char *} rl_basic_quote_characters 1700136644SacheA list of quote characters which can cause a word break. 1701136644Sache@end deftypevar 1702136644Sache 1703136644Sache@deftypevar {const char *} rl_completer_word_break_characters 1704136644SacheThe list of characters that signal a break between words for 1705136644Sache@code{rl_complete_internal()}. The default list is the value of 1706136644Sache@code{rl_basic_word_break_characters}. 1707136644Sache@end deftypevar 1708136644Sache 1709136644Sache@deftypevar {rl_cpvfunc_t *} rl_completion_word_break_hook 1710136644SacheIf non-zero, this is the address of a function to call when Readline is 1711136644Sachedeciding where to separate words for word completion. It should return 1712136644Sachea character string like @code{rl_completer_word_break_characters} to be 1713136644Sacheused to perform the current completion. The function may choose to set 1714136644Sache@code{rl_completer_word_break_characters} itself. If the function 1715136644Sachereturns @code{NULL}, @code{rl_completer_word_break_characters} is used. 1716136644Sache@end deftypevar 1717136644Sache 1718136644Sache@deftypevar {const char *} rl_completer_quote_characters 1719136644SacheA list of characters which can be used to quote a substring of the line. 1720136644SacheCompletion occurs on the entire substring, and within the substring 1721136644Sache@code{rl_completer_word_break_characters} are treated as any other character, 1722136644Sacheunless they also appear within this list. 1723136644Sache@end deftypevar 1724136644Sache 1725136644Sache@deftypevar {const char *} rl_filename_quote_characters 1726136644SacheA list of characters that cause a filename to be quoted by the completer 1727136644Sachewhen they appear in a completed filename. The default is the null string. 1728136644Sache@end deftypevar 1729136644Sache 1730136644Sache@deftypevar {const char *} rl_special_prefixes 1731136644SacheThe list of characters that are word break characters, but should be 1732136644Sacheleft in @var{text} when it is passed to the completion function. 1733136644SachePrograms can use this to help determine what kind of completing to do. 1734136644SacheFor instance, Bash sets this variable to "$@@" so that it can complete 1735136644Sacheshell variables and hostnames. 1736136644Sache@end deftypevar 1737136644Sache 1738136644Sache@deftypevar int rl_completion_query_items 1739136644SacheUp to this many items will be displayed in response to a 1740157184Sachepossible-completions call. After that, readline asks the user if she is sure 1741157184Sacheshe wants to see them all. The default value is 100. A negative value 1742157184Sacheindicates that Readline should never ask the user. 1743136644Sache@end deftypevar 1744136644Sache 1745136644Sache@deftypevar {int} rl_completion_append_character 1746136644SacheWhen a single completion alternative matches at the end of the command 1747136644Sacheline, this character is appended to the inserted completion text. The 1748136644Sachedefault is a space character (@samp{ }). Setting this to the null 1749136644Sachecharacter (@samp{\0}) prevents anything being appended automatically. 1750136644SacheThis can be changed in application-specific completion functions to 1751136644Sacheprovide the ``most sensible word separator character'' according to 1752136644Sachean application-specific command line syntax specification. 1753136644Sache@end deftypevar 1754136644Sache 1755136644Sache@deftypevar int rl_completion_suppress_append 1756136644SacheIf non-zero, @var{rl_completion_append_character} is not appended to 1757136644Sachematches at the end of the command line, as described above. 1758136644SacheIt is set to 0 before any application-specific completion function 1759136644Sacheis called, and may only be changed within such a function. 1760136644Sache@end deftypevar 1761136644Sache 1762136644Sache@deftypevar int rl_completion_quote_character 1763136644SacheWhen Readline is completing quoted text, as delimited by one of the 1764136644Sachecharacters in @var{rl_completer_quote_characters}, it sets this variable 1765136644Sacheto the quoting character found. 1766136644SacheThis is set before any application-specific completion function is called. 1767136644Sache@end deftypevar 1768136644Sache 1769136644Sache@deftypevar int rl_completion_suppress_quote 1770136644SacheIf non-zero, Readline does not append a matching quote character when 1771136644Sacheperforming completion on a quoted string. 1772136644SacheIt is set to 0 before any application-specific completion function 1773136644Sacheis called, and may only be changed within such a function. 1774136644Sache@end deftypevar 1775136644Sache 1776136644Sache@deftypevar int rl_completion_found_quote 1777136644SacheWhen Readline is completing quoted text, it sets this variable 1778136644Sacheto a non-zero value if the word being completed contains or is delimited 1779136644Sacheby any quoting characters, including backslashes. 1780136644SacheThis is set before any application-specific completion function is called. 1781136644Sache@end deftypevar 1782136644Sache 1783136644Sache@deftypevar int rl_completion_mark_symlink_dirs 1784136644SacheIf non-zero, a slash will be appended to completed filenames that are 1785136644Sachesymbolic links to directory names, subject to the value of the 1786136644Sacheuser-settable @var{mark-directories} variable. 1787136644SacheThis variable exists so that application-specific completion functions 1788136644Sachecan override the user's global preference (set via the 1789136644Sache@var{mark-symlinked-directories} Readline variable) if appropriate. 1790136644SacheThis variable is set to the user's preference before any 1791136644Sacheapplication-specific completion function is called, so unless that 1792136644Sachefunction modifies the value, the user's preferences are honored. 1793136644Sache@end deftypevar 1794136644Sache 1795136644Sache@deftypevar int rl_ignore_completion_duplicates 1796136644SacheIf non-zero, then duplicates in the matches are removed. 1797136644SacheThe default is 1. 1798136644Sache@end deftypevar 1799136644Sache 1800136644Sache@deftypevar int rl_filename_completion_desired 1801136644SacheNon-zero means that the results of the matches are to be treated as 1802136644Sachefilenames. This is @emph{always} zero when completion is attempted, 1803136644Sacheand can only be changed 1804136644Sachewithin an application-specific completion function. If it is set to a 1805136644Sachenon-zero value by such a function, directory names have a slash appended 1806136644Sacheand Readline attempts to quote completed filenames if they contain any 1807136644Sachecharacters in @code{rl_filename_quote_characters} and 1808136644Sache@code{rl_filename_quoting_desired} is set to a non-zero value. 1809136644Sache@end deftypevar 1810136644Sache 1811136644Sache@deftypevar int rl_filename_quoting_desired 1812136644SacheNon-zero means that the results of the matches are to be quoted using 1813136644Sachedouble quotes (or an application-specific quoting mechanism) if the 1814136644Sachecompleted filename contains any characters in 1815136644Sache@code{rl_filename_quote_chars}. This is @emph{always} non-zero 1816136644Sachewhen completion is attempted, and can only be changed within an 1817136644Sacheapplication-specific completion function. 1818136644SacheThe quoting is effected via a call to the function pointed to 1819136644Sacheby @code{rl_filename_quoting_function}. 1820136644Sache@end deftypevar 1821136644Sache 1822136644Sache@deftypevar int rl_attempted_completion_over 1823136644SacheIf an application-specific completion function assigned to 1824136644Sache@code{rl_attempted_completion_function} sets this variable to a non-zero 1825136644Sachevalue, Readline will not perform its default filename completion even 1826136644Sacheif the application's completion function returns no matches. 1827136644SacheIt should be set only by an application's completion function. 1828136644Sache@end deftypevar 1829136644Sache 1830136644Sache@deftypevar int rl_completion_type 1831136644SacheSet to a character describing the type of completion Readline is currently 1832136644Sacheattempting; see the description of @code{rl_complete_internal()} 1833136644Sache(@pxref{Completion Functions}) for the list of characters. 1834136644SacheThis is set to the appropriate value before any application-specific 1835136644Sachecompletion function is called, allowing such functions to present 1836136644Sachethe same interface as @code{rl_complete()}. 1837136644Sache@end deftypevar 1838136644Sache 1839136644Sache@deftypevar int rl_inhibit_completion 1840136644SacheIf this variable is non-zero, completion is inhibited. The completion 1841136644Sachecharacter will be inserted as any other bound to @code{self-insert}. 1842136644Sache@end deftypevar 1843136644Sache 1844136644Sache@node A Short Completion Example 1845136644Sache@subsection A Short Completion Example 1846136644Sache 1847136644SacheHere is a small application demonstrating the use of the GNU Readline 1848136644Sachelibrary. It is called @code{fileman}, and the source code resides in 1849136644Sache@file{examples/fileman.c}. This sample application provides 1850136644Sachecompletion of command names, line editing features, and access to the 1851136644Sachehistory list. 1852136644Sache 1853136644Sache@page 1854136644Sache@smallexample 1855136644Sache/* fileman.c -- A tiny application which demonstrates how to use the 1856136644Sache GNU Readline library. This application interactively allows users 1857136644Sache to manipulate files and their modes. */ 1858136644Sache 1859136644Sache#include <stdio.h> 1860136644Sache#include <sys/types.h> 1861136644Sache#include <sys/file.h> 1862136644Sache#include <sys/stat.h> 1863136644Sache#include <sys/errno.h> 1864136644Sache 1865136644Sache#include <readline/readline.h> 1866136644Sache#include <readline/history.h> 1867136644Sache 1868136644Sacheextern char *xmalloc (); 1869136644Sache 1870136644Sache/* The names of functions that actually do the manipulation. */ 1871136644Sacheint com_list __P((char *)); 1872136644Sacheint com_view __P((char *)); 1873136644Sacheint com_rename __P((char *)); 1874136644Sacheint com_stat __P((char *)); 1875136644Sacheint com_pwd __P((char *)); 1876136644Sacheint com_delete __P((char *)); 1877136644Sacheint com_help __P((char *)); 1878136644Sacheint com_cd __P((char *)); 1879136644Sacheint com_quit __P((char *)); 1880136644Sache 1881136644Sache/* A structure which contains information on the commands this program 1882136644Sache can understand. */ 1883136644Sache 1884136644Sachetypedef struct @{ 1885136644Sache char *name; /* User printable name of the function. */ 1886136644Sache rl_icpfunc_t *func; /* Function to call to do the job. */ 1887136644Sache char *doc; /* Documentation for this function. */ 1888136644Sache@} COMMAND; 1889136644Sache 1890136644SacheCOMMAND commands[] = @{ 1891136644Sache @{ "cd", com_cd, "Change to directory DIR" @}, 1892136644Sache @{ "delete", com_delete, "Delete FILE" @}, 1893136644Sache @{ "help", com_help, "Display this text" @}, 1894136644Sache @{ "?", com_help, "Synonym for `help'" @}, 1895136644Sache @{ "list", com_list, "List files in DIR" @}, 1896136644Sache @{ "ls", com_list, "Synonym for `list'" @}, 1897136644Sache @{ "pwd", com_pwd, "Print the current working directory" @}, 1898136644Sache @{ "quit", com_quit, "Quit using Fileman" @}, 1899136644Sache @{ "rename", com_rename, "Rename FILE to NEWNAME" @}, 1900136644Sache @{ "stat", com_stat, "Print out statistics on FILE" @}, 1901136644Sache @{ "view", com_view, "View the contents of FILE" @}, 1902136644Sache @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @} 1903136644Sache@}; 1904136644Sache 1905136644Sache/* Forward declarations. */ 1906136644Sachechar *stripwhite (); 1907136644SacheCOMMAND *find_command (); 1908136644Sache 1909136644Sache/* The name of this program, as taken from argv[0]. */ 1910136644Sachechar *progname; 1911136644Sache 1912136644Sache/* When non-zero, this means the user is done using this program. */ 1913136644Sacheint done; 1914136644Sache 1915136644Sachechar * 1916136644Sachedupstr (s) 1917136644Sache int s; 1918136644Sache@{ 1919136644Sache char *r; 1920136644Sache 1921136644Sache r = xmalloc (strlen (s) + 1); 1922136644Sache strcpy (r, s); 1923136644Sache return (r); 1924136644Sache@} 1925136644Sache 1926136644Sachemain (argc, argv) 1927136644Sache int argc; 1928136644Sache char **argv; 1929136644Sache@{ 1930136644Sache char *line, *s; 1931136644Sache 1932136644Sache progname = argv[0]; 1933136644Sache 1934136644Sache initialize_readline (); /* Bind our completer. */ 1935136644Sache 1936136644Sache /* Loop reading and executing lines until the user quits. */ 1937136644Sache for ( ; done == 0; ) 1938136644Sache @{ 1939136644Sache line = readline ("FileMan: "); 1940136644Sache 1941136644Sache if (!line) 1942136644Sache break; 1943136644Sache 1944136644Sache /* Remove leading and trailing whitespace from the line. 1945136644Sache Then, if there is anything left, add it to the history list 1946136644Sache and execute it. */ 1947136644Sache s = stripwhite (line); 1948136644Sache 1949136644Sache if (*s) 1950136644Sache @{ 1951136644Sache add_history (s); 1952136644Sache execute_line (s); 1953136644Sache @} 1954136644Sache 1955136644Sache free (line); 1956136644Sache @} 1957136644Sache exit (0); 1958136644Sache@} 1959136644Sache 1960136644Sache/* Execute a command line. */ 1961136644Sacheint 1962136644Sacheexecute_line (line) 1963136644Sache char *line; 1964136644Sache@{ 1965136644Sache register int i; 1966136644Sache COMMAND *command; 1967136644Sache char *word; 1968136644Sache 1969136644Sache /* Isolate the command word. */ 1970136644Sache i = 0; 1971136644Sache while (line[i] && whitespace (line[i])) 1972136644Sache i++; 1973136644Sache word = line + i; 1974136644Sache 1975136644Sache while (line[i] && !whitespace (line[i])) 1976136644Sache i++; 1977136644Sache 1978136644Sache if (line[i]) 1979136644Sache line[i++] = '\0'; 1980136644Sache 1981136644Sache command = find_command (word); 1982136644Sache 1983136644Sache if (!command) 1984136644Sache @{ 1985136644Sache fprintf (stderr, "%s: No such command for FileMan.\n", word); 1986136644Sache return (-1); 1987136644Sache @} 1988136644Sache 1989136644Sache /* Get argument to command, if any. */ 1990136644Sache while (whitespace (line[i])) 1991136644Sache i++; 1992136644Sache 1993136644Sache word = line + i; 1994136644Sache 1995136644Sache /* Call the function. */ 1996136644Sache return ((*(command->func)) (word)); 1997136644Sache@} 1998136644Sache 1999136644Sache/* Look up NAME as the name of a command, and return a pointer to that 2000136644Sache command. Return a NULL pointer if NAME isn't a command name. */ 2001136644SacheCOMMAND * 2002136644Sachefind_command (name) 2003136644Sache char *name; 2004136644Sache@{ 2005136644Sache register int i; 2006136644Sache 2007136644Sache for (i = 0; commands[i].name; i++) 2008136644Sache if (strcmp (name, commands[i].name) == 0) 2009136644Sache return (&commands[i]); 2010136644Sache 2011136644Sache return ((COMMAND *)NULL); 2012136644Sache@} 2013136644Sache 2014136644Sache/* Strip whitespace from the start and end of STRING. Return a pointer 2015136644Sache into STRING. */ 2016136644Sachechar * 2017136644Sachestripwhite (string) 2018136644Sache char *string; 2019136644Sache@{ 2020136644Sache register char *s, *t; 2021136644Sache 2022136644Sache for (s = string; whitespace (*s); s++) 2023136644Sache ; 2024136644Sache 2025136644Sache if (*s == 0) 2026136644Sache return (s); 2027136644Sache 2028136644Sache t = s + strlen (s) - 1; 2029136644Sache while (t > s && whitespace (*t)) 2030136644Sache t--; 2031136644Sache *++t = '\0'; 2032136644Sache 2033136644Sache return s; 2034136644Sache@} 2035136644Sache 2036136644Sache/* **************************************************************** */ 2037136644Sache/* */ 2038136644Sache/* Interface to Readline Completion */ 2039136644Sache/* */ 2040136644Sache/* **************************************************************** */ 2041136644Sache 2042136644Sachechar *command_generator __P((const char *, int)); 2043136644Sachechar **fileman_completion __P((const char *, int, int)); 2044136644Sache 2045136644Sache/* Tell the GNU Readline library how to complete. We want to try to 2046136644Sache complete on command names if this is the first word in the line, or 2047136644Sache on filenames if not. */ 2048136644Sacheinitialize_readline () 2049136644Sache@{ 2050136644Sache /* Allow conditional parsing of the ~/.inputrc file. */ 2051136644Sache rl_readline_name = "FileMan"; 2052136644Sache 2053136644Sache /* Tell the completer that we want a crack first. */ 2054136644Sache rl_attempted_completion_function = fileman_completion; 2055136644Sache@} 2056136644Sache 2057136644Sache/* Attempt to complete on the contents of TEXT. START and END 2058136644Sache bound the region of rl_line_buffer that contains the word to 2059136644Sache complete. TEXT is the word to complete. We can use the entire 2060136644Sache contents of rl_line_buffer in case we want to do some simple 2061136644Sache parsing. Returnthe array of matches, or NULL if there aren't any. */ 2062136644Sachechar ** 2063136644Sachefileman_completion (text, start, end) 2064136644Sache const char *text; 2065136644Sache int start, end; 2066136644Sache@{ 2067136644Sache char **matches; 2068136644Sache 2069136644Sache matches = (char **)NULL; 2070136644Sache 2071136644Sache /* If this word is at the start of the line, then it is a command 2072136644Sache to complete. Otherwise it is the name of a file in the current 2073136644Sache directory. */ 2074136644Sache if (start == 0) 2075136644Sache matches = rl_completion_matches (text, command_generator); 2076136644Sache 2077136644Sache return (matches); 2078136644Sache@} 2079136644Sache 2080136644Sache/* Generator function for command completion. STATE lets us 2081136644Sache know whether to start from scratch; without any state 2082136644Sache (i.e. STATE == 0), then we start at the top of the list. */ 2083136644Sachechar * 2084136644Sachecommand_generator (text, state) 2085136644Sache const char *text; 2086136644Sache int state; 2087136644Sache@{ 2088136644Sache static int list_index, len; 2089136644Sache char *name; 2090136644Sache 2091136644Sache /* If this is a new word to complete, initialize now. This 2092136644Sache includes saving the length of TEXT for efficiency, and 2093136644Sache initializing the index variable to 0. */ 2094136644Sache if (!state) 2095136644Sache @{ 2096136644Sache list_index = 0; 2097136644Sache len = strlen (text); 2098136644Sache @} 2099136644Sache 2100136644Sache /* Return the next name which partially matches from the 2101136644Sache command list. */ 2102136644Sache while (name = commands[list_index].name) 2103136644Sache @{ 2104136644Sache list_index++; 2105136644Sache 2106136644Sache if (strncmp (name, text, len) == 0) 2107136644Sache return (dupstr(name)); 2108136644Sache @} 2109136644Sache 2110136644Sache /* If no names matched, then return NULL. */ 2111136644Sache return ((char *)NULL); 2112136644Sache@} 2113136644Sache 2114136644Sache/* **************************************************************** */ 2115136644Sache/* */ 2116136644Sache/* FileMan Commands */ 2117136644Sache/* */ 2118136644Sache/* **************************************************************** */ 2119136644Sache 2120136644Sache/* String to pass to system (). This is for the LIST, VIEW and RENAME 2121136644Sache commands. */ 2122136644Sachestatic char syscom[1024]; 2123136644Sache 2124136644Sache/* List the file(s) named in arg. */ 2125136644Sachecom_list (arg) 2126136644Sache char *arg; 2127136644Sache@{ 2128136644Sache if (!arg) 2129136644Sache arg = ""; 2130136644Sache 2131136644Sache sprintf (syscom, "ls -FClg %s", arg); 2132136644Sache return (system (syscom)); 2133136644Sache@} 2134136644Sache 2135136644Sachecom_view (arg) 2136136644Sache char *arg; 2137136644Sache@{ 2138136644Sache if (!valid_argument ("view", arg)) 2139136644Sache return 1; 2140136644Sache 2141136644Sache sprintf (syscom, "more %s", arg); 2142136644Sache return (system (syscom)); 2143136644Sache@} 2144136644Sache 2145136644Sachecom_rename (arg) 2146136644Sache char *arg; 2147136644Sache@{ 2148136644Sache too_dangerous ("rename"); 2149136644Sache return (1); 2150136644Sache@} 2151136644Sache 2152136644Sachecom_stat (arg) 2153136644Sache char *arg; 2154136644Sache@{ 2155136644Sache struct stat finfo; 2156136644Sache 2157136644Sache if (!valid_argument ("stat", arg)) 2158136644Sache return (1); 2159136644Sache 2160136644Sache if (stat (arg, &finfo) == -1) 2161136644Sache @{ 2162136644Sache perror (arg); 2163136644Sache return (1); 2164136644Sache @} 2165136644Sache 2166136644Sache printf ("Statistics for `%s':\n", arg); 2167136644Sache 2168136644Sache printf ("%s has %d link%s, and is %d byte%s in length.\n", arg, 2169136644Sache finfo.st_nlink, 2170136644Sache (finfo.st_nlink == 1) ? "" : "s", 2171136644Sache finfo.st_size, 2172136644Sache (finfo.st_size == 1) ? "" : "s"); 2173136644Sache printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime)); 2174136644Sache printf (" Last access at: %s", ctime (&finfo.st_atime)); 2175136644Sache printf (" Last modified at: %s", ctime (&finfo.st_mtime)); 2176136644Sache return (0); 2177136644Sache@} 2178136644Sache 2179136644Sachecom_delete (arg) 2180136644Sache char *arg; 2181136644Sache@{ 2182136644Sache too_dangerous ("delete"); 2183136644Sache return (1); 2184136644Sache@} 2185136644Sache 2186136644Sache/* Print out help for ARG, or for all of the commands if ARG is 2187136644Sache not present. */ 2188136644Sachecom_help (arg) 2189136644Sache char *arg; 2190136644Sache@{ 2191136644Sache register int i; 2192136644Sache int printed = 0; 2193136644Sache 2194136644Sache for (i = 0; commands[i].name; i++) 2195136644Sache @{ 2196136644Sache if (!*arg || (strcmp (arg, commands[i].name) == 0)) 2197136644Sache @{ 2198136644Sache printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc); 2199136644Sache printed++; 2200136644Sache @} 2201136644Sache @} 2202136644Sache 2203136644Sache if (!printed) 2204136644Sache @{ 2205136644Sache printf ("No commands match `%s'. Possibilties are:\n", arg); 2206136644Sache 2207136644Sache for (i = 0; commands[i].name; i++) 2208136644Sache @{ 2209136644Sache /* Print in six columns. */ 2210136644Sache if (printed == 6) 2211136644Sache @{ 2212136644Sache printed = 0; 2213136644Sache printf ("\n"); 2214136644Sache @} 2215136644Sache 2216136644Sache printf ("%s\t", commands[i].name); 2217136644Sache printed++; 2218136644Sache @} 2219136644Sache 2220136644Sache if (printed) 2221136644Sache printf ("\n"); 2222136644Sache @} 2223136644Sache return (0); 2224136644Sache@} 2225136644Sache 2226136644Sache/* Change to the directory ARG. */ 2227136644Sachecom_cd (arg) 2228136644Sache char *arg; 2229136644Sache@{ 2230136644Sache if (chdir (arg) == -1) 2231136644Sache @{ 2232136644Sache perror (arg); 2233136644Sache return 1; 2234136644Sache @} 2235136644Sache 2236136644Sache com_pwd (""); 2237136644Sache return (0); 2238136644Sache@} 2239136644Sache 2240136644Sache/* Print out the current working directory. */ 2241136644Sachecom_pwd (ignore) 2242136644Sache char *ignore; 2243136644Sache@{ 2244136644Sache char dir[1024], *s; 2245136644Sache 2246136644Sache s = getcwd (dir, sizeof(dir) - 1); 2247136644Sache if (s == 0) 2248136644Sache @{ 2249136644Sache printf ("Error getting pwd: %s\n", dir); 2250136644Sache return 1; 2251136644Sache @} 2252136644Sache 2253136644Sache printf ("Current directory is %s\n", dir); 2254136644Sache return 0; 2255136644Sache@} 2256136644Sache 2257136644Sache/* The user wishes to quit using this program. Just set DONE 2258136644Sache non-zero. */ 2259136644Sachecom_quit (arg) 2260136644Sache char *arg; 2261136644Sache@{ 2262136644Sache done = 1; 2263136644Sache return (0); 2264136644Sache@} 2265136644Sache 2266136644Sache/* Function which tells you that you can't do this. */ 2267136644Sachetoo_dangerous (caller) 2268136644Sache char *caller; 2269136644Sache@{ 2270136644Sache fprintf (stderr, 2271157184Sache "%s: Too dangerous for me to distribute.\n", 2272136644Sache caller); 2273136644Sache fprintf (stderr, "Write it yourself.\n"); 2274136644Sache@} 2275136644Sache 2276136644Sache/* Return non-zero if ARG is a valid argument for CALLER, 2277136644Sache else print an error message and return zero. */ 2278136644Sacheint 2279136644Sachevalid_argument (caller, arg) 2280136644Sache char *caller, *arg; 2281136644Sache@{ 2282136644Sache if (!arg || !*arg) 2283136644Sache @{ 2284136644Sache fprintf (stderr, "%s: Argument required.\n", caller); 2285136644Sache return (0); 2286136644Sache @} 2287136644Sache 2288136644Sache return (1); 2289136644Sache@} 2290136644Sache@end smallexample 2291