rltech.texinfo

UNIX下SH的实现源码

@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, allowing the generator to perform
any necessary initialization, 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.  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.

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

@deftypevar {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,
@code{filename_completion_function ()}, is used.
@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.
@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{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 {char **} completion_matches (char *text, CPFunction *entry_func)
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_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 *} filename_completion_function (char *text, int state)
A generator function for filename completion in the general case.  Note
that completion in Bash is a little different because of all
the pathnames that must be followed when looking up completions for a
command.  The Bash source is a useful reference for writing custom
completion functions.
@end deftypefun

@deftypefun {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{~}).  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 {Function *} rl_completion_entry_function
A pointer to the generator function for @code{completion_matches ()}.
@code{NULL} means to use @code{filename_completion_function ()}, the default
filename completer.
@end deftypevar

@deftypevar {CPPFunction *} 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}, or if this variable is set to @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 deftypevar

@deftypevar {CPFunction *} rl_filename_quoting_function
A pointer to a function that will quote a filename in an application-
specific fashion.  This is called if filename completion is being
attempted and one of the characters in @code{rl_filename_quote_characters}
appears in a completed filename.  The function is called with
@var{text}, @var{match_type}, and @var{quote_pointer}.  The @var{text}
is the filename to be quoted.  The @var{match_type} is either
@code{SINGLE_MATCH}, if there is only one completion match, or
@code{MULT_MATCH}.  Some functions use this to decide whether or not to
insert a closing quote character.  The @var{quote_pointer} is a pointer
to any opening quote character the user typed.  Some functions choose
to reset this character.
@end deftypevar

@deftypevar {CPFunction *} rl_filename_dequoting_function
A pointer to a function that will remove application-specific quoting
characters from a filename before completion is attempted, so those
characters do not interfere with matching the text against names in
the filesystem.  It is called with @var{text}, the text of the word
to be dequoted, and @var{quote_char}, which is the quoting character 
that delimits the filename (usually @samp{'} or @samp{"}).  If
@var{quote_char} is zero, the filename was not in an embedded string.
@end deftypevar

@deftypevar {Function *} rl_char_is_quoted_p
A pointer to a function to call that determines whether or not a specific
character in the line buffer is quoted, according to whatever quoting
mechanism the program calling readline uses.  The function is called with
two arguments: @var{text}, the text of the line, and @var{index}, the
index of the character in the line.  It is used to decide whether a
character found in @code{rl_completer_word_break_characters} should be
used to break words for the completer.
@end deftypevar

@deftypevar 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 deftypevar

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

@deftypevar {char *} rl_basic_quote_characters
List of quote characters which can cause a word break.
@end deftypevar

@deftypevar {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 value of
@code{rl_basic_word_break_characters}.
@end deftypevar

@deftypevar {char *} rl_completer_quote_characters
List of characters which can be used to quote a substring of the line.
Completion occurs on the entire substring, and within the substring
@code{rl_completer_word_break_characters} are treated as any other character,
unless they also appear within this list.
@end deftypevar

@deftypevar {char *} rl_filename_quote_characters
A list of characters that cause a filename to be quoted by the completer
when they appear in a completed filename.  The default is the null string.
@end deftypevar

@deftypevar {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.
For instance, Bash sets this variable to "$@@" so that it can complete
shell variables and hostnames.
@end deftypevar

@deftypevar {int} rl_completion_append_character
When a single completion alternative matches at the end of the command
line, this character is appended to the inserted completion text.  The
default is a space character (@samp{ }).  Setting this to the null
character (@samp{\0}) prevents anything being appended automatically.
This can be changed in custom completion functions to
provide the ``most sensible word separator character'' according to
an application-specific command line syntax specification.
@end deftypevar

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

@deftypevar 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.  If it is set to a non-zero
value, directory names have a slash appended and Readline attempts to
quote completed filenames if they contain any embedded word break
characters.
@end deftypevar

@deftypevar int rl_filename_quoting_desired
Non-zero means that the results of the matches are to be quoted using
double quotes (or an application-specific quoting mechanism) if the
completed filename contains any characters in
@code{rl_filename_quote_chars}.  This is @emph{always} non-zero
on entry, and can only be changed within a completion entry generator
function.  The quoting is effected via a call to the function pointed to
by @code{rl_filename_quoting_function}.
@end deftypevar

@deftypevar int rl_inhibit_completion
If this variable is non-zero, completion is inhibit<ed.  The completion
character will be inserted as any other bound to @code{self-insert}.
@end deftypevar

@deftypevar {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 matches.
The first element (@code{matches[0]}) is the
maximal substring common to all matches. This function can
re-arrange the list of matches as required, but each element deleted
from the array must be freed.
@end deftypevar

@deftypevar {Function *} rl_directory_completion_hook
This function, if defined, is allowed to modify the directory portion
of filenames Readline completes.  It is called with the address of a
string (the current directory name) as an argument.  It could be used
to expand symbolic links or shell variables in pathnames.
@end deftypevar

@deftypevar {VFunction *} rl_completion_display_matches_hook
If non-zero, then this is the address of a function to call when
completing a word would normally display the list of possible matches.
This function is called in lieu of Readline displaying the list.
It takes three arguments:
(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length})
where @var{matches} is the array of matching strings,
@var{num_matches} is the number of strings in that array, and
@var{max_length} is the length of the longest string in that array.
Readline provides a convenience function, @code{rl_display_match_list},
that takes care of doing the display to Readline's output stream.  That
function may be called from this hook.
@end deftypevar

@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{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 <sys/types.h>
#include <sys/file.h>
#include <sys/stat.h>
#include <sys/errno.h>

#include <readline/readline.h>
#include <readline/history.h>

extern char *getwd ();
extern char *xmalloc ();

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

/* Forward declarations. */
char *stripwhite ();
COMMAND *find_command ();

/* 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;

char *
dupstr (s)
     int s;
@{
  char *r;

  r = xmalloc (strlen (s) + 1);
  strcpy (r, s);
  return (r);
@}

main (argc, argv)
     int argc;
     char **argv;
@{
  char *line, *s;

  progname = argv[0];

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

  /* Loop reading and executing lines until the user quits. */
  for ( ; done == 0; )
    @{
      line = readline ("FileMan: ");

      if (!line)