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 (see section Custom Completers).