GNU Info

(readline.info)Basic Behavior

---

Next: Custom Functions Up: Programming with GNU Readline

---

Enter node , (file) or (file)node

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 (Note: Custom Completers).