Utility Functions Readline Convenience Functions

2.4.9: 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.

2.4.10: 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);
}

Utility Functions

Readline Convenience Functions