rltech.texi

linux中bash shell的源代码

These functions manage key bindings.

@deftypefun int rl_bind_key (int key, rl_command_func_t *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, rl_command_func_t *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_bind_key_if_unbound (int key, rl_command_func_t *function)
Binds @var{key} to @var{function} if it is not already bound in the
currently active keymap.
Returns non-zero in the case of an invalid @var{key} or if @var{key} is
already bound.
@end deftypefun

@deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map)
Binds @var{key} to @var{function} if it is not already bound in @var{map}.
Returns non-zero in the case of an invalid @var{key} or if @var{key} is
already bound.
@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 (rl_command_func_t *function, Keymap map)
Unbind all keys that execute @var{function} in @var{map}.
@end deftypefun

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

@deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function)
Bind the key sequence represented by the string @var{keyseq} to the function
@var{function}, beginning in the current keymap.
This makes new keymaps as necessary.
The return value is non-zero if @var{keyseq} is invalid.
@end deftypefun

@deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
Bind the key sequence represented by the string @var{keyseq} to the function
@var{function}.  This makes new keymaps as necessary.
Initial bindings are performed in @var{map}.
The return value is non-zero if @var{keyseq} is invalid.
@end deftypefun

@deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map)
Equivalent to @code{rl_bind_keyseq_in_map}.
@end deftypefun

@deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function)
Binds @var{keyseq} to @var{function} if it is not already bound in the
currently active keymap.
Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
already bound.
@end deftypefun

@deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map)
Binds @var{keyseq} to @var{function} if it is not already bound in @var{map}.
Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is
already bound.
@end deftypefun

@deftypefun int rl_generic_bind (int type, const 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 (const 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.  You may also
associate a new function name with an arbitrary function.

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

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

@deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *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 (rl_command_func_t *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 (void)
Print the names of all bindable Readline functions to @code{rl_outstream}.
@end deftypefun

@deftypefun {const char **} rl_funmap_names (void)
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 @code{free()} the array when you are done, but not the pointers.
@end deftypefun

@deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function)
Add @var{name} to the list of bindable Readline command names, and make
@var{function} the function to be called when @var{name} is invoked.
@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.

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:

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

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 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 (void)
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 (void)
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 rl_free_undo_list (void)
Free the existing undo list.
@end deftypefun

@deftypefun int rl_do_undo (void)
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 (void)
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 (void)
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 (void)
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 (void)
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 (void)
Reset the display state to a clean state and redisplay the current line
starting on a new line.
@end deftypefun

@deftypefun int rl_crlf (void)
Move the cursor to the start of the next screen line.
@end deftypefun

@deftypefun int rl_show_char (int c)
Display character @var{c} on @code{rl_outstream}.
If Readline has not been set to display meta characters directly, this
will convert meta characters to a meta-prefixed key sequence.
This is intended for use by applications which wish to do their own
redisplay.
@end deftypefun

@deftypefun int rl_message (const char *, @dots{})
The arguments are a format string as would be supplied to @code{printf},
possibly containing conversion specifications such as @samp{%d}, and
any additional arguments necessary to satisfy the conversion specifications.
The resulting string is displayed in the @dfn{echo area}.  The echo area
is also used to display numeric arguments and search strings.
You should call @code{rl_save_prompt} to save the prompt information
before calling this function.
@end deftypefun

@deftypefun int rl_clear_message (void)
Clear the message in the echo area.  If the prompt was saved with a call to
@code{rl_save_prompt} before the last call to @code{rl_message},
call @code{rl_restore_prompt} before calling this function.
@end deftypefun

@deftypefun void rl_save_prompt (void)
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 (void)
Restore the local Readline prompt display state saved by the most
recent call to @code{rl_save_prompt}.
if @code{rl_save_prompt} was called to save the prompt before a call
to @code{rl_message}, this function should be called before the
corresponding call to @code{rl_clear_message}.
@end deftypefun

@deftypefun int rl_expand_prompt (char *prompt)
Expand any special character sequences in @var{prompt} and set up the
local Readline prompt redisplay variables.
This function is called by @code{readline()}.  It may also be called to
expand the primary prompt if the @code{rl_on_new_line_with_prompt()}
function or @code{rl_already_prompted} variable is used.
It returns the number of visible characters on the last line of the
(possibly multi-line) prompt.
Applications may indicate that the prompt contains characters that take
up no physical screen space when displayed by bracketing a sequence of
such characters with the special markers @code{RL_PROMPT_START_IGNORE}
and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h}.  This may
be used to embed terminal-specific escape sequences in prompts.
@end deftypefun

@deftypefun int rl_set_prompt (const char *prompt)
Make Readline use @var{prompt} for subsequent redisplay.  This calls
@code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt}
to the result.
@end deftypefun

@node Modifying Text
@subsection Modifying Text

@deftypefun int rl_insert_text (const char *text)
Insert @var{text} into the line at the current cursor position.
Returns the number of characters inserted.
@end deftypefun

@deftypefun int rl_delete_text (int start, int end)
Delete the text between @var{start} and @var{end} in the current line.
Returns the number of characters deleted.
@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

@deftypefun int rl_kill_text (int start, int end)
Copy the text between @var{start} and @var{end} in the current line
to the kill ring, appending or prepending to the last kill if the
last command was a kill command.  The text is deleted.
If @var{start} is less than @var{end},
the text is appended, otherwise prepended.  If the last command was
not a kill, a new kill ring slot is used.
@end deftypefun