(readline.info.gz) Basic Behavior
Info Catalog
(readline.info.gz) Programming with GNU Readline
(readline.info.gz) Custom Functions
2.1 Basic Behavior
==================
Many programs provide a command line interface, such as `mail', `ftp',
and `sh'. For such programs, the default behaviour of Readline is
sufficient. This section describes how to use Readline in the simplest
way possible, perhaps to replace calls in your code to `gets()' or
`fgets()'.
The function `readline()' prints a prompt PROMPT and then reads and
returns a single line of text from the user. If PROMPT is `NULL' or
the empty string, no prompt is displayed. The line `readline' returns
is allocated with `malloc()'; the caller should `free()' the line when
it has finished with it. The declaration for `readline' in ANSI C is
`char *readline (const char *PROMPT);'
So, one might say
`char *line = readline ("Enter a line: ");'
in order to read a line of text from the user. The line returned
has the final newline removed, so only the text remains.
If `readline' encounters an `EOF' while reading the line, and the
line is empty at that point, then `(char *)NULL' is returned.
Otherwise, the line is ended just as if a newline had been typed.
If you want the user to be able to get at the line later, (with
<C-p> for example), you must call `add_history()' to save the line away
in a "history" list of such lines.
`add_history (line)';
For full details on the GNU History Library, see the associated manual.
It is preferable to avoid saving empty lines on the history list,
since users rarely have a burning need to reuse a blank line. Here is
a function which usefully replaces the standard `gets()' library
function, and has the advantage of no static buffer to overflow:
/* A static variable for holding the line. */
static char *line_read = (char *)NULL;
/* Read a string, and return a pointer to it.
Returns NULL on EOF. */
char *
rl_gets ()
{
/* If the buffer has already been allocated,
return the memory to the free pool. */
if (line_read)
{
free (line_read);
line_read = (char *)NULL;
}
/* Get a line from the user. */
line_read = readline ("");
/* If the line has any text in it,
save it on the history. */
if (line_read && *line_read)
add_history (line_read);
return (line_read);
}
This function gives the user the default behaviour of <TAB>
completion: completion on file names. If you do not want Readline to
complete on filenames, you can change the binding of the <TAB> key with
`rl_bind_key()'.
`int rl_bind_key (int KEY, rl_command_func_t *FUNCTION);'
`rl_bind_key()' takes two arguments: KEY is the character that you
want to bind, and FUNCTION is the address of the function to call when
KEY is pressed. Binding <TAB> to `rl_insert()' makes <TAB> insert
itself. `rl_bind_key()' returns non-zero if KEY is not a valid ASCII
character code (between 0 and 255).
Thus, to disable the default <TAB> behavior, the following suffices:
`rl_bind_key ('\t', rl_insert);'
This code should be executed once at the start of your program; you
might write a function called `initialize_readline()' which performs
this and other desired initializations, such as installing custom
completers ( Custom Completers).
Info Catalog
(readline.info.gz) Programming with GNU Readline
(readline.info.gz) Custom Functions
automatically generated byinfo2html