DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

(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