| rltech.texi (136644) | rltech.texi (157184) |
|---|---|
| 1@comment %**start of header (This is for running Texinfo on a region.) 2@setfilename rltech.info 3@comment %**end of header (This is for running Texinfo on a region.) 4@setchapternewpage odd 5 6@ifinfo 7This document describes the GNU Readline Library, a utility for aiding | 1@comment %**start of header (This is for running Texinfo on a region.) 2@setfilename rltech.info 3@comment %**end of header (This is for running Texinfo on a region.) 4@setchapternewpage odd 5 6@ifinfo 7This document describes the GNU Readline Library, a utility for aiding |
| 8in the consitency of user interface across discrete programs that need | 8in the consistency of user interface across discrete programs that need |
| 9to provide a command line interface. 10 | 9to provide a command line interface. 10 |
| 11Copyright (C) 1988-2004 Free Software Foundation, Inc. | 11Copyright (C) 1988-2005 Free Software Foundation, Inc. |
| 12 13Permission is granted to make and distribute verbatim copies of 14this manual provided the copyright notice and this permission notice 15pare preserved on all copies. 16 17@ignore 18Permission is granted to process this file through TeX and print the 19results, provided the printed document carries copying permission --- 259 unchanged lines hidden (view full) --- 279ignore it. In general, if a 280function uses the numeric argument as a repeat count, it should be able 281to do something useful with both negative and positive arguments. 282At the very least, it should be aware that it can be passed a 283negative argument. 284 285A command function should return 0 if its action completes successfully, 286and a non-zero value if some error occurs. | 12 13Permission is granted to make and distribute verbatim copies of 14this manual provided the copyright notice and this permission notice 15pare preserved on all copies. 16 17@ignore 18Permission is granted to process this file through TeX and print the 19results, provided the printed document carries copying permission --- 259 unchanged lines hidden (view full) --- 279ignore it. In general, if a 280function uses the numeric argument as a repeat count, it should be able 281to do something useful with both negative and positive arguments. 282At the very least, it should be aware that it can be passed a 283negative argument. 284 285A command function should return 0 if its action completes successfully, 286and a non-zero value if some error occurs. |
| 287This is the convention obeyed by all of the builtin Readline bindable 288command functions. |
|
| 287 288@node Readline Variables 289@section Readline Variables 290 291These variables are available to function writers. 292 293@deftypevar {char *} rl_line_buffer 294This is the line gathered so far. You are welcome to modify the --- 98 unchanged lines hidden (view full) --- 393If @code{NULL}, Readline defaults to @var{stdin}. 394@end deftypevar 395 396@deftypevar {FILE *} rl_outstream 397The stdio stream to which Readline performs output. 398If @code{NULL}, Readline defaults to @var{stdout}. 399@end deftypevar 400 | 289 290@node Readline Variables 291@section Readline Variables 292 293These variables are available to function writers. 294 295@deftypevar {char *} rl_line_buffer 296This is the line gathered so far. You are welcome to modify the --- 98 unchanged lines hidden (view full) --- 395If @code{NULL}, Readline defaults to @var{stdin}. 396@end deftypevar 397 398@deftypevar {FILE *} rl_outstream 399The stdio stream to which Readline performs output. 400If @code{NULL}, Readline defaults to @var{stdout}. 401@end deftypevar 402 |
| 403@deftypevar int rl_prefer_env_winsize 404If non-zero, Readline gives values found in the @env{LINES} and 405@env{COLUMNS} environment variables greater precedence than values fetched 406from the kernel when computing the screen dimensions. 407@end deftypevar 408 |
|
| 401@deftypevar {rl_command_func_t *} rl_last_func 402The address of the last command function Readline executed. May be used to 403test whether or not a function is being executed twice in succession, for 404example. 405@end deftypevar 406 407@deftypevar {rl_hook_func_t *} rl_startup_hook 408If non-zero, this is the address of a function to call just --- 495 unchanged lines hidden (view full) --- 904@end deftypefun 905 906@deftypefun int rl_message (const char *, @dots{}) 907The arguments are a format string as would be supplied to @code{printf}, 908possibly containing conversion specifications such as @samp{%d}, and 909any additional arguments necessary to satisfy the conversion specifications. 910The resulting string is displayed in the @dfn{echo area}. The echo area 911is also used to display numeric arguments and search strings. | 409@deftypevar {rl_command_func_t *} rl_last_func 410The address of the last command function Readline executed. May be used to 411test whether or not a function is being executed twice in succession, for 412example. 413@end deftypevar 414 415@deftypevar {rl_hook_func_t *} rl_startup_hook 416If non-zero, this is the address of a function to call just --- 495 unchanged lines hidden (view full) --- 912@end deftypefun 913 914@deftypefun int rl_message (const char *, @dots{}) 915The arguments are a format string as would be supplied to @code{printf}, 916possibly containing conversion specifications such as @samp{%d}, and 917any additional arguments necessary to satisfy the conversion specifications. 918The resulting string is displayed in the @dfn{echo area}. The echo area 919is also used to display numeric arguments and search strings. |
| 920You should call @code{rl_save_prompt} to save the prompt information 921before calling this function. |
|
| 912@end deftypefun 913 914@deftypefun int rl_clear_message (void) | 922@end deftypefun 923 924@deftypefun int rl_clear_message (void) |
| 915Clear the message in the echo area. | 925Clear the message in the echo area. If the prompt was saved with a call to 926@code{rl_save_prompt} before the last call to @code{rl_message}, 927call @code{rl_restore_prompt} before calling this function. |
| 916@end deftypefun 917 918@deftypefun void rl_save_prompt (void) 919Save the local Readline prompt display state in preparation for 920displaying a new message in the message area with @code{rl_message()}. 921@end deftypefun 922 923@deftypefun void rl_restore_prompt (void) 924Restore the local Readline prompt display state saved by the most 925recent call to @code{rl_save_prompt}. | 928@end deftypefun 929 930@deftypefun void rl_save_prompt (void) 931Save the local Readline prompt display state in preparation for 932displaying a new message in the message area with @code{rl_message()}. 933@end deftypefun 934 935@deftypefun void rl_restore_prompt (void) 936Restore the local Readline prompt display state saved by the most 937recent call to @code{rl_save_prompt}. |
| 938if @code{rl_save_prompt} was called to save the prompt before a call 939to @code{rl_message}, this function should be called before the 940corresponding call to @code{rl_clear_message}. |
|
| 926@end deftypefun 927 928@deftypefun int rl_expand_prompt (char *prompt) 929Expand any special character sequences in @var{prompt} and set up the 930local Readline prompt redisplay variables. 931This function is called by @code{readline()}. It may also be called to 932expand the primary prompt if the @code{rl_on_new_line_with_prompt()} 933function or @code{rl_already_prompted} variable is used. --- 210 unchanged lines hidden (view full) --- 1144 1145@deftypefun int rl_variable_bind (const char *variable, const char *value) 1146Make the Readline variable @var{variable} have @var{value}. 1147This behaves as if the readline command 1148@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc} 1149file (@pxref{Readline Init File Syntax}). 1150@end deftypefun 1151 | 941@end deftypefun 942 943@deftypefun int rl_expand_prompt (char *prompt) 944Expand any special character sequences in @var{prompt} and set up the 945local Readline prompt redisplay variables. 946This function is called by @code{readline()}. It may also be called to 947expand the primary prompt if the @code{rl_on_new_line_with_prompt()} 948function or @code{rl_already_prompted} variable is used. --- 210 unchanged lines hidden (view full) --- 1159 1160@deftypefun int rl_variable_bind (const char *variable, const char *value) 1161Make the Readline variable @var{variable} have @var{value}. 1162This behaves as if the readline command 1163@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc} 1164file (@pxref{Readline Init File Syntax}). 1165@end deftypefun 1166 |
| 1167@deftypefun {char *} rl_variable_value (const char *variable) 1168Return a string representing the value of the Readline variable @var{variable}. 1169For boolean variables, this string is either @samp{on} or @samp{off}. 1170@end deftypefun 1171 |
|
| 1152@deftypefun void rl_variable_dumper (int readable) 1153Print the readline variable names and their current values 1154to @code{rl_outstream}. 1155If @var{readable} is non-zero, the list is formatted in such a way 1156that it can be made part of an @code{inputrc} file and re-read. 1157@end deftypefun 1158 1159@deftypefun int rl_set_paren_blink_timeout (int u) --- 213 unchanged lines hidden (view full) --- 1373is received. 1374 1375@deftypefun void rl_resize_terminal (void) 1376Update Readline's internal screen size by reading values from the kernel. 1377@end deftypefun 1378 1379@deftypefun void rl_set_screen_size (int rows, int cols) 1380Set Readline's idea of the terminal size to @var{rows} rows and | 1172@deftypefun void rl_variable_dumper (int readable) 1173Print the readline variable names and their current values 1174to @code{rl_outstream}. 1175If @var{readable} is non-zero, the list is formatted in such a way 1176that it can be made part of an @code{inputrc} file and re-read. 1177@end deftypefun 1178 1179@deftypefun int rl_set_paren_blink_timeout (int u) --- 213 unchanged lines hidden (view full) --- 1393is received. 1394 1395@deftypefun void rl_resize_terminal (void) 1396Update Readline's internal screen size by reading values from the kernel. 1397@end deftypefun 1398 1399@deftypefun void rl_set_screen_size (int rows, int cols) 1400Set Readline's idea of the terminal size to @var{rows} rows and |
| 1381@var{cols} columns. | 1401@var{cols} columns. If either @var{rows} or @var{columns} is less than 1402or equal to 0, Readline's idea of that terminal dimension is unchanged. |
| 1382@end deftypefun 1383 1384If an application does not want to install a @code{SIGWINCH} handler, but 1385is still interested in the screen dimensions, Readline's idea of the screen 1386size may be queried. 1387 1388@deftypefun void rl_get_screen_size (int *rows, int *cols) 1389Return Readline's idea of the terminal's size in the 1390variables pointed to by the arguments. 1391@end deftypefun 1392 | 1403@end deftypefun 1404 1405If an application does not want to install a @code{SIGWINCH} handler, but 1406is still interested in the screen dimensions, Readline's idea of the screen 1407size may be queried. 1408 1409@deftypefun void rl_get_screen_size (int *rows, int *cols) 1410Return Readline's idea of the terminal's size in the 1411variables pointed to by the arguments. 1412@end deftypefun 1413 |
| 1414@deftypefun void rl_reset_screen_size (void) 1415Cause Readline to reobtain the screen size and recalculate its dimensions. 1416@end deftypefun 1417 |
|
| 1393The following functions install and remove Readline's signal handlers. 1394 1395@deftypefun int rl_set_signals (void) 1396Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT}, 1397@code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, 1398@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of 1399@code{rl_catch_signals} and @code{rl_catch_sigwinch}. 1400@end deftypefun --- 301 unchanged lines hidden (view full) --- 1702left in @var{text} when it is passed to the completion function. 1703Programs can use this to help determine what kind of completing to do. 1704For instance, Bash sets this variable to "$@@" so that it can complete 1705shell variables and hostnames. 1706@end deftypevar 1707 1708@deftypevar int rl_completion_query_items 1709Up to this many items will be displayed in response to a | 1418The following functions install and remove Readline's signal handlers. 1419 1420@deftypefun int rl_set_signals (void) 1421Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT}, 1422@code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, 1423@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of 1424@code{rl_catch_signals} and @code{rl_catch_sigwinch}. 1425@end deftypefun --- 301 unchanged lines hidden (view full) --- 1727left in @var{text} when it is passed to the completion function. 1728Programs can use this to help determine what kind of completing to do. 1729For instance, Bash sets this variable to "$@@" so that it can complete 1730shell variables and hostnames. 1731@end deftypevar 1732 1733@deftypevar int rl_completion_query_items 1734Up to this many items will be displayed in response to a |
| 1710possible-completions call. After that, we ask the user if she is sure 1711she wants to see them all. The default value is 100. | 1735possible-completions call. After that, readline asks the user if she is sure 1736she wants to see them all. The default value is 100. A negative value 1737indicates that Readline should never ask the user. |
| 1712@end deftypevar 1713 1714@deftypevar {int} rl_completion_append_character 1715When a single completion alternative matches at the end of the command 1716line, this character is appended to the inserted completion text. The 1717default is a space character (@samp{ }). Setting this to the null 1718character (@samp{\0}) prevents anything being appended automatically. 1719This can be changed in application-specific completion functions to --- 512 unchanged lines hidden (view full) --- 2232 return (0); 2233@} 2234 2235/* Function which tells you that you can't do this. */ 2236too_dangerous (caller) 2237 char *caller; 2238@{ 2239 fprintf (stderr, | 1738@end deftypevar 1739 1740@deftypevar {int} rl_completion_append_character 1741When a single completion alternative matches at the end of the command 1742line, this character is appended to the inserted completion text. The 1743default is a space character (@samp{ }). Setting this to the null 1744character (@samp{\0}) prevents anything being appended automatically. 1745This can be changed in application-specific completion functions to --- 512 unchanged lines hidden (view full) --- 2258 return (0); 2259@} 2260 2261/* Function which tells you that you can't do this. */ 2262too_dangerous (caller) 2263 char *caller; 2264@{ 2265 fprintf (stderr, |
| 2240 "%s: Too dangerous for me to distribute.\n" | 2266 "%s: Too dangerous for me to distribute.\n", |
| 2241 caller); 2242 fprintf (stderr, "Write it yourself.\n"); 2243@} 2244 2245/* Return non-zero if ARG is a valid argument for CALLER, 2246 else print an error message and return zero. */ 2247int 2248valid_argument (caller, arg) 2249 char *caller, *arg; 2250@{ 2251 if (!arg || !*arg) 2252 @{ 2253 fprintf (stderr, "%s: Argument required.\n", caller); 2254 return (0); 2255 @} 2256 2257 return (1); 2258@} 2259@end smallexample | 2267 caller); 2268 fprintf (stderr, "Write it yourself.\n"); 2269@} 2270 2271/* Return non-zero if ARG is a valid argument for CALLER, 2272 else print an error message and return zero. */ 2273int 2274valid_argument (caller, arg) 2275 char *caller, *arg; 2276@{ 2277 if (!arg || !*arg) 2278 @{ 2279 fprintf (stderr, "%s: Argument required.\n", caller); 2280 return (0); 2281 @} 2282 2283 return (1); 2284@} 2285@end smallexample |