--- /dev/null
+\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
--- /dev/null
+@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
--- /dev/null
+@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.
+
+
+
+
--- /dev/null
+\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
+
projects / binutils-gdb.git / commitdiff