Initial revision
This commit is contained in:
K. Richard Pixley
parent
7785cbdd0b
commit
681fa9a853
|
|
@ -0,0 +1,198 @@
|
|||
\input texinfo.tex
|
||||
@setfilename history.info
|
||||
|
||||
@c start-menu
|
||||
* History: (history). The GNU History library.
|
||||
@c end-menu
|
||||
|
||||
@ifinfo
|
||||
This file documents the GNU History library.
|
||||
|
||||
Copyright (C) 1988 Free Software Foundation, Inc.
|
||||
Authored by Brian Fox.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this manual
|
||||
provided the copyright notice and this permission notice are 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 also that the
|
||||
GNU Copyright statement is available to the distributee, and 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.
|
||||
@end ifinfo
|
||||
|
||||
@node Top, Introduction, , (DIR)
|
||||
|
||||
This document describes the GNU History library, a programming tool that
|
||||
provides a consistent user interface for recalling lines of previously
|
||||
typed input.
|
||||
|
||||
@menu
|
||||
* Introduction:: What is the GNU History library for?
|
||||
* Interactive Use:: What it feels like using History as a user.
|
||||
* Programming:: How to use History in your programs.
|
||||
@end menu
|
||||
|
||||
@node Introduction, Interactive Use, , Top
|
||||
@unnumbered Introduction
|
||||
|
||||
Many programs read input from the user a line at a time. The GNU history
|
||||
library is able to keep track of those lines, associate arbitrary data with
|
||||
each line, and utilize information from previous lines in making up new
|
||||
ones.
|
||||
|
||||
The programmer using the History library has available to him functions for
|
||||
remembering lines on a history stack, associating arbitrary data with a
|
||||
line, removing lines from the stack, searching through the stack for a
|
||||
line containing an arbitrary text string, and referencing any line on the
|
||||
stack directly. In addition, a history @dfn{expansion} function is
|
||||
available which provides for a consistent user interface across many
|
||||
different programs.
|
||||
|
||||
The end-user using programs written with the History library has the
|
||||
benifit of a consistent user interface, with a set of well-known commands
|
||||
for manipulating the text of previous lines and using that text in new
|
||||
commands. The basic history manipulation commands are similar to the
|
||||
history substitution used by Csh.
|
||||
|
||||
If the programmer desires, he can use the Readline library, which includes
|
||||
history manipulation by default, and has the added advantage of Emacs style
|
||||
command line editing.
|
||||
|
||||
@node Interactive Use, Programming, Introduction, Top
|
||||
@chapter Interactive Use
|
||||
|
||||
@section History Expansion
|
||||
@cindex expansion
|
||||
|
||||
The History library provides a history expansion feature that is similar to
|
||||
the history expansion in Csh. The following text describes what syntax
|
||||
features are available.
|
||||
|
||||
History expansion takes place in two parts. The first is to determine
|
||||
which line from the previous history should be used during substitution.
|
||||
The second is to select portions of that line for inclusion into the
|
||||
current one. The line selected from the previous history is called the
|
||||
@dfn{event}, and the portions of that line that are acted upon are called
|
||||
@dfn{words}. The line is broken into words in the same fashion that the
|
||||
Bash shell does, so that several English (or Unix) words surrounded by
|
||||
quotes are considered as one word.
|
||||
|
||||
@menu
|
||||
* Event Designators:: How to specify which history line to use.
|
||||
* Word Designators:: Specifying which words are of interest.
|
||||
* Modifiers:: Modifying the results of susbstitution.
|
||||
@end menu
|
||||
|
||||
@node Event Designators, Word Designators, , Interactive Use
|
||||
@subsection Event Designators
|
||||
@cindex event designators
|
||||
|
||||
An event designator is a reference to a command line entry in the history
|
||||
list.
|
||||
|
||||
@table @var
|
||||
|
||||
@item !
|
||||
Start a history subsititution, except when followed by a @key{SPC},
|
||||
@key{TAB}, @key{RET}, @key{=} or @key{(}.
|
||||
|
||||
@item !!
|
||||
Refer to the previous command. This is a synonym for @code{!-1}.
|
||||
|
||||
@item !n
|
||||
Refer to command line @var{n}.
|
||||
|
||||
@item !-n
|
||||
Refer to the current command line minus @var{n}.
|
||||
|
||||
@item !string
|
||||
Refer to the most recent command starting with @var{string}.
|
||||
|
||||
@item !?string[?]
|
||||
Refer to the most recent command containing @var{string}.
|
||||
|
||||
@end table
|
||||
|
||||
@node Word Designators, Modifiers, Event Designators, Interactive Use
|
||||
@subsection Word Designators
|
||||
|
||||
A @key{:} separates the event specification from the word designator. It
|
||||
can be omitted if the word designator begins with a @key{^}, @key{$},
|
||||
@key{*} or @key{%}. Words are numbered from the beginning of the line,
|
||||
with the first word being denoted by a 0 (zero).
|
||||
|
||||
@table @asis
|
||||
|
||||
@item @var{0} (zero)
|
||||
The zero'th word. For many applications, this is the command word.
|
||||
|
||||
@item n
|
||||
The @var{n}'th word.
|
||||
|
||||
@item @var{^}
|
||||
The first argument. that is, word 1.
|
||||
|
||||
@item @var{$}
|
||||
The last argument.
|
||||
|
||||
@item @var{%}
|
||||
The word matched by the most recent @code{?string?} search.
|
||||
|
||||
@item @var{x}-@var{y}
|
||||
A range of words; @code{-@var{y}} is equivalent to @code{0-@var{y}}.
|
||||
|
||||
@item @var{*}
|
||||
All of the words, excepting the zero'th. This is a synonym for @samp{1-$}.
|
||||
It is not an error to use @samp{*} if there is just one word in the event.
|
||||
The empty string is returned in that case.
|
||||
|
||||
@end table
|
||||
|
||||
@node Modifiers, , Word Designators, Interactive Use
|
||||
@subsection Modifiers
|
||||
|
||||
After the optional word designator, you can add a sequence of one or more
|
||||
of the following modifiers, each preceded by a @key{:}.
|
||||
|
||||
@table @code
|
||||
|
||||
@item #
|
||||
The entire command line typed so far. This means the current command,
|
||||
not the previous command, so it really isn't a word designator, and doesn't
|
||||
belong in this section.
|
||||
|
||||
@item h
|
||||
Remove a trailing pathname component, leaving only the head.
|
||||
|
||||
@item r
|
||||
Remove a trailing suffix of the form ".xxx", leaving the basename (root).
|
||||
|
||||
@item e
|
||||
Remove all but the suffix (end).
|
||||
|
||||
@item t
|
||||
Remove all leading pathname components (before the last slash), leaving
|
||||
the tail.
|
||||
|
||||
@item p
|
||||
Print the new command but do not execute it. This takes effect
|
||||
immediately, so it should be the last specifier on the line.
|
||||
|
||||
@end table
|
||||
|
||||
@node Programming, , Interactive Use, Top
|
||||
@chapter Programming
|
||||
|
||||
@bye
|
||||
|
|
@ -0,0 +1,188 @@
|
|||
@ifinfo
|
||||
This file documents the GNU History library.
|
||||
|
||||
Copyright (C) 1988 Free Software Foundation, Inc.
|
||||
Authored by Brian Fox.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this manual
|
||||
provided the copyright notice and this permission notice are preserved on
|
||||
all copies.
|
||||
@end ifinfo
|
||||
|
||||
@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).
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided also that the
|
||||
GNU Copyright statement is available to the distributee, and 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.
|
||||
@end ignore
|
||||
|
||||
@node History Top,,,
|
||||
@appendix Command Line History
|
||||
@ifinfo
|
||||
This file is meant to be an inclusion in the documentation of programs
|
||||
that use the history library features. There is also a standalone
|
||||
document, entitled @file{history.texinfo}.
|
||||
@end ifinfo
|
||||
|
||||
This Appendix describes the GNU History library, a programming tool that
|
||||
provides a consistent user interface for recalling lines of previously
|
||||
typed input.
|
||||
|
||||
@menu
|
||||
* Introduction to History:: What is the GNU History library for?
|
||||
* History Interaction:: What it feels like using History as a user.
|
||||
@end menu
|
||||
|
||||
@node Introduction to History, History Interaction, History Top, Top
|
||||
@appendixsec Introduction to History
|
||||
|
||||
Many programs read input from the user a line at a time. The GNU history
|
||||
library is able to keep track of those lines, associate arbitrary data with
|
||||
each line, and utilize information from previous lines in making up new
|
||||
ones.
|
||||
|
||||
The programmer using the History library has available to him functions
|
||||
for remembering lines on a history stack, associating arbitrary data
|
||||
with a line, removing lines from the stack, searching through the stack
|
||||
for a line containing an arbitrary text string, and referencing any line
|
||||
on the stack directly. In addition, a history @dfn{expansion} function
|
||||
is available which provides for a consistent user interface across many
|
||||
different programs.
|
||||
|
||||
When you use programs written with the History library, you have the
|
||||
benefit of a consistent user interface, with a set of well-known
|
||||
commands for manipulating the text of previous lines and using that text
|
||||
in new commands. The basic history manipulation commands are similar to
|
||||
the history substitution used by Csh.
|
||||
|
||||
GNU programs often also use the Readline library, which includes history
|
||||
manipulation by default, and has the added advantage of Emacs style
|
||||
command line editing.
|
||||
|
||||
@node History Interaction, , Introduction to History, Top
|
||||
@appendixsec History Interaction
|
||||
@cindex expansion
|
||||
|
||||
The History library provides a history expansion feature that is similar
|
||||
to the history expansion in Csh. The following text describes what
|
||||
syntax features are available.
|
||||
|
||||
History expansion takes place in two parts. The first is to determine
|
||||
which line from the previous history should be used during substitution.
|
||||
The second is to select portions of that line for inclusion into the
|
||||
current one. The line selected from the previous history is called the
|
||||
@dfn{event}, and the portions of that line that are acted upon are
|
||||
called @dfn{words}. The line is broken into words in the same fashion
|
||||
used by the Bash shell, so that several words surrounded by quotes are
|
||||
treated as if they were a single word.
|
||||
|
||||
@menu
|
||||
* Event Designators:: How to specify which history line to use. *
|
||||
Word Designators:: Specifying which words are of interest. *
|
||||
Modifiers:: Modifying the results of susbstitution.
|
||||
@end menu
|
||||
|
||||
@node Event Designators, Word Designators, , History Interaction
|
||||
@appendixsubsec Event Designators
|
||||
@cindex event designators
|
||||
|
||||
An event designator is a reference to a command line entry in the
|
||||
history list.
|
||||
|
||||
@table @asis
|
||||
|
||||
@item @code{!}
|
||||
Start a history subsititution, except when followed by a space, tab, or
|
||||
the end of the line; or by @samp{=} or @samp{(}.
|
||||
|
||||
@item @code{!!}
|
||||
Refer to the previous command. This is a synonym for @code{!-1}.
|
||||
|
||||
@item @code{!@var{n}}
|
||||
Refer to command line @var{n}.
|
||||
|
||||
@item @code{!-@var{n}}
|
||||
Refer to the command line @var{n} lines back.
|
||||
|
||||
@item @code{!@var{string}}
|
||||
Refer to the most recent command starting with @var{string}.
|
||||
|
||||
@item @code{!?@var{string}}[@code{?}]
|
||||
Refer to the most recent command containing @var{string}.
|
||||
|
||||
@end table
|
||||
|
||||
@node Word Designators, Modifiers, Event Designators, History Interaction
|
||||
@appendixsubsec Word Designators
|
||||
|
||||
A @samp{:} separates the event specification from the word designator. It
|
||||
can be omitted if the word designator begins with a @samp{^}, @samp{$},
|
||||
@samp{*} or @samp{%}. Words are numbered from the beginning of the line,
|
||||
with the first word being denoted by a 0 (zero).
|
||||
|
||||
@table @code
|
||||
|
||||
@item 0 (zero)
|
||||
The zero'th word. For many applications, this is the command word.
|
||||
|
||||
@item n
|
||||
The @var{n}'th word.
|
||||
|
||||
@item ^
|
||||
The first argument. that is, word 1.
|
||||
|
||||
@item $
|
||||
The last argument.
|
||||
|
||||
@item %
|
||||
The word matched by the most recent @code{?@var{string}?} search.
|
||||
|
||||
@item @var{x}-@var{y}
|
||||
A range of words; @code{-@var{y}} abbreviates @code{0-@var{y}}.
|
||||
|
||||
@item *
|
||||
All of the words, excepting the zero'th. This is a synonym for @samp{1-$}.
|
||||
It is not an error to use @samp{*} if there is just one word in the event.
|
||||
The empty string is returned in that case.
|
||||
|
||||
@end table
|
||||
|
||||
@node Modifiers, , Word Designators, History Interaction
|
||||
@appendixsubsec Modifiers
|
||||
|
||||
After the optional word designator, you can add a sequence of one or more
|
||||
of the following modifiers, each preceded by a @samp{:}.
|
||||
|
||||
@table @code
|
||||
|
||||
@item #
|
||||
The entire command line typed so far. This means the current command,
|
||||
not the previous command, so it really isn't a word designator, and doesn't
|
||||
belong in this section.
|
||||
|
||||
@item h
|
||||
Remove a trailing pathname component, leaving only the head.
|
||||
|
||||
@item r
|
||||
Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving the basename.
|
||||
|
||||
@item e
|
||||
Remove all but the suffix.
|
||||
|
||||
@item t
|
||||
Remove all leading pathname components, leaving the tail.
|
||||
|
||||
@item p
|
||||
Print the new command but do not execute it. This takes effect
|
||||
immediately, so it should be the last specifier on the line.
|
||||
|
||||
@end table
|
||||
|
|
@ -0,0 +1,494 @@
|
|||
@ignore
|
||||
|
||||
This file documents the end user interface to the GNU command line
|
||||
editing feautres. It is to be an appendix to manuals for programs which
|
||||
use these features. There is a document entitled "readline.texinfo"
|
||||
which contains both end-user and programmer documentation for the GNU
|
||||
Readline Library.
|
||||
|
||||
Copyright (C) 1988, 1991 Free Software Foundation, Inc.
|
||||
|
||||
Written by Brian Fox.
|
||||
|
||||
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).
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this manual
|
||||
provided the copyright notice and this permission notice are preserved on
|
||||
all copies.
|
||||
|
||||
Permission is granted to copy and distribute modified versions of this
|
||||
manual under the conditions for verbatim copying, provided also that the
|
||||
GNU Copyright statement is available to the distributee, and 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.
|
||||
@end ignore
|
||||
|
||||
@node Command Line Editing, , , Top
|
||||
@appendix Command Line Editing
|
||||
|
||||
This appendix describes GNU's command line editing interface.
|
||||
Often during an interactive session you will type in a long line of
|
||||
text, only to notice that the first word on the line is misspelled. The
|
||||
Readline library gives you a set of commands for manipulating the text
|
||||
as you type it in, allowing you to just fix your typo, and not forcing
|
||||
you to retype the majority of the line. Using these editing commands,
|
||||
you move the cursor to the place that needs correction, and delete or
|
||||
insert the text of the corrections. Then, when you are satisfied with
|
||||
the line, you simply press @key{RETURN}. You do not have to be at the
|
||||
end of the line to press @key{RETURN}; the entire line will be accepted
|
||||
in any case.
|
||||
|
||||
@menu
|
||||
* Conventions:: Notation used in this appendix.
|
||||
* Basic Line Editing:: The minimum set of commands for editing a line.
|
||||
* Movement Commands:: Commands for moving the cursor about the line.
|
||||
* Cutting and Pasting:: Deletion and copying of text sections.
|
||||
* Transposition:: Exchanging two characters or words.
|
||||
* Completion:: Expansion of a partially typed word into
|
||||
the full text.
|
||||
@end menu
|
||||
|
||||
@node Conventions, Basic Line Editing, Command Line Editing, Command Line Editing
|
||||
@appendixsec Conventions on Notation
|
||||
|
||||
In this Appendix, the following notation is used to describe
|
||||
keystrokes.
|
||||
|
||||
The text @kbd{C-k} is read as `Control-K' and describes the character
|
||||
produced when the Control key is depressed and the @key{k} key is struck.
|
||||
|
||||
The text @kbd{M-k} is read as `Meta-K' and describes the character
|
||||
produced when the meta key (if you have one) is depressed, and the
|
||||
@key{k} key is struck. If you do not have a meta key, it is equivalent
|
||||
to type @key{ESC} @i{first}, and then type @key{k}. Either process is
|
||||
known as @dfn{metafying} the @key{k} key.
|
||||
|
||||
The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the
|
||||
character produced by @dfn{metafying} @kbd{C-k}.
|
||||
|
||||
In addition, several keys have their own names. Specifically,
|
||||
@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all
|
||||
stand for themselves when seen in this text, or in an init file
|
||||
(@pxref{Readline Init File}, for more info).
|
||||
|
||||
@node Readline Interaction, Readline Init File, Readline Introduction, Readline Top
|
||||
@appendixsec Readline Interaction
|
||||
@cindex interaction, readline
|
||||
|
||||
@menu
|
||||
* Readline Bare Essentials:: The least you need to know about Readline.
|
||||
* Readline Movement Commands:: Moving about the input line.
|
||||
* Readline Killing Commands:: How to delete text, and how to get it back!
|
||||
* Readline Arguments:: Giving numeric arguments to commands.
|
||||
@end menu
|
||||
|
||||
@node Readline Bare Essentials, Readline Movement Commands, Readline Interaction, Readline Interaction
|
||||
@appendixsubsec Bare Essentials
|
||||
|
||||
In order to enter characters into the line, simply type them. The typed
|
||||
character appears where the cursor was, and then the cursor moves one
|
||||
space to the right. If you mistype a character, you can use @key{DEL} to
|
||||
back up, and delete the mistyped character.
|
||||
|
||||
Sometimes you may miss typing a character that you wanted to type, and
|
||||
not notice your error until you have typed several other characters. In
|
||||
that case, you can type @kbd{C-b} to move the cursor to the left, and then
|
||||
correct your mistake. Aftwerwards, you can move the cursor to the right
|
||||
with @kbd{C-f}.
|
||||
|
||||
When you add text in the middle of a line, you will notice that characters
|
||||
to the right of the cursor get `pushed over' to make room for the text
|
||||
that you have inserted. Likewise, when you delete text behind the cursor,
|
||||
characters to the right of the cursor get `pulled back' to fill in the
|
||||
blank space created by the removal of the text. A list of the basic bare
|
||||
essentials for editing the text of an input line follows.
|
||||
|
||||
@table @asis
|
||||
@item @kbd{C-b}
|
||||
Move back one character.
|
||||
@item @kbd{C-f}
|
||||
Move forward one character.
|
||||
@item @key{DEL}
|
||||
Delete the character to the left of the cursor.
|
||||
@item @kbd{C-d}
|
||||
Delete the character underneath the cursor.
|
||||
@item @var{c}
|
||||
Insert an ordinary printing character @var{c} into the line at the cursor.
|
||||
@item @kbd{C-_}
|
||||
Undo the last thing that you did. You can undo all the way back to an
|
||||
empty line.
|
||||
@end table
|
||||
|
||||
@node Readline Movement Commands, Readline Killing Commands, Readline Bare Essentials, Readline Interaction
|
||||
@appendixsubsec Movement Commands
|
||||
|
||||
|
||||
The above table describes the most basic possible keystrokes that you need
|
||||
in order to do editing of the input line. For your convenience, many
|
||||
other commands have been added in addition to @kbd{C-b}, @kbd{C-f},
|
||||
@kbd{C-d}, and @key{DEL}. Here are some commands for moving more rapidly
|
||||
about the line.
|
||||
|
||||
@table @kbd
|
||||
@item C-a
|
||||
Move to the start of the line.
|
||||
@item C-e
|
||||
Move to the end of the line.
|
||||
@item M-f
|
||||
Move forward a word.
|
||||
@item M-b
|
||||
Move backward a word.
|
||||
@item C-l
|
||||
Clear the screen, reprinting the current line at the top.
|
||||
@end table
|
||||
|
||||
Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves
|
||||
forward a word. It is a loose convention that control keystrokes
|
||||
operate on characters while meta keystrokes operate on words.
|
||||
|
||||
@node Readline Killing Commands, Readline Arguments, Readline Movement Commands, Readline Interaction
|
||||
@appendixsubsec Killing Commands
|
||||
|
||||
@dfn{Killing} text means to delete the text from the line, but to save
|
||||
it away for later use, usually by @dfn{yanking} it back into the line.
|
||||
If the description for a command says that it `kills' text, then you can
|
||||
be sure that you can get the text back in a different (or the same)
|
||||
place later.
|
||||
|
||||
Here is the list of commands for killing text.
|
||||
|
||||
@table @kbd
|
||||
@item C-k
|
||||
Kill the text from the current cursor position to the end of the line.
|
||||
|
||||
@item M-d
|
||||
Kill from the cursor to the end of the current word, or if between
|
||||
words, to the end of the next word.
|
||||
|
||||
@item M-@key{DEL}
|
||||
Kill from the cursor the start ofthe previous word, or if between words, to the start of the previous word.
|
||||
|
||||
@item C-w
|
||||
Kill from the cursor to the previous whitespace. This is different than
|
||||
@kbd{M-@key{DEL}} because the word boundaries differ.
|
||||
|
||||
@end table
|
||||
|
||||
And, here is how to @dfn{yank} the text back into the line. Yanking
|
||||
is
|
||||
|
||||
@table @kbd
|
||||
@item C-y
|
||||
Yank the most recently killed text back into the buffer at the cursor.
|
||||
|
||||
@item M-y
|
||||
Rotate the kill-ring, and yank the new top. You can only do this if
|
||||
the prior command is @kbd{C-y} or @kbd{M-y}.
|
||||
@end table
|
||||
|
||||
When you use a kill command, the text is saved in a @dfn{kill-ring}.
|
||||
Any number of consecutive kills save all of the killed text together, so
|
||||
that when you yank it back, you get it in one clean sweep. The kill
|
||||
ring is not line specific; the text that you killed on a previously
|
||||
typed line is available to be yanked back later, when you are typing
|
||||
another line.
|
||||
|
||||
@node Readline Arguments, , Readline Killing Commands, Readline Interaction
|
||||
@appendixsubsec Arguments
|
||||
|
||||
You can pass numeric arguments to Readline commands. Sometimes the
|
||||
argument acts as a repeat count, other times it is the @i{sign} of the
|
||||
argument that is significant. If you pass a negative argument to a
|
||||
command which normally acts in a forward direction, that command will
|
||||
act in a backward direction. For example, to kill text back to the
|
||||
start of the line, you might type @kbd{M--} @kbd{C-k}.
|
||||
|
||||
The general way to pass numeric arguments to a command is to type meta
|
||||
digits before the command. If the first `digit' you type is a minus
|
||||
sign (@kbd{-}), then the sign of the argument will be negative. Once
|
||||
you have typed one meta digit to get the argument started, you can type
|
||||
the remainder of the digits, and then the command. For example, to give
|
||||
the @kbd{C-d} command an argument of 10, you could type @kbd{M-1 0 C-d}.
|
||||
|
||||
|
||||
@node Readline Init File, , Readline Interaction, Readline Top
|
||||
@appendixsec Readline Init File
|
||||
|
||||
Although the Readline library comes with a set of Emacs-like
|
||||
keybindings, it is possible that you would like to use a different set
|
||||
of keybindings. You can customize programs that use Readline by putting
|
||||
commands in an @dfn{init} file in your home directory. The name of this
|
||||
file is @file{~/.inputrc}.
|
||||
|
||||
When a program which uses the Readline library starts up, it reads the file
|
||||
@file{~/.inputrc}, and sets the keybindings.
|
||||
|
||||
@menu
|
||||
* Readline Init Syntax:: Syntax for the commands in @file{~/.inputrc}.
|
||||
* Readline Vi Mode:: Switching to @code{vi} mode in Readline.
|
||||
@end menu
|
||||
|
||||
@node Readline Init Syntax, Readline Vi Mode, Readline Init File, Readline Init File
|
||||
@appendixsubsec Readline Init Syntax
|
||||
|
||||
You can start up with a vi-like editing mode by placing
|
||||
|
||||
@example
|
||||
@code{set editing-mode vi}
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
in your @file{~/.inputrc} file.
|
||||
|
||||
You can have Readline use a single line for display, scrolling the input
|
||||
between the two edges of the screen by placing
|
||||
|
||||
@example
|
||||
@code{set horizontal-scroll-mode On}
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
in your @file{~/.inputrc} file.
|
||||
|
||||
The syntax for controlling keybindings in the @file{~/.inputrc} file is
|
||||
simple. First you have to know the @i{name} of the command that you
|
||||
want to change. The following pages contain tables of the command name, the
|
||||
default keybinding, and a short description of what the command does.
|
||||
|
||||
Once you know the name of the command, simply place the name of the key
|
||||
you wish to bind the command to, a colon, and then the name of the
|
||||
command on a line in the @file{~/.inputrc} file. Here is an example:
|
||||
|
||||
@example
|
||||
# This is a comment line.
|
||||
Meta-Rubout: backward-kill-word
|
||||
Control-u: universal-argument
|
||||
@end example
|
||||
|
||||
@menu
|
||||
* Commands For Moving:: Moving about the line.
|
||||
* Commands For History:: Getting at previous lines.
|
||||
* Commands For Text:: Commands for changing text.
|
||||
* Commands For Killing:: Commands for killing and yanking.
|
||||
* Numeric Arguments:: Specifying numeric arguments, repeat counts.
|
||||
* Commands For Completion:: Getting Readline to do the typing for you.
|
||||
* Miscellaneous Commands:: Other miscillaneous commands.
|
||||
@end menu
|
||||
|
||||
@node Commands For Moving, Commands For History, Readline Init Syntax, Readline Init Syntax
|
||||
@appendixsubsubsec Moving
|
||||
@table @code
|
||||
@item beginning-of-line (C-a)
|
||||
Move to the start of the current line.
|
||||
|
||||
@item end-of-line (C-e)
|
||||
Move to the end of the line.
|
||||
|
||||
@item forward-char (C-f)
|
||||
Move forward a character.
|
||||
|
||||
@item backward-char (C-b)
|
||||
Move back a character.
|
||||
|
||||
@item forward-word (M-f)
|
||||
Move forward to the end of the next word.
|
||||
|
||||
@item backward-word (M-b)
|
||||
Move back to the start of this, or the previous, word.
|
||||
|
||||
@item clear-screen (C-l)
|
||||
Clear the screen leaving the current line at the top of the screen.
|
||||
|
||||
@end table
|
||||
|
||||
@node Commands For History, Commands For Text, Commands For Moving, Readline Init Syntax
|
||||
@appendixsubsubsec Using the History
|
||||
|
||||
@table @code
|
||||
@item accept-line (Newline, Return)
|
||||
Accept the line regardless of where the cursor is. If this line is
|
||||
non-empty, add it to the history list. If this line was a history
|
||||
line, then restore the history line to its original state.
|
||||
|
||||
@item previous-history (C-p)
|
||||
Move `up' through the history list.
|
||||
|
||||
@item next-history (C-n)
|
||||
Move `down' through the history list.
|
||||
|
||||
@item beginning-of-history (M-<)
|
||||
Move to the first line in the history.
|
||||
|
||||
@item end-of-history (M->)
|
||||
Move to the end of the input history, i.e., the line you are entering!
|
||||
|
||||
@item reverse-search-history (C-r)
|
||||
Search backward starting at the current line and moving `up' through
|
||||
the history as necessary. This is an incremental search.
|
||||
|
||||
@item forward-search-history (C-s)
|
||||
Search forward starting at the current line and moving `down' through
|
||||
the the history as neccessary.
|
||||
|
||||
@end table
|
||||
|
||||
@node Commands For Text, Commands For Killing, Commands For History, Readline Init Syntax
|
||||
@appendixsubsubsec Changing Text
|
||||
|
||||
@table @code
|
||||
@item delete-char (C-d)
|
||||
Delete the character under the cursor. If the cursor is at the
|
||||
beginning of the line, and there are no characters in the line, and
|
||||
the last character typed was not C-d, then return EOF.
|
||||
|
||||
@item backward-delete-char (Rubout)
|
||||
Delete the character behind the cursor. A numeric arg says to kill
|
||||
the characters instead of deleting them.
|
||||
|
||||
@item quoted-insert (C-q, C-v)
|
||||
Add the next character that you type to the line verbatim. This is
|
||||
how to insert things like C-q for example.
|
||||
|
||||
@item tab-insert (M-TAB)
|
||||
Insert a tab character.
|
||||
|
||||
@item self-insert (a, b, A, 1, !, ...)
|
||||
Insert an ordinary printing character into the line.
|
||||
|
||||
@item transpose-chars (C-t)
|
||||
Drag the character before point forward over the character at point.
|
||||
Point moves forward as well. If point is at the end of the line, then
|
||||
transpose the two characters before point. Negative args don't work.
|
||||
|
||||
@item transpose-words (M-t)
|
||||
Drag the word behind the cursor past the word in front of the cursor
|
||||
moving the cursor over that word as well.
|
||||
|
||||
@item upcase-word (M-u)
|
||||
Uppercase the current (or following) word. With a negative argument,
|
||||
do the previous word, but do not move point.
|
||||
|
||||
@item downcase-word (M-l)
|
||||
Lowercase the current (or following) word. With a negative argument,
|
||||
do the previous word, but do not move point.
|
||||
|
||||
@item capitalize-word (M-c)
|
||||
Uppercase the current (or following) word. With a negative argument,
|
||||
do the previous word, but do not move point.
|
||||
|
||||
@end table
|
||||
|
||||
@node Commands For Killing, Numeric Arguments, Commands For Text, Readline Init Syntax
|
||||
@appendixsubsubsec Killing And Yanking
|
||||
|
||||
@table @code
|
||||
|
||||
@item kill-line (C-k)
|
||||
Kill the text from the current cursor position to the end of the line.
|
||||
|
||||
@item backward-kill-line ()
|
||||
Kill backward to the beginning of the line. This is normally unbound.
|
||||
|
||||
@item kill-word (M-d)
|
||||
Kill from the cursor to the end of the current word, or if between
|
||||
words, to the end of the next word.
|
||||
|
||||
@item backward-kill-word (M-DEL)
|
||||
Kill the word behind the cursor.
|
||||
|
||||
@item unix-line-discard (C-u)
|
||||
Kill the entire line. This is similar to the use of the Unix kill
|
||||
character (often also @key{C-u}), save that here the killed text can be
|
||||
retrieved later (since it goes on the kill-ring).
|
||||
|
||||
@item unix-word-rubout (C-w)
|
||||
Kill the current word, like the Unix word erase character. The killed
|
||||
text goes on the kill-ring. This is different than
|
||||
@code{backward-kill-word} because the word boundaries differ.
|
||||
|
||||
@item yank (C-y)
|
||||
Yank the top of the kill ring into the buffer at point.
|
||||
|
||||
@item yank-pop (M-y)
|
||||
Rotate the kill-ring, and yank the new top. You can only do this if
|
||||
the prior command is @code{yank} or @code{yank-pop}.
|
||||
@end table
|
||||
|
||||
@node Numeric Arguments, Commands For Completion, Commands For Killing, Readline Init Syntax
|
||||
@appendixsubsubsec Numeric Arguments
|
||||
@table @code
|
||||
|
||||
@item digit-argument (M-0, M-1, ... M--)
|
||||
Add this digit to the argument already accumulating, or start a new
|
||||
argument. @kbd{M--} starts a negative argument.
|
||||
|
||||
@item universal-argument ()
|
||||
Do what @key{C-u} does in emacs. By default, this is not bound to any keys.
|
||||
@end table
|
||||
|
||||
|
||||
@node Commands For Completion, Miscellaneous Commands, Numeric Arguments, Readline Init Syntax
|
||||
@appendixsubsubsec Letting Readline Type
|
||||
|
||||
@table @code
|
||||
@item complete (TAB)
|
||||
Attempt to do completion on the text before point. This is
|
||||
implementation defined. Generally, if you are typing a filename
|
||||
argument, you can do filename completion; if you are typing a command,
|
||||
you can do command completion, if you are typing in a symbol to GDB, you
|
||||
can do symbol name completion, if you are typing in a variable to Bash,
|
||||
you can do variable name completion...
|
||||
|
||||
@item possible-completions (M-?)
|
||||
List the possible completions of the text before point.
|
||||
@end table
|
||||
|
||||
@node Miscellaneous Commands, , Commands For Completion, Readline Init Syntax
|
||||
@appendixsubsubsec Other Commands
|
||||
@table @code
|
||||
|
||||
@item abort (@kbd{C-g})
|
||||
The line editing commands @code{reverse-search-history} (@kbd{C-r}) and
|
||||
@code{forward-search-history} (@kbd{C-s} go into a separate input mode;
|
||||
you can abort the search, and return to normal input mode, by using the
|
||||
@code{abort} (@kbd{C-g}) command.
|
||||
|
||||
@item do-uppercase-version (@kbd{M-a}, @kbd{M-b}, @dots)
|
||||
Run the command that is bound to your uppercase brother.
|
||||
|
||||
@item prefix-meta (@key{ESC})
|
||||
Make the next character that you type be metafied. This is for
|
||||
people without a meta key. @kbd{@key{ESC}-f} is equivalent to @kbd{M-f}.
|
||||
|
||||
@item undo (@kbd{C-_})
|
||||
Incremental undo, separately remembered for each line.
|
||||
|
||||
@item revert-line (@kbd{M-r})
|
||||
Undo all changes made to this line. This is like typing the `undo'
|
||||
command enough times to get back to the beginning.
|
||||
@end table
|
||||
|
||||
@node Readline vi Mode, , Readline Init Syntax, Readline Init File
|
||||
@appendixsubsec Readline @code{vi} Mode
|
||||
|
||||
While the Readline library does not have a full set of @code{vi} editing
|
||||
functions, it does contain enough to allow simple editing of the line.
|
||||
|
||||
In order to switch interactively between Emacs and @code{vi} editing modes, use
|
||||
the command @kbd{M-C-j} (@code{toggle-editing-mode}).
|
||||
|
||||
When you enter a line in @code{vi} mode, you are already in
|
||||
``insertion'' mode, as if you had typed an @kbd{i}. Pressing @key{ESC}
|
||||
switches you into ``edit'' mode, where you can edit the text of the line
|
||||
with the standard @code{vi} movement keys, move to previous history
|
||||
lines with @kbd{k}, to following lines with @kbd{j}, and so forth.
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,438 @@
|
|||
\input texinfo @c -*-texinfo-*-
|
||||
@comment %**start of header (This is for running Texinfo on a region.)
|
||||
@setfilename readline.info
|
||||
@settitle Line Editing Commands
|
||||
@comment %**end of header (This is for running Texinfo on a region.)
|
||||
@synindex fn vr
|
||||
|
||||
@c start-menu
|
||||
* Readline: (readline). The GNU Readline Library.
|
||||
@c end-menu
|
||||
|
||||
@iftex
|
||||
@comment finalout
|
||||
@end iftex
|
||||
|
||||
@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 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
|
||||
|
||||
@setchapternewpage odd
|
||||
@titlepage
|
||||
@sp 11
|
||||
@center @titlefont{GNU Readline Library}
|
||||
@sp 2
|
||||
@center by Brian Fox
|
||||
@sp 2
|
||||
@center Version 1.0
|
||||
@sp 2
|
||||
@center February 1989
|
||||
|
||||
@comment Include the Distribution inside the titlepage environment so
|
||||
@c that headings are turned off.
|
||||
|
||||
@page
|
||||
@vskip 0pt plus 1filll
|
||||
Copyright @copyright{} 1989 Free Software Foundation, Inc.
|
||||
|
||||
@sp 2
|
||||
This document describes the GNU Readline Library, a utility for aiding
|
||||
in the consistency of user interface across discrete programs that need
|
||||
to provide a command line interface.
|
||||
@sp 2
|
||||
|
||||
Published by the Free Software Foundation @*
|
||||
675 Massachusetts Avenue, @*
|
||||
Cambridge, MA 02139 USA
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of
|
||||
this manual provided the copyright notice and this permission notice
|
||||
are preserved on all copies.
|
||||
|
||||
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 titlepage
|
||||
|
||||
@node Top, Readline Top, ,(DIR)
|
||||
@chapter GNU Readline Library
|
||||
|
||||
@ifinfo
|
||||
This document describes the GNU Readline Library, a utility for aiding
|
||||
in the consistency of user interface across discrete programs that need
|
||||
to provide a command line interface.
|
||||
@end ifinfo
|
||||
|
||||
@menu
|
||||
* Readline Top:: GNU Readline User's Manual
|
||||
* Readline Technical:: GNU Readline Programmer's Manual
|
||||
@end menu
|
||||
@include inc-readline.texinfo
|
||||
@node Readline Technical, , Top, Top
|
||||
@chapter Readline Programmer's Manual
|
||||
|
||||
This manual describes the interface between the GNU Readline Library and
|
||||
user programs. If you are a programmer, and you wish to include the
|
||||
features found in GNU Readline in your own programs, such as completion,
|
||||
line editing, and interactive history manipulation, this documentation
|
||||
is for you.
|
||||
|
||||
@menu
|
||||
* Default Behaviour:: Using the default behaviour of Readline.
|
||||
* Custom Functions:: Adding your own functions to Readline.
|
||||
* Custom Completers:: Supplanting or supplementing Readline's
|
||||
completion functions.
|
||||
* Variable Index:: Index of externally tweakable variables.
|
||||
@end menu
|
||||
|
||||
@node Default Behaviour, Custom Functions, Readline Technical, Readline Technical
|
||||
@section Default Behaviour
|
||||
|
||||
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 ()}.
|
||||
|
||||
@findex readline ()
|
||||
@cindex readline, function
|
||||
The function @code{readline} prints a prompt and then reads and returns
|
||||
a single line of text from the user. The line which @code{readline ()}
|
||||
returns is allocated with @code{malloc ()}; you should @code{free ()}
|
||||
the line when you are done with it. The declaration in ANSI C is
|
||||
|
||||
@example
|
||||
@code{char *readline (char *@var{prompt});}
|
||||
@end example
|
||||
or, preferably,
|
||||
@example
|
||||
@code{#include <readline/readline.h>}
|
||||
@end example
|
||||
|
||||
So, one might say
|
||||
@example
|
||||
@code{char *line = readline ("Enter a line: ");}
|
||||
@end example
|
||||
in order to read a line of text from the user.
|
||||
|
||||
The line which is returned has the final newline removed, so only the
|
||||
text of the line remains.
|
||||
|
||||
If readline encounters an 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 was 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
|
||||
|
||||
If you use @code{add_history ()}, you should also
|
||||
@code{#include <readline/history.h>}
|
||||
For full details on the GNU History Library, see the associated manual.
|
||||
|
||||
It is polite to avoid saving empty lines on the history list, since
|
||||
no one has a burning need to reuse a blank line. Here is a function
|
||||
which usefully replaces the standard @code{gets ()} library function:
|
||||
|
||||
@example
|
||||
#include <readline/readline.h>
|
||||
#include <readline/history.h>
|
||||
|
||||
/* A static variable for holding the line. */
|
||||
static char *my_gets_line = (char *)NULL;
|
||||
|
||||
/* Read a string, and return a pointer to it. Returns NULL on EOF. */
|
||||
char *
|
||||
my_gets ()
|
||||
@{
|
||||
/* If the buffer has already been allocated, return the memory
|
||||
to the free pool. */
|
||||
if (my_gets_line != (char *)NULL)
|
||||
free (my_gets_line);
|
||||
|
||||
/* Get a line from the user. */
|
||||
my_gets_line = readline ("");
|
||||
|
||||
/* If the line has any text in it, save it on the history. */
|
||||
if (my_get_line && *my_gets_line)
|
||||
add_history (my_gets_line);
|
||||
|
||||
return (my_gets_line);
|
||||
@}
|
||||
@end example
|
||||
|
||||
The above code 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 ()}.
|
||||
|
||||
@findex rl_bind_key ()
|
||||
|
||||
@example
|
||||
@code{int rl_bind_key (int @var{key}, (int (*)())@var{function});}
|
||||
@end example
|
||||
|
||||
@code{rl_bind_key ()} takes 2 arguments; @var{key} is the character that
|
||||
you want to bind, and @var{function} is the address of the function to
|
||||
run when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert ()}
|
||||
makes @key{TAB} just insert itself.
|
||||
|
||||
@code{rl_bind_key ()} returns non-zero if @var{key} is not a valid
|
||||
ASCII character code (between 0 and 255).
|
||||
|
||||
@example
|
||||
@code{rl_bind_key ('\t', rl_insert);}
|
||||
@end example
|
||||
|
||||
@node Custom Functions, Custom Completers, Default Behaviour, Readline Technical
|
||||
@section Custom Functions
|
||||
|
||||
Readline provides a great 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 in within the Readline library which allow a user program to add
|
||||
customized functionality to Readline.
|
||||
|
||||
@menu
|
||||
* The Function Type:: C declarations to make code readable.
|
||||
* Function Naming:: How to give a function you write a name.
|
||||
* Keymaps:: Making keymaps.
|
||||
* Binding Keys:: Changing Keymaps.
|
||||
* Function Writing:: Variables and calling conventions.
|
||||
* Allowing Undoing:: How to make your functions undoable.
|
||||
@end menu
|
||||
|
||||
@node The Function Type, Function Naming, Custom Functions, Custom Functions
|
||||
For the sake of readabilty, we declare a new type of object, called
|
||||
@dfn{Function}. `Function' is a C language function which returns an
|
||||
@code{int}. The type declaration for `Function' is:
|
||||
|
||||
@code{typedef int Function ();}
|
||||
|
||||
The reason for declaring this new type is to make it easier to discuss
|
||||
pointers to C functions. Let us say we had a variable called @var{func}
|
||||
which was a pointer to a function. Instead of the classic C declaration
|
||||
|
||||
@code{int (*)()func;}
|
||||
|
||||
we have
|
||||
|
||||
@code{Function *func;}
|
||||
|
||||
@node Function Naming, Keymaps, The Function Type, Custom Functions
|
||||
@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 @key{Meta-Rubout} to the function @emph{descriptively} named
|
||||
@code{backward-kill-word}. You, as a programmer, should bind the
|
||||
functions you write to descriptive names as well. Here is how to do
|
||||
that.
|
||||
|
||||
@defun 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 defun
|
||||
|
||||
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 already. If you need to do more or different
|
||||
things than adding a function to Readline, you may need to use the
|
||||
underlying functions described below.
|
||||
|
||||
@node Keymaps, Binding Keys, Function Naming, Custom Functions
|
||||
@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.
|
||||
|
||||
@defun 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 defun
|
||||
|
||||
@defun rl_copy_keymap (Keymap map)
|
||||
Return a new keymap which is a copy of @var{map}.
|
||||
@end defun
|
||||
|
||||
@defun 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 defun
|
||||
|
||||
@node Binding Keys, Function Writing, Keymaps, Custom Functions
|
||||
@subsection Binding Keys
|
||||
|
||||
You associate keys with functions through the keymap. Here are
|
||||
the functions for doing that.
|
||||
|
||||
@defun rl_bind_key (int key, Function *function)
|
||||
Binds @var{key} to @var{function} in the currently selected keymap.
|
||||
Returns non-zero in the case of an invalid @var{key}.
|
||||
@end defun
|
||||
|
||||
@defun 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 defun
|
||||
|
||||
@defun rl_unbind_key (int key)
|
||||
Make @var{key} do nothing in the currently selected keymap.
|
||||
Returns non-zero in case of error.
|
||||
@end defun
|
||||
|
||||
@defun rl_unbind_key_in_map (int key, Keymap map)
|
||||
Make @var{key} be bound to the null function in @var{map}.
|
||||
Returns non-zero in case of error.
|
||||
@end defun
|
||||
|
||||
@node Function Writing, Allowing Undoing, Binding Keys, Custom Functions
|
||||
@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 gathered so far.
|
||||
|
||||
@defvar char *rl_line_buffer
|
||||
This is the line gathered so far. You are welcome to modify the
|
||||
contents of this, but see Undoing, below.
|
||||
@end defvar
|
||||
|
||||
@defvar int rl_point
|
||||
The offset of the current cursor position in @var{rl_line_buffer}.
|
||||
@end defvar
|
||||
|
||||
@defvar int rl_end
|
||||
The number of characters present in @code{rl_line_buffer}. When
|
||||
@code{rl_point} is at the end of the line, then @code{rl_point} and
|
||||
@code{rl_end} are equal.
|
||||
@end defvar
|
||||
|
||||
The calling sequence for a command @code{foo} looks like
|
||||
|
||||
@example
|
||||
@code{foo (count, key)}
|
||||
@end example
|
||||
|
||||
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, other
|
||||
functions as a flag, and 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 a negative argument as well as a positive
|
||||
argument. At the very least, it should be aware that it can be passed a
|
||||
negative argument.
|
||||
|
||||
@node Allowing Undoing, , Function Writing, Custom Functions
|
||||
@subsection Allowing Undoing
|
||||
|
||||
Supporting the undo command is a painless thing to do, and makes your
|
||||
function much more useful to the end user. 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 it
|
||||
calls @code{rl_insert_text ()} or @code{rl_delete_text ()} to do it, then
|
||||
undoing is already done for you automatically, and you can safely skip
|
||||
this section.
|
||||
|
||||
If you do multiple insertions or multiple deletions, or any combination
|
||||
of these operations, you will want to group them together into one
|
||||
operation. This can be done with @code{rl_begin_undo_group ()} and
|
||||
@code{rl_end_undo_group ()}.
|
||||
|
||||
@defun 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 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
|
||||
|
||||
Let us say that we are actually going to put an example here.
|
||||
|
||||
@node Custom Completers, Variable Index, Custom Functions, Readline Technical
|
||||
|
||||
Typically, a program that reads commands from the user has a way of
|
||||
disambiguating between 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
|
||||
@end menu
|
||||
|
||||
@node Variable Index, , Custom Completers, Readline Technical
|
||||
@appendix Variable Index
|
||||
@printindex vr
|
||||
@contents
|
||||
|
||||
@bye
|
||||
|
||||
Loading…
Reference in New Issue