Alternate Interface
-------------------

   An alternate interface is available to plain `readline()'.  Some
applications need to interleave keyboard I/O with file, device, or
window system I/O, typically by using a main loop to `select()' on
various file descriptors.  To accomodate this need, readline can also
be invoked as a `callback' function from an event loop.  There are
functions available to make this easy.

 - Function: void rl_callback_handler_install (char *prompt, Vfunction
          *lhandler)
     Set up the terminal for readline I/O and display the initial
     expanded value of PROMPT.  Save the value of LHANDLER to use as a
     callback when a complete line of input has been entered.

 - Function: void rl_callback_read_char ()
     Whenever an application determines that keyboard input is
     available, it should call `rl_callback_read_char()', which will
     read the next character from the current input source.  If that
     character completes the line, `rl_callback_read_char' will invoke
     the LHANDLER function saved by `rl_callback_handler_install' to
     process the line.  `EOF' is  indicated by calling LHANDLER with a
     `NULL' line.

 - Function: void rl_callback_handler_remove ()
     Restore the terminal to its initial state and remove the line
     handler.  This may be called from within a callback as well as
     independently.

An Example
----------

   Here is a function which changes lowercase characters to their
uppercase equivalents, and uppercase characters to lowercase.  If this
function was bound to `M-c', then typing `M-c' would change the case of
the character under point.  Typing `M-1 0 M-c' would change the case of
the following 10 characters, leaving the cursor on the last character
changed.

     /* Invert the case of the COUNT following characters. */
     int
     invert_case_line (count, key)
          int count, key;
     {
       register int start, end, i;
     
       start = rl_point;
     
       if (rl_point >= rl_end)
         return (0);
     
       if (count < 0)
         {
           direction = -1;
           count = -count;
         }
       else
         direction = 1;
     
       /* Find the end of the range to modify. */
       end = start + (count * direction);
     
       /* Force it to be within range. */
       if (end > rl_end)
         end = rl_end;
       else if (end < 0)
         end = 0;
     
       if (start == end)
         return (0);
     
       if (start > end)
         {
           int temp = start;
           start = end;
           end = temp;
         }
     
       /* Tell readline that we are modifying the line, so it will save
          the undo information. */
       rl_modifying (start, end);
     
       for (i = start; i != end; i++)
         {
           if (uppercase_p (rl_line_buffer[i]))
             rl_line_buffer[i] = to_lower (rl_line_buffer[i]);
           else if (lowercase_p (rl_line_buffer[i]))
             rl_line_buffer[i] = to_upper (rl_line_buffer[i]);
         }
       /* Move point to on top of the last character changed. */
       rl_point = (direction == 1) ? end - 1 : start;
       return (0);
     }