Info Catalog readline: Programming with GNU Readline readline: Custom Functions

readline: Basic Behavior

 
 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: Programming with GNU Readline readline: Custom Functions