diff options
Diffstat (limited to 'gdb/readline')
| -rw-r--r-- | gdb/readline/ChangeLog | 15 | ||||
| -rw-r--r-- | gdb/readline/Makefile | 4 | ||||
| -rw-r--r-- | gdb/readline/history.texinfo | 194 | ||||
| -rw-r--r-- | gdb/readline/readline.c | 3 | ||||
| -rw-r--r-- | gdb/readline/readline.texinfo | 425 |
5 files changed, 637 insertions, 4 deletions
diff --git a/gdb/readline/ChangeLog b/gdb/readline/ChangeLog index 58a5784..b72a59d 100644 --- a/gdb/readline/ChangeLog +++ b/gdb/readline/ChangeLog @@ -1,9 +1,22 @@ +Thu Feb 8 01:04:00 1990 Jim Kingdon (kingdon at pogo.ai.mit.edu) + + * Makefile (the *other* libreadline.a): Uncomment out ranlib line. + +Thu Feb 1 17:50:22 1990 Jim Kingdon (kingdon at pogo.ai.mit.edu) + + * Makefile (libreadline.a): Uncomment out ranlib line. + +Sun Nov 26 16:29:11 1989 Jim Kingdon (kingdon at hobbes.ai.mit.edu) + + * readline.c (rl_deprep_terminal): Only restore local_mode_flags + if they had been set. + Thu Oct 19 17:18:40 1989 Jim Kingdon (kingdon at hobbes.ai.mit.edu) * Move vi_doing_insert from vi_mode.c to readline.c * readline.c: Move compare_strings before its use. - Remove definitions. + Remove declarations. * readline.c: Move defining_kbd_macro above rl_dispatch. (rl_dispatch): Remove "extern int defining_kbd_macro". diff --git a/gdb/readline/Makefile b/gdb/readline/Makefile index fadca97..dc11539 100644 --- a/gdb/readline/Makefile +++ b/gdb/readline/Makefile @@ -65,7 +65,7 @@ all: libreadline.a libreadline.a: readline.o history.o funmap.o keymaps.o $(RM) -f libreadline.a $(AR) clq libreadline.a readline.o history.o funmap.o keymaps.o -# if [ -f $(RANLIB) ]; then $(RANLIB) libreadline.a; fi + if [ -f $(RANLIB) ]; then $(RANLIB) libreadline.a; fi readline.o: readline.h chardefs.h keymaps.h history.h readline.c vi_mode.c $(CC) -c $(CFLAGS) $(CPPFLAGS) $(READLINE_DEFINES) \ @@ -111,4 +111,4 @@ clean: $(DESTDIR)/libreadline.a: libreadline.a -mv $(DESTDIR)/libreadline.a $(DESTDIR)/libreadline.old cp libreadline.a $(DESTDIR)/libreadline.a -# $(RANLIB) -t $(DESTDIR)/libreadline.a + $(RANLIB) -t $(DESTDIR)/libreadline.a diff --git a/gdb/readline/history.texinfo b/gdb/readline/history.texinfo new file mode 100644 index 0000000..526d66d --- /dev/null +++ b/gdb/readline/history.texinfo @@ -0,0 +1,194 @@ +\input texinfo.tex +@setfilename history.info + +@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. + +@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 + +@node Programming, , Interactive Use, Top +@chapter Programming + +@bye + diff --git a/gdb/readline/readline.c b/gdb/readline/readline.c index 0185e13..c111491 100644 --- a/gdb/readline/readline.c +++ b/gdb/readline/readline.c @@ -2078,7 +2078,8 @@ rl_deprep_terminal () int tty = fileno (rl_instream); #if defined (TIOCLGET) && defined (LPASS8) - ioctl (tty, TIOCLSET, &local_mode_flags); + if ((the_ttybuff.sg_flags & (ODDP | EVENP)) == (ODDP | EVENP)) + ioctl (tty, TIOCLSET, &local_mode_flags); #endif #ifdef TIOCSLTC diff --git a/gdb/readline/readline.texinfo b/gdb/readline/readline.texinfo new file mode 100644 index 0000000..40e5211 --- /dev/null +++ b/gdb/readline/readline.texinfo @@ -0,0 +1,425 @@ +\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 + +@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 + +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 + +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 +/* 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 + |