2.4.12 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 (const char *prompt, rl_vcpfunc_t *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 function to call when a complete line of input has been entered. The function takes the text of the line as an argument.

Function: void rl_callback_read_char (void)

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. Before calling the lhandler function, the terminal settings are reset to the values they had before calling rl_callback_handler_install. If the lhandler function returns, the terminal settings are modified for Readline’s use again. EOF is indicated by calling lhandler with a NULL line.

Function: void rl_callback_handler_remove (void)

Restore the terminal to its initial state and remove the line handler. This may be called from within a callback as well as independently. If the lhandler installed by rl_callback_handler_install does not exit the program, either this function or the function referred to by the value of rl_deprep_term_function should be called before the program exits to reset the terminal settings.