rltech.texinfo

早期freebsd实现

@code{rl_delete_text ()}, but they could be direct calls to
@code{rl_add_undo ()}.
@end defun

@defun rl_end_undo_group ()
Closes the current undo group started with @code{rl_begin_undo_group
()}.  There should be exactly one call to @code{rl_end_undo_group ()}
for every call to @code{rl_begin_undo_group ()}.
@end defun

Finally, if you neither insert nor delete text, but directly modify the
existing text (e.g. change its case), you call @code{rl_modifying ()}
once, just before you modify the text.  You must supply the indices of
the text range that you are going to modify.

@defun rl_modifying (int start, int end)
Tell Readline to save the text between @var{start} and @var{end} as a
single undo unit.  It is assumed that subsequent to this call you will
modify that range of text in some way.
@end defun

@subsection An Example

Here is a function which changes lowercase characters to the uppercase
equivalents, and uppercase characters to the lowercase equivalents.  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{10 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. */
invert_case_line (count, key)
     int count, key;
@{
  register int start, end;

  start = rl_point;

  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 = -1;

  if (start > end)
    @{
      int temp = start;
      start = end;
      end = temp;
    @}

  if (start == end)
    return;

  /* Tell readline that we are modifying the line, so save the undo
     information. */
  rl_modifying (start, end);

  for (; start != end; start += direction)
    @{
      if (uppercase_p (rl_line_buffer[start]))
        rl_line_buffer[start] = to_lower (rl_line_buffer[start]);
      else if (lowercase_p (rl_line_buffer[start]))
        rl_line_buffer[start] = to_upper (rl_line_buffer[start]);
    @}
  /* Move point to on top of the last character changed. */
  rl_point = end - direction;
@}
@end example

@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 either commands, or data, or both commands
and data.  The following sections describe how your program and Readline
cooperate to provide this service to end users.

@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 to say, it is not possible to accurately
expand a partial word without knowing what all of the possible words
that make sense in that context are.  The GNU Readline library provides
the user interface to completion, and additionally, 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 those functions must do, and provides an example
function.

There are three major functions used to perform completion:

@enumerate
@item
The user-interface function @code{rl_complete ()}.  This function is
called interactively with the same calling conventions as other
functions in readline intended for interactive use; i.e. @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 or actually performs the
completion, depending on which behaviour 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
@code{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, and a positive non-zero integer for
each subsequent call.  When the generator function returns @code{(char
*)NULL} this signals @code{completion_matches ()} that there are no more
possibilities left.

@end enumerate

@defun 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{completion_matches ()}).  The default is to do filename completion.
@end defun

Note that @code{rl_complete ()} has the identical calling conventions as
any other key-invokable function; this is because by default it is bound
to the @samp{TAB} key.

@defvar {Function *rl_completion_entry_function}
This is a pointer to the generator function for @code{completion_matches
()}.  If the value of @code{rl_completion_entry_function} is
@code{(Function *)NULL} then the default filename generator function is
used, namely @code{filename_entry_function ()}.
@end defvar

@node Completion Functions
@subsection Completion Functions

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

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

@defun 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{completion_matches ()}).  The default is to do filename
completion.  This just calls @code{rl_complete_internal ()} with an
argument of @samp{TAB}.
@end defun

@defun rl_possible_completions ()
List the possible completions.  See description of @code{rl_complete
()}.  This just calls @code{rl_complete_internal ()} with an argument of
@samp{?}.
@end defun

@defun {char **completion_matches} (char *text, char *(*entry_function) ())
Returns an array of @code{(char *)} which is a list of completions for
@var{text}.  If there are no completions, returns @code{(char **)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_function} 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.  It returns a @code{NULL}  pointer to the caller when there are
no more matches.
@end defun

@defun {char *filename_completion_function} (char *text, int state)
A generator function for filename completion in the general case.  Note
that completion in the Bash shell is a little different because of all
the pathnames that must be followed when looking up the completion for a
command.
@end defun

@defun {char *username_completion_function} (char *text, int state)
A completion generator for usernames.  @var{text} contains a partial
username preceded by a random character (usually @samp{~}).
@end defun

@node Completion Variables
@subsection Completion Variables

@defvar {Function *rl_completion_entry_function}
A pointer to the generator function for @code{completion_matches ()}.
@code{NULL} means to use @code{filename_entry_function ()}, the default
filename completer.
@end defvar

@defvar {Function *rl_attempted_completion_function}
A pointer to an alternative function to create matches.
The function is called with @var{text}, @var{start}, and @var{end}.
@var{start} and @var{end} are indices in @code{rl_line_buffer} saying
what the boundaries of @var{text} are.  If this function exists and
returns @code{NULL} then @code{rl_complete ()} will call the value of
@code{rl_completion_entry_function} to generate matches, otherwise the
array of strings returned will be used.
@end defvar

@defvar {int rl_completion_query_items}
Up to this many items will be displayed in response to a
possible-completions call.  After that, we ask the user if she is sure
she wants to see them all.  The default value is 100.
@end defvar

@defvar {char *rl_basic_word_break_characters}
The basic list of characters that signal a break between words for the
completer routine.  The contents of this variable is what breaks words
in the Bash shell, i.e. " \t\n\"\\'`@@$><=;|&@{(".
@end defvar

@defvar {char *rl_completer_word_break_characters}
The list of characters that signal a break between words for
@code{rl_complete_internal ()}.  The default list is the contents of
@code{rl_basic_word_break_characters}.
@end defvar

@defvar {char *rl_special_prefixes}
The list of characters that are word break characters, but should be
left in @var{text} when it is passed to the completion function.
Programs can use this to help determine what kind of completing to do.
@end defvar

@defvar {int rl_ignore_completion_duplicates}
If non-zero, then disallow duplicates in the matches.  Default is 1.
@end defvar

@defvar {int rl_filename_completion_desired}
Non-zero means that the results of the matches are to be treated as
filenames.  This is @emph{always} zero on entry, and can only be changed
within a completion entry generator function.
@end defvar

@defvar {Function *rl_ignore_some_completions_function}
This function, if defined, is called by the completer when real filename
completion is done, after all the matching names have been generated.
It is passed a @code{NULL} terminated array of @code{(char *)} known as
@var{matches} in the code.  The 1st element (@code{matches[0]}) is the
maximal substring that is common to all matches. This function can
re-arrange the list of matches as required, but each deleted element of
the array must be @code{free()}'d.
@end defvar

@node A Short Completion Example
@subsection A Short Completion Example

Here is a small application demonstrating the use of the GNU Readline
library.  It is called @code{fileman}, and the source code resides in
@file{readline/examples/fileman.c}.  This sample application provides
completion of command names, line editing features, and access to the
history list.

@page
@smallexample
/* fileman.c -- A tiny application which demonstrates how to use the
   GNU Readline library.  This application interactively allows users
   to manipulate files and their modes. */

#include <stdio.h>
#include <readline/readline.h>
#include <readline/history.h>
#include <sys/types.h>
#include <sys/file.h>
#include <sys/stat.h>
#include <sys/errno.h>

/* The names of functions that actually do the manipulation. */
int com_list (), com_view (), com_rename (), com_stat (), com_pwd ();
int com_delete (), com_help (), com_cd (), com_quit ();

/* A structure which contains information on the commands this program
   can understand. */

typedef struct @{
  char *name;                   /* User printable name of the function. */
  Function *func;               /* Function to call to do the job. */
  char *doc;                    /* Documentation for this function.  */
@} COMMAND;

COMMAND commands[] = @{
  @{ "cd", com_cd, "Change to directory DIR" @},
  @{ "delete", com_delete, "Delete FILE" @},
  @{ "help", com_help, "Display this text" @},
  @{ "?", com_help, "Synonym for `help'" @},
  @{ "list", com_list, "List files in DIR" @},
  @{ "ls", com_list, "Synonym for `list'" @},
  @{ "pwd", com_pwd, "Print the current working directory" @},
  @{ "quit", com_quit, "Quit using Fileman" @},
  @{ "rename", com_rename, "Rename FILE to NEWNAME" @},
  @{ "stat", com_stat, "Print out statistics on FILE" @},
  @{ "view", com_view, "View the contents of FILE" @},
  @{ (char *)NULL, (Function *)NULL, (char *)NULL @}
@};

/* The name of this program, as taken from argv[0]. */
char *progname;

/* When non-zero, this global means the user is done using this program. */
int done = 0;
@page
main (argc, argv)
     int argc;
     char **argv;
@{
  progname = argv[0];

  initialize_readline ();       /* Bind our completer. */