From: K. Richard Pixley Date: Wed, 13 Nov 1991 21:01:55 +0000 (+0000) Subject: Initial revision X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=681fa9a853842192e71ead32593bdbff36d85b73;p=binutils-gdb.git Initial revision --- diff --git a/readline/history.texi b/readline/history.texi new file mode 100755 index 00000000000..7302edb3323 --- /dev/null +++ b/readline/history.texi @@ -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 diff --git a/readline/inc-hist.texi b/readline/inc-hist.texi new file mode 100755 index 00000000000..9bbb575d407 --- /dev/null +++ b/readline/inc-hist.texi @@ -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 diff --git a/readline/inc-read.texi b/readline/inc-read.texi new file mode 100755 index 00000000000..52a0e33f9a8 --- /dev/null +++ b/readline/inc-read.texi @@ -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. + + + + diff --git a/readline/readline.texi b/readline/readline.texi new file mode 100755 index 00000000000..578e1b7e9d5 --- /dev/null +++ b/readline/readline.texi @@ -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 } +@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 } +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 +#include + +/* 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 +