rltech.texi

android-w.song.android.widget

      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 (_rl_uppercase_p (rl_line_buffer[i]))
        rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
      else if (_rl_lowercase_p (rl_line_buffer[i]))
        rl_line_buffer[i] = _rl_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 such a signal is received in order 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()} below).

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 information, 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()} or @code{rl_set_screen_size()} to force
Readline to update its idea of the terminal size when a @code{SIGWINCH}
is received.

@deftypefun void rl_echo_signal_char (int sig)
If an application wishes to install its own signal handlers, but still
have readline display characters that generate signals, calling this
function with @var{sig} set to @code{SIGINT}, @code{SIGQUIT}, or
@code{SIGTSTP} will display the character generating that signal.
@end deftypefun

@deftypefun void rl_resize_terminal (void)
Update Readline's internal screen size by reading values from the kernel.
@end deftypefun

@deftypefun void rl_set_screen_size (int rows, int cols)
Set Readline's idea of the terminal size to @var{rows} rows and
@var{cols} columns.  If either @var{rows} or @var{columns} is less than
or equal to 0, Readline's idea of that terminal dimension is unchanged.
@end deftypefun

If an application does not want to install a @code{SIGWINCH} handler, but
is still interested in the screen dimensions, Readline's idea of the screen
size may be queried.

@deftypefun void rl_get_screen_size (int *rows, int *cols)
Return Readline's idea of the terminal's size in the
variables pointed to by the arguments.
@end deftypefun

@deftypefun void rl_reset_screen_size (void)
Cause Readline to reobtain the screen size and recalculate its dimensions.
@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
@cindex application-specific completion functions

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 bindable Readline functions:
@var{count} and @var{invoking_key}.
It isolates the word to be completed and calls
@code{rl_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{rl_completion_matches()} uses an
application-supplied @dfn{generator} function to generate the list of
possible matches, and then returns the array of these matches.
The caller should place the address of its generator function in
@code{rl_completion_entry_function}.

@item
The generator function is called repeatedly from
@code{rl_completion_matches()}, returning a string each time.  The
arguments to the generator function are @var{text} and @var{state}.
@var{text} is the partial word to be completed.  @var{state} is zero the
first time the function is called, allowing the generator to perform
any necessary initialization, and a positive non-zero integer for
each subsequent call.  The generator function returns
@code{(char *)NULL} to inform @code{rl_completion_matches()} that there are
no more possibilities left.  Usually the generator function computes the
list of possible completions when @var{state} is zero, and returns them
one at a time on subsequent calls.  Each string the generator function
returns as a match must be allocated with @code{malloc()}; Readline
frees the strings when it has finished with them.
Such a generator function is referred to as an
@dfn{application-specific completion function}.

@end enumerate

@deftypefun int rl_complete (int ignore, int invoking_key)
Complete the word at or before point.  You have supplied the function
that does the initial simple matching selection algorithm (see
@code{rl_completion_matches()}).  The default is to do filename completion.
@end deftypefun

@deftypevar {rl_compentry_func_t *} rl_completion_entry_function
This is a pointer to the generator function for
@code{rl_completion_matches()}.
If the value of @code{rl_completion_entry_function} is
@code{NULL} then the default filename generator
function, @code{rl_filename_completion_function()}, is used.
An @dfn{application-specific completion function} is a function whose
address is assigned to @code{rl_completion_entry_function} and whose
return values are used to  generate possible completions.
@end deftypevar

@node Completion Functions
@subsection Completion Functions

Here is the complete list of callable completion functions present in
Readline.

@deftypefun int rl_complete_internal (int what_to_do)
Complete the word at or before point.  @var{what_to_do} says what to do
with the completion.  A value of @samp{?} means list the possible
completions.  @samp{TAB} means do standard completion.  @samp{*} means
insert all of the possible completions.  @samp{!} means to display
all of the possible completions, if there is more than one, as well as
performing partial completion.  @samp{@@} is similar to @samp{!}, but
possible completions are not listed if the possible completions share
a common prefix.
@end deftypefun

@deftypefun int rl_complete (int ignore, int invoking_key)
Complete the word at or before point.  You have supplied the function
that does the initial simple matching selection algorithm (see
@code{rl_completion_matches()} and @code{rl_completion_entry_function}).
The default is to do filename
completion.  This calls @code{rl_complete_internal()} with an
argument depending on @var{invoking_key}.
@end deftypefun

@deftypefun int rl_possible_completions (int count, int invoking_key)
List the possible completions.  See description of @code{rl_complete
()}.  This calls @code{rl_complete_internal()} with an argument of
@samp{?}.
@end deftypefun

@deftypefun int rl_insert_completions (int count, int invoking_key)
Insert the list of possible completions into the line, deleting the
partially-completed word.  See description of @code{rl_complete()}.
This calls @code{rl_complete_internal()} with an argument of @samp{*}.
@end deftypefun

@deftypefun int rl_completion_mode (rl_command_func_t *cfunc)
Returns the apppriate value to pass to @code{rl_complete_internal()}
depending on whether @var{cfunc} was called twice in succession and
the values of the @code{show-all-if-ambiguous} and
@code{show-all-if-unmodified} variables.
Application-specific completion functions may use this function to present
the same interface as @code{rl_complete()}.
@end deftypefun

@deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func)
Returns an array of strings which is a list of completions for
@var{text}.  If there are no completions, returns @code{NULL}.
The first entry in the returned array is the substitution for @var{text}.
The remaining entries are the possible completions.  The array is
terminated with a @code{NULL} pointer.

@var{entry_func} is a function of two args, and returns a
@code{char *}.  The first argument is @var{text}.  The second is a
state argument; it is zero on the first call, and non-zero on subsequent
calls.  @var{entry_func} returns a @code{NULL}  pointer to the caller
when there are no more matches.
@end deftypefun

@deftypefun {char *} rl_filename_completion_function (const char *text, int state)
A generator function for filename completion in the general case.
@var{text} is a partial filename.
The Bash source is a useful reference for writing application-specific
completion functions (the Bash completion functions call this and other
Readline functions).
@end deftypefun

@deftypefun {char *} rl_username_completion_function (const char *text, int state)
A completion generator for usernames.  @var{text} contains a partial
username preceded by a random character (usually @samp{~}).  As with all
completion generators, @var{state} is zero on the first call and non-zero
for subsequent calls.
@end deftypefun

@node Completion Variables
@subsection Completion Variables

@deftypevar {rl_compentry_func_t *} rl_completion_entry_function
A pointer to the generator function for @code{rl_completion_matches()}.
@code{NULL} means to use @code{rl_filename_completion_function()},
the default filename completer.
@end deftypevar

@deftypevar {rl_completion_func_t *} rl_attempted_completion_function