rltech.texi

在非GUI环境下

@comment %**start of header (This is for running Texinfo on a region.)
@setfilename rltech.info
@comment %**end of header (This is for running Texinfo on a region.)
@setchapternewpage odd

@ifinfo
This document describes the GNU Readline Library, a utility for aiding
in the consitency of user interface across discrete programs that need
to provide a command line interface.

Copyright (C) 1988-2004 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
pare preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifinfo

@node Programming with GNU Readline
@chapter Programming with GNU Readline

This chapter describes the interface between the @sc{gnu} Readline Library and
other programs.  If you are a programmer, and you wish to include the
features found in @sc{gnu} Readline
such as completion, line editing, and interactive history manipulation
in your own programs, this section is for you.

@menu
* Basic Behavior::	Using the default behavior of Readline.
* Custom Functions::	Adding your own functions to Readline.
* Readline Variables::			Variables accessible to custom
					functions.
* Readline Convenience Functions::	Functions which Readline supplies to
					aid in writing your own custom
					functions.
* Readline Signal Handling::	How Readline behaves when it receives signals.
* Custom Completers::	Supplanting or supplementing Readline's
			completion functions.
@end menu

@node Basic Behavior
@section Basic Behavior

Many programs provide a command line interface, such as @code{mail},
@code{ftp}, and @code{sh}.  For such programs, the default behaviour of
Readline is sufficient.  This section describes how to use Readline in
the simplest way possible, perhaps to replace calls in your code to
@code{gets()} or @code{fgets()}.

@findex readline
@cindex readline, function

The function @code{readline()} prints a prompt @var{prompt}
and then reads and returns a single line of text from the user.
If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed.
The line @code{readline} returns is allocated with @code{malloc()};
the caller should @code{free()} the line when it has finished with it.
The declaration for @code{readline} in ANSI C is

@example
@code{char *readline (const char *@var{prompt});}
@end example

@noindent
So, one might say
@example
@code{char *line = readline ("Enter a line: ");}
@end example
@noindent
in order to read a line of text from the user.
The line returned has the final newline removed, so only the
text remains.

If @code{readline} encounters an @code{EOF} while reading the line, and the
line is empty at that point, then @code{(char *)NULL} is returned.
Otherwise, the line is ended just as if a newline had been typed.

If you want the user to be able to get at the line later, (with
@key{C-p} for example), you must call @code{add_history()} to save the
line away in a @dfn{history} list of such lines.

@example
@code{add_history (line)};
@end example

@noindent
For full details on the GNU History Library, see the associated manual.

It is preferable to avoid saving empty lines on the history list, since
users rarely have a burning need to reuse a blank line.  Here is
a function which usefully replaces the standard @code{gets()} library
function, and has the advantage of no static buffer to overflow:

@example
/* A static variable for holding the line. */
static char *line_read = (char *)NULL;

/* Read a string, and return a pointer to it.
   Returns NULL on EOF. */
char *
rl_gets ()
@{
  /* If the buffer has already been allocated,
     return the memory to the free pool. */
  if (line_read)
    @{
      free (line_read);
      line_read = (char *)NULL;
    @}

  /* Get a line from the user. */
  line_read = readline ("");

  /* If the line has any text in it,
     save it on the history. */
  if (line_read && *line_read)
    add_history (line_read);

  return (line_read);
@}
@end example

This function gives the user the default behaviour of @key{TAB}
completion: completion on file names.  If you do not want Readline to
complete on filenames, you can change the binding of the @key{TAB} key
with @code{rl_bind_key()}.

@example
@code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});}
@end example

@code{rl_bind_key()} takes two arguments: @var{key} is the character that
you want to bind, and @var{function} is the address of the function to
call when @var{key} is pressed.  Binding @key{TAB} to @code{rl_insert()}
makes @key{TAB} insert itself.
@code{rl_bind_key()} returns non-zero if @var{key} is not a valid
ASCII character code (between 0 and 255).

Thus, to disable the default @key{TAB} behavior, the following suffices:
@example
@code{rl_bind_key ('\t', rl_insert);}
@end example

This code should be executed once at the start of your program; you
might write a function called @code{initialize_readline()} which
performs this and other desired initializations, such as installing
custom completers (@pxref{Custom Completers}).

@node Custom Functions
@section Custom Functions

Readline provides many functions for manipulating the text of
the line, but it isn't possible to anticipate the needs of all
programs.  This section describes the various functions and variables
defined within the Readline library which allow a user program to add
customized functionality to Readline.

Before declaring any functions that customize Readline's behavior, or
using any functionality Readline provides in other code, an
application writer should include the file @code{<readline/readline.h>}
in any file that uses Readline's features.  Since some of the definitions
in @code{readline.h} use the @code{stdio} library, the file
@code{<stdio.h>} should be included before @code{readline.h}.

@code{readline.h} defines a C preprocessor variable that should
be treated as an integer, @code{RL_READLINE_VERSION}, which may
be used to conditionally compile application code depending on
the installed Readline version.  The value is a hexadecimal
encoding of the major and minor version numbers of the library,
of the form 0x@var{MMmm}.  @var{MM} is the two-digit major
version number; @var{mm} is the two-digit minor version number. 
For Readline 4.2, for example, the value of
@code{RL_READLINE_VERSION} would be @code{0x0402}. 

@menu
* Readline Typedefs::	C declarations to make code readable.
* Function Writing::	Variables and calling conventions.
@end menu

@node Readline Typedefs
@subsection Readline Typedefs

For readabilty, we declare a number of new object types, all pointers
to functions.

The reason for declaring these new types is to make it easier to write
code describing pointers to C functions with appropriately prototyped
arguments and return values.

For instance, say we want to declare a variable @var{func} as a pointer
to a function which takes two @code{int} arguments and returns an
@code{int} (this is the type of all of the Readline bindable functions).
Instead of the classic C declaration

@code{int (*func)();}

@noindent
or the ANSI-C style declaration

@code{int (*func)(int, int);}

@noindent
we may write

@code{rl_command_func_t *func;}

The full list of function pointer types available is

@table @code
@item typedef int rl_command_func_t (int, int);

@item typedef char *rl_compentry_func_t (const char *, int);

@item typedef char **rl_completion_func_t (const char *, int, int);

@item typedef char *rl_quote_func_t (char *, int, char *);

@item typedef char *rl_dequote_func_t (char *, int);

@item typedef int rl_compignore_func_t (char **);

@item typedef void rl_compdisp_func_t (char **, int, int);

@item typedef int rl_hook_func_t (void);

@item typedef int rl_getc_func_t (FILE *);

@item typedef int rl_linebuf_func_t (char *, int);

@item typedef int rl_intfunc_t (int);
@item #define rl_ivoidfunc_t rl_hook_func_t
@item typedef int rl_icpfunc_t (char *);
@item typedef int rl_icppfunc_t (char **);

@item typedef void rl_voidfunc_t (void);
@item typedef void rl_vintfunc_t (int);
@item typedef void rl_vcpfunc_t (char *);
@item typedef void rl_vcppfunc_t (char **);

@end table

@node Function Writing
@subsection Writing a New Function

In order to write new functions for Readline, you need to know the
calling conventions for keyboard-invoked functions, and the names of the
variables that describe the current state of the line read so far.

The calling sequence for a command @code{foo} looks like

@example
@code{int foo (int count, int key)}
@end example

@noindent
where @var{count} is the numeric argument (or 1 if defaulted) and
@var{key} is the key that invoked this function.

It is completely up to the function as to what should be done with the
numeric argument.  Some functions use it as a repeat count, some
as a flag, and others to choose alternate behavior (refreshing the current
line as opposed to refreshing the screen, for example).  Some choose to
ignore it.  In general, if a
function uses the numeric argument as a repeat count, it should be able
to do something useful with both negative and positive arguments.
At the very least, it should be aware that it can be passed a
negative argument.

A command function should return 0 if its action completes successfully,
and a non-zero value if some error occurs.

@node Readline Variables
@section Readline Variables

These variables are available to function writers.

@deftypevar {char *} rl_line_buffer
This is the line gathered so far.  You are welcome to modify the
contents of the line, but see @ref{Allowing Undoing}.  The
function @code{rl_extend_line_buffer} is available to increase
the memory allocated to @code{rl_line_buffer}.
@end deftypevar

@deftypevar int rl_point
The offset of the current cursor position in @code{rl_line_buffer}
(the @emph{point}).
@end deftypevar

@deftypevar int rl_end
The number of characters present in @code{rl_line_buffer}.  When
@code{rl_point} is at the end of the line, @code{rl_point} and
@code{rl_end} are equal.
@end deftypevar

@deftypevar int rl_mark
The @var{mark} (saved position) in the current line.  If set, the mark
and point define a @emph{region}.
@end deftypevar

@deftypevar int rl_done
Setting this to a non-zero value causes Readline to return the current
line immediately.
@end deftypevar

@deftypevar int rl_num_chars_to_read
Setting this to a positive value before calling @code{readline()} causes
Readline to return after accepting that many characters, rather
than reading up to a character bound to @code{accept-line}.
@end deftypevar

@deftypevar int rl_pending_input
Setting this to a value makes it the next keystroke read.  This is a
way to stuff a single character into the input stream.
@end deftypevar