rltech.texinfo

UNIX下SH的实现源码

By default, it is set to @code{rl_redisplay}, the default @code{readline}
redisplay function (@pxref{Redisplay}).
@end deftypevar

@deftypevar {Keymap} rl_executing_keymap
This variable is set to the keymap (@pxref{Keymaps}) in which the
currently executing readline function was found.
@end deftypevar 

@deftypevar {Keymap} rl_binding_keymap
This variable is set to the keymap (@pxref{Keymaps}) in which the
last key binding occurred.
@end deftypevar 

@node Readline Convenience Functions
@section Readline Convenience Functions

@menu
* Function Naming::	How to give a function you write a name.
* Keymaps::		Making keymaps.
* Binding Keys::	Changing Keymaps.
* Associating Function Names and Bindings::	Translate function names to
						key sequences.
* Allowing Undoing::	How to make your functions undoable.
* Redisplay::		Functions to control line display.
* Modifying Text::	Functions to modify @code{rl_line_buffer}.
* Utility Functions::	Generally useful functions and hooks.
* Alternate Interface::	Using Readline in a `callback' fashion.
@end menu

@node Function Naming
@subsection Naming a Function

The user can dynamically change the bindings of keys while using
Readline.  This is done by representing the function with a descriptive
name.  The user is able to type the descriptive name when referring to
the function.  Thus, in an init file, one might find

@example
Meta-Rubout:	backward-kill-word
@end example

This binds the keystroke @key{Meta-Rubout} to the function
@emph{descriptively} named @code{backward-kill-word}.  You, as the
programmer, should bind the functions you write to descriptive names as
well.  Readline provides a function for doing that:

@deftypefun int rl_add_defun (char *name, Function *function, int key)
Add @var{name} to the list of named functions.  Make @var{function} be
the function that gets called.  If @var{key} is not -1, then bind it to
@var{function} using @code{rl_bind_key ()}.
@end deftypefun

Using this function alone is sufficient for most applications.  It is
the recommended way to add a few functions to the default functions that
Readline has built in.  If you need to do something other
than adding a function to Readline, you may need to use the
underlying functions described below.

@node Keymaps
@subsection Selecting a Keymap

Key bindings take place on a @dfn{keymap}.  The keymap is the
association between the keys that the user types and the functions that
get run.  You can make your own keymaps, copy existing keymaps, and tell
Readline which keymap to use.

@deftypefun Keymap rl_make_bare_keymap ()
Returns a new, empty keymap.  The space for the keymap is allocated with
@code{malloc ()}; you should @code{free ()} it when you are done.
@end deftypefun

@deftypefun Keymap rl_copy_keymap (Keymap map)
Return a new keymap which is a copy of @var{map}.
@end deftypefun

@deftypefun Keymap rl_make_keymap ()
Return a new keymap with the printing characters bound to rl_insert,
the lowercase Meta characters bound to run their equivalents, and
the Meta digits bound to produce numeric arguments.
@end deftypefun

@deftypefun void rl_discard_keymap (Keymap keymap)
Free the storage associated with @var{keymap}.
@end deftypefun

Readline has several internal keymaps.  These functions allow you to
change which keymap is active.

@deftypefun Keymap rl_get_keymap ()
Returns the currently active keymap.
@end deftypefun

@deftypefun void rl_set_keymap (Keymap keymap)
Makes @var{keymap} the currently active keymap.
@end deftypefun

@deftypefun Keymap rl_get_keymap_by_name (char *name)
Return the keymap matching @var{name}.  @var{name} is one which would
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
@end deftypefun

@deftypefun {char *} rl_get_keymap_name (Keymap keymap)
Return the name matching @var{keymap}.  @var{name} is one which would
be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}).
@end deftypefun

@node Binding Keys
@subsection Binding Keys

You associate keys with functions through the keymap.  Readline has
several internal keymaps: @code{emacs_standard_keymap},
@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap},
@code{vi_movement_keymap}, and @code{vi_insertion_keymap}.
@code{emacs_standard_keymap} is the default, and the examples in
this manual assume that.

Since @code{readline} installs a set of default key bindings the first
time it is called, there is always the danger that a custom binding
installed before the first call to @code{readline} will be overridden.
An alternate mechanism is to install custom key bindings in an
initialization function assigned to the @code{rl_startup_hook} variable
(@pxref{Readline Variables}).

These functions manage key bindings.

@deftypefun int rl_bind_key (int key, Function *function)
Binds @var{key} to @var{function} in the currently active keymap.
Returns non-zero in the case of an invalid @var{key}.
@end deftypefun

@deftypefun int rl_bind_key_in_map (int key, Function *function, Keymap map)
Bind @var{key} to @var{function} in @var{map}.  Returns non-zero in the case
of an invalid @var{key}.
@end deftypefun

@deftypefun int rl_unbind_key (int key)
Bind @var{key} to the null function in the currently active keymap.
Returns non-zero in case of error.
@end deftypefun

@deftypefun int rl_unbind_key_in_map (int key, Keymap map)
Bind @var{key} to the null function in @var{map}.
Returns non-zero in case of error.
@end deftypefun

@deftypefun int rl_unbind_function_in_map (Function *function, Keymap map)
Unbind all keys that execute @var{function} in @var{map}.
@end deftypefun

@deftypefun int rl_unbind_command_in_map (char *command, Keymap map)
Unbind all keys that are bound to @var{command} in @var{map}.
@end deftypefun

@deftypefun int rl_generic_bind (int type, char *keyseq, char *data, Keymap map)
Bind the key sequence represented by the string @var{keyseq} to the arbitrary
pointer @var{data}.  @var{type} says what kind of data is pointed to by
@var{data}; this can be a function (@code{ISFUNC}), a macro
(@code{ISMACR}), or a keymap (@code{ISKMAP}).  This makes new keymaps as
necessary.  The initial keymap in which to do bindings is @var{map}.
@end deftypefun

@deftypefun int rl_parse_and_bind (char *line)
Parse @var{line} as if it had been read from the @code{inputrc} file and
perform any key bindings and variable assignments found
(@pxref{Readline Init File}).
@end deftypefun

@deftypefun int rl_read_init_file (char *filename)
Read keybindings and variable assignments from @var{filename}
(@pxref{Readline Init File}).
@end deftypefun

@node Associating Function Names and Bindings
@subsection Associating Function Names and Bindings

These functions allow you to find out what keys invoke named functions
and the functions invoked by a particular key sequence.

@deftypefun {Function *} rl_named_function (char *name)
Return the function with name @var{name}.
@end deftypefun

@deftypefun {Function *} rl_function_of_keyseq (char *keyseq, Keymap map, int *type)
Return the function invoked by @var{keyseq} in keymap @var{map}.
If @var{map} is NULL, the current keymap is used.  If @var{type} is
not NULL, the type of the object is returned in it (one of @code{ISFUNC},
@code{ISKMAP}, or @code{ISMACR}).
@end deftypefun

@deftypefun {char **} rl_invoking_keyseqs (Function *function)
Return an array of strings representing the key sequences used to
invoke @var{function} in the current keymap.
@end deftypefun

@deftypefun {char **} rl_invoking_keyseqs_in_map (Function *function, Keymap map)
Return an array of strings representing the key sequences used to
invoke @var{function} in the keymap @var{map}.
@end deftypefun

@deftypefun void rl_function_dumper (int readable)
Print the readline function names and the key sequences currently
bound to them to @code{rl_outstream}.  If @var{readable} is non-zero,
the list is formatted in such a way that it can be made part of an
@code{inputrc} file and re-read.
@end deftypefun

@deftypefun void rl_list_funmap_names ()
Print the names of all bindable Readline functions to @code{rl_outstream}.
@end deftypefun

@deftypefun {char **} rl_funmap_names ()
Return a NULL terminated array of known function names.  The array is
sorted.  The array itself is allocated, but not the strings inside.  You
should free () the array when you done, but not the pointrs.
@end deftypefun

@node Allowing Undoing
@subsection Allowing Undoing

Supporting the undo command is a painless thing, and makes your
functions much more useful.  It is certainly easy to try
something if you know you can undo it.  I could use an undo function for
the stock market.

If your function simply inserts text once, or deletes text once, and
uses @code{rl_insert_text ()} or @code{rl_delete_text ()} to do it, then
undoing is already done for you automatically.

If you do multiple insertions or multiple deletions, or any combination
of these operations, you should group them together into one operation.
This is done with @code{rl_begin_undo_group ()} and
@code{rl_end_undo_group ()}.

The types of events that can be undone are:

@example
enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @}; 
@end example

Notice that @code{UNDO_DELETE} means to insert some text, and
@code{UNDO_INSERT} means to delete some text.  That is, the undo code
tells undo what to undo, not how to undo it.  @code{UNDO_BEGIN} and
@code{UNDO_END} are tags added by @code{rl_begin_undo_group ()} and
@code{rl_end_undo_group ()}.

@deftypefun int rl_begin_undo_group ()
Begins saving undo information in a group construct.  The undo
information usually comes from calls to @code{rl_insert_text ()} and
@code{rl_delete_text ()}, but could be the result of calls to
@code{rl_add_undo ()}.
@end deftypefun

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

@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text)
Remember how to undo an event (according to @var{what}).  The affected
text runs from @var{start} to @var{end}, and encompasses @var{text}.
@end deftypefun

@deftypefun void free_undo_list ()
Free the existing undo list.
@end deftypefun

@deftypefun int rl_do_undo ()
Undo the first thing on the undo list.  Returns @code{0} if there was
nothing to undo, non-zero if something was undone.
@end deftypefun

Finally, if you neither insert nor delete text, but directly modify the
existing text (e.g., change its case), 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.

@deftypefun int 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 you will subsequently modify
that text.
@end deftypefun

@node Redisplay
@subsection Redisplay

@deftypefun void rl_redisplay ()
Change what's displayed on the screen to reflect the current contents
of @code{rl_line_buffer}.
@end deftypefun

@deftypefun int rl_forced_update_display ()
Force the line to be updated and redisplayed, whether or not
Readline thinks the screen display is correct.
@end deftypefun

@deftypefun int rl_on_new_line ()
Tell the update functions that we have moved onto a new (empty) line,
usually after ouputting a newline.
@end deftypefun

@deftypefun int rl_on_new_line_with_prompt ()
Tell the update functions that we have moved onto a new line, with
@var{rl_prompt} already displayed.
This could be used by applications that want to output the prompt string
themselves, but still need Readline to know the prompt string length for
redisplay.
It should be used after setting @var{rl_already_prompted}.
@end deftypefun

@deftypefun int rl_reset_line_state ()
Reset the display state to a clean state and redisplay the current line
starting on a new line.
@end deftypefun

@deftypefun int rl_message (va_alist)
The arguments are a string as would be supplied to @code{printf}.  The
resulting string is displayed in the @dfn{echo area}.  The echo area
is also used to display numeric arguments and search strings.
@end deftypefun

@deftypefun int rl_clear_message ()
Clear the message in the echo area.
@end deftypefun

@deftypefun void rl_save_prompt ()
Save the local Readline prompt display state in preparation for
displaying a new message in the message area with @code{rl_message}.
@end deftypefun

@deftypefun void rl_restore_prompt ()
Restore the local Readline prompt display state saved by the most
recent call to @code{rl_save_prompt}.
@end deftypefun

@node Modifying Text
@subsection Modifying Text

@deftypefun int rl_insert_text (char *text)
Insert @var{text} into the line at the current cursor position.
@end deftypefun

@deftypefun int rl_delete_text (int start, int end)
Delete the text between @var{start} and @var{end} in the current line.
@end deftypefun

@deftypefun {char *} rl_copy_text (int start, int end)
Return a copy of the text between @var{start} and @var{end} in
the current line.
@end deftypefun