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
9to provide a command line interface.
10
11Copyright (C) 1988-2004 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.
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
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.
912@end deftypefun
913
914@deftypefun int rl_clear_message (void)
915Clear the message in the echo area.
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}.
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
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
1381@var{cols} columns.
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
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
1710possible-completions call. After that, we ask the user if she is sure
1711she wants to see them all. The default value is 100.
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,
2240 "%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
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
9to provide a command line interface.
10
11Copyright (C) 1988-2004 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.
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
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.
912@end deftypefun
913
914@deftypefun int rl_clear_message (void)
915Clear the message in the echo area.
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}.
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
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
1381@var{cols} columns.
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
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
1710possible-completions call. After that, we ask the user if she is sure
1711she wants to see them all. The default value is 100.
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,
2240 "%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