rltech.texinfo

UNIX下SH的实现源码

@deftypefun int rl_kill_text (int start, int end)
Copy the text between @var{start} and @var{end} in the current line
to the kill ring, appending or prepending to the last kill if the
last command was a kill command.  The text is deleted.
If @var{start} is less than @var{end},
the text is appended, otherwise prepended.  If the last command was
not a kill, a new kill ring slot is used.
@end deftypefun

@node Utility Functions
@subsection Utility Functions

@deftypefun int rl_read_key ()
Return the next character available.  This handles input inserted into
the input stream via @var{pending input} (@pxref{Readline Variables})
and @code{rl_stuff_char ()}, macros, and characters read from the keyboard.
@end deftypefun

@deftypefun int rl_getc (FILE *)
Return the next character available from the keyboard.
@end deftypefun

@deftypefun int rl_stuff_char (int c)
Insert @var{c} into the Readline input stream.  It will be "read"
before Readline attempts to read characters from the terminal with
@code{rl_read_key ()}.
@end deftypefun

@deftypefun int rl_extend_line_buffer (int len)
Ensure that @code{rl_line_buffer} has enough space to hold @var{len}
characters, possibly reallocating it if necessary.
@end deftypefun

@deftypefun int rl_initialize ()
Initialize or re-initialize Readline's internal state.
@end deftypefun

@deftypefun int rl_reset_terminal (char *terminal_name)
Reinitialize Readline's idea of the terminal settings using
@var{terminal_name} as the terminal type (e.g., @code{vt100}).
If @var{terminal_name} is NULL, the value of the @code{TERM}
environment variable is used.
@end deftypefun

@deftypefun int alphabetic (int c)
Return 1 if @var{c} is an alphabetic character.
@end deftypefun

@deftypefun int numeric (int c)
Return 1 if @var{c} is a numeric character.
@end deftypefun

@deftypefun int ding ()
Ring the terminal bell, obeying the setting of @code{bell-style}.
@end deftypefun

@deftypefun void rl_display_match_list (char **matches, int len, int max)
A convenience function for displaying a list of strings in
columnar format on Readline's output stream.  @code{matches} is the list
of strings, in argv format, such as a list of completion matches.
@code{len} is the number of strings in @code{matches}, and @code{max}
is the length of the longest string in @code{matches}.  This function uses
the setting of @code{print-completions-horizontally} to select how the
matches are displayed (@pxref{Readline Init File Syntax}).
@end deftypefun

The following are implemented as macros, defined in @code{chartypes.h}.

@deftypefun int uppercase_p (int c)
Return 1 if @var{c} is an uppercase alphabetic character.
@end deftypefun

@deftypefun int lowercase_p (int c)
Return 1 if @var{c} is a lowercase alphabetic character.
@end deftypefun

@deftypefun int digit_p (int c)
Return 1 if @var{c} is a numeric character.
@end deftypefun

@deftypefun int to_upper (int c)
If @var{c} is a lowercase alphabetic character, return the corresponding
uppercase character.
@end deftypefun

@deftypefun int to_lower (int c)
If @var{c} is an uppercase alphabetic character, return the corresponding
lowercase character.
@end deftypefun

@deftypefun int digit_value (int c)
If @var{c} is a number, return the value it represents.
@end deftypefun

@node Alternate Interface
@subsection Alternate Interface

An alternate interface is available to plain @code{readline()}.  Some
applications need to interleave keyboard I/O with file, device, or
window system I/O, typically by using a main loop to @code{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.

@deftypefun void rl_callback_handler_install (char *prompt, Vfunction *lhandler)
Set up the terminal for readline I/O and display the initial
expanded value of @var{prompt}.  Save the value of @var{lhandler} to
use as a callback when a complete line of input has been entered.
@end deftypefun

@deftypefun void rl_callback_read_char ()
Whenever an application determines that keyboard input is available, it
should call @code{rl_callback_read_char()}, which will read the next
character from the current input source.  If that character completes the
line, @code{rl_callback_read_char} will invoke the @var{lhandler}
function saved by @code{rl_callback_handler_install} to process the
line.  @code{EOF} is  indicated by calling @var{lhandler} with a
@code{NULL} line.
@end deftypefun

@deftypefun 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.
@end deftypefun

@subsection 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 @samp{M-c}, then typing @samp{M-c} would
change the case of the character under point.  Typing @samp{M-1 0 M-c}
would change the case of the following 10 characters, leaving the cursor on
the last character changed.

@example
/* 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);
@}
@end example

@node Readline Signal Handling
@section Readline Signal Handling

Signals are asynchronous events sent to a process by the Unix kernel,
sometimes on behalf of another process.  They are intended to indicate
exceptional events, like a user pressing the interrupt key on his
terminal, or a network connection being broken.  There is a class of
signals that can be sent to the process currently reading input from
the keyboard.  Since Readline changes the terminal attributes when it
is called, it needs to perform special processing when a signal is
received to restore the terminal to a sane state, or provide application
writers with functions to do so manually.

Readline contains an internal signal handler that is installed for a
number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM},
@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}).
When one of these signals is received, the signal handler
will reset the terminal attributes to those that were in effect before
@code{readline ()} was called, reset the signal handling to what it was
before @code{readline ()} was called, and resend the signal to the calling
application.
If and when the calling application's signal handler returns, Readline
will reinitialize the terminal and continue to accept input.
When a @code{SIGINT} is received, the Readline signal handler performs
some additional work, which will cause any partially-entered line to be
aborted (see the description of @code{rl_free_line_state ()}).

There is an additional Readline signal handler, for @code{SIGWINCH}, which
the kernel sends to a process whenever the terminal's size changes (for
example, if a user resizes an @code{xterm}).  The Readline @code{SIGWINCH}
handler updates Readline's internal screen size state, and then calls any
@code{SIGWINCH} signal handler the calling application has installed. 
Readline calls the application's @code{SIGWINCH} signal handler without
resetting the terminal to its original state.  If the application's signal
handler does more than update its idea of the terminal size and return (for
example, a @code{longjmp} back to a main processing loop), it @emph{must}
call @code{rl_cleanup_after_signal ()} (described below), to restore the
terminal state. 

Readline provides two variables that allow application writers to
control whether or not it will catch certain signals and act on them
when they are received.  It is important that applications change the
values of these variables only when calling @code{readline ()}, not in
a signal handler, so Readline's internal signal state is not corrupted.

@deftypevar int rl_catch_signals
If this variable is non-zero, Readline will install signal handlers for
@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGALRM},
@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}.

The default value of @code{rl_catch_signals} is 1.
@end deftypevar

@deftypevar int rl_catch_sigwinch
If this variable is non-zero, Readline will install a signal handler for
@code{SIGWINCH}.

The default value of @code{rl_catch_sigwinch} is 1.
@end deftypevar

If an application does not wish to have Readline catch any signals, or
to handle signals other than those Readline catches (@code{SIGHUP},
for example), 
Readline provides convenience functions to do the necessary terminal
and internal state cleanup upon receipt of a signal.

@deftypefun void rl_cleanup_after_signal (void)
This function will reset the state of the terminal to what it was before
@code{readline ()} was called, and remove the Readline signal handlers for
all signals, depending on the values of @code{rl_catch_signals} and
@code{rl_catch_sigwinch}.
@end deftypefun

@deftypefun void rl_free_line_state (void)
This will free any partial state associated with the current input line
(undo information, any partial history entry, any partially-entered
keyboard macro, and any partially-entered numeric argument).  This
should be called before @code{rl_cleanup_after_signal ()}.  The
Readline signal handler for @code{SIGINT} calls this to abort the
current input line.
@end deftypefun

@deftypefun void rl_reset_after_signal (void)
This will reinitialize the terminal and reinstall any Readline signal
handlers, depending on the values of @code{rl_catch_signals} and
@code{rl_catch_sigwinch}.
@end deftypefun

If an application does not wish Readline to catch @code{SIGWINCH}, it may
call @code{rl_resize_terminal ()} to force Readline to update its idea of
the terminal size when a @code{SIGWINCH} is received.

@deftypefun void rl_resize_terminal (void)
Update Readline's internal screen size.
@end deftypefun

The following functions install and remove Readline's signal handlers.

@deftypefun int rl_set_signals (void)
Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT},
@code{SIGTERM}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN},
@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of
@code{rl_catch_signals} and @code{rl_catch_sigwinch}.
@end deftypefun

@deftypefun int rl_clear_signals (void)
Remove all of the Readline signal handlers installed by
@code{rl_set_signals ()}.
@end deftypefun

@node Custom Completers
@section Custom Completers

Typically, a program that reads commands from the user has a way of
disambiguating commands and data.  If your program is one of these, then
it can provide completion for commands, data, or both.
The following sections describe how your program and Readline
cooperate to provide this service.

@menu
* How Completing Works::	The logic used to do completion.
* Completion Functions::	Functions provided by Readline.
* Completion Variables::	Variables which control completion.
* A Short Completion Example::	An example of writing completer subroutines.
@end menu

@node How Completing Works
@subsection How Completing Works

In order to complete some text, the full list of possible completions
must be available.  That is, it is not possible to accurately
expand a partial word without knowing all of the possible words
which make sense in that context.  The Readline library provides
the user interface to completion, and two of the most common
completion functions:  filename and username.  For completing other types
of text, you must write your own completion function.  This section
describes exactly what such functions must do, and provides an example.

There are three major functions used to perform completion:

@enumerate
@item
The user-interface function @code{rl_complete ()}.  This function is
called with the same arguments as other Readline
functions intended for interactive use:  @var{count} and
@var{invoking_key}.  It isolates the word to be completed and calls
@code{completion_matches ()} to generate a list of possible completions.
It then either lists the possible completions, inserts the possible
completions, or actually performs the
completion, depending on which behavior is desired.

@item
The internal function @code{completion_matches ()} uses your
@dfn{generator} function to generate the list of possible matches, and
then returns the array of these matches.  You should place the address
of your generator function in @code{rl_completion_entry_function}.

@item
The generator function is called repeatedly from