diff options
Diffstat (limited to 'contrib/gdb/readline/doc/hstech.texinfo')
| -rw-r--r-- | contrib/gdb/readline/doc/hstech.texinfo | 311 |
1 files changed, 0 insertions, 311 deletions
diff --git a/contrib/gdb/readline/doc/hstech.texinfo b/contrib/gdb/readline/doc/hstech.texinfo deleted file mode 100644 index c3fe3f6..0000000 --- a/contrib/gdb/readline/doc/hstech.texinfo +++ /dev/null @@ -1,311 +0,0 @@ -@ignore -This file documents the user interface to the GNU History library. - -Copyright (C) 1988, 1991 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. - -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 Programming with GNU History -@chapter Programming with GNU History - -This chapter describes how to interface the GNU History Library with -programs that you write. It should be considered a technical guide. -For information on the interactive use of GNU History, @pxref{Using -History Interactively}. - -@menu -* Introduction to History:: What is the GNU History library for? -* History Storage:: How information is stored. -* History Functions:: Functions that you can use. -* History Variables:: Variables that control behaviour. -* History Programming Example:: Example of using the GNU History Library. -@end menu - -@node Introduction to History -@section 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. - -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 @code{Csh}. - -If the programmer desires, he can use the Readline library, which -includes some history manipulation by default, and has the added -advantage of Emacs style command line editing. - -@node History Storage -@section History Storage - -@example -typedef struct _hist_entry @{ - char *line; - char *data; -@} HIST_ENTRY; -@end example - -@node History Functions -@section History Functions - -This section describes the calling sequence for the various functions -present in GNU History. - -@defun {void using_history} () -Begin a session in which the history functions might be used. This -just initializes the interactive variables. -@end defun - -@defun {void add_history} (char *string) -Place @var{string} at the end of the history list. The associated data -field (if any) is set to @code{NULL}. -@end defun - -@defun {int where_history} () -Returns the number which says what history element we are now looking -at. -@end defun - -@defun {int history_set_pos} (int pos) -Set the position in the history list to @var{pos}. -@end defun - -@defun {int history_search_pos} (char *string, int direction, int pos) -Search for @var{string} in the history list, starting at @var{pos}, an -absolute index into the list. @var{direction}, if negative, says to search -backwards from @var{pos}, else forwards. Returns the absolute index of -the history element where @var{string} was found, or -1 otherwise. -@end defun - -@defun {HIST_ENTRY *remove_history} (); -Remove history element @var{which} from the history. The removed -element is returned to you so you can free the line, data, -and containing structure. -@end defun - -@defun {void stifle_history} (int max) -Stifle the history list, remembering only @var{max} number of entries. -@end defun - -@defun {int unstifle_history} (); -Stop stifling the history. This returns the previous amount the -history was stifled by. The value is positive if the history was -stifled, negative if it wasn't. -@end defun - -@defun {int read_history} (char *filename) -Add the contents of @var{filename} to the history list, a line at a -time. If @var{filename} is @code{NULL}, then read from -@file{~/.history}. Returns 0 if successful, or errno if not. -@end defun - -@defun {int read_history_range} (char *filename, int from, int to) -Read a range of lines from @var{filename}, adding them to the history list. -Start reading at the @var{from}'th line and end at the @var{to}'th. If -@var{from} is zero, start at the beginning. If @var{to} is less than -@var{from}, then read until the end of the file. If @var{filename} is -@code{NULL}, then read from @file{~/.history}. Returns 0 if successful, -or @code{errno} if not. -@end defun - -@defun {int write_history} (char *filename) -Append the current history to @var{filename}. If @var{filename} is -@code{NULL}, then append the history list to @file{~/.history}. Values -returned are as in @code{read_history ()}. -@end defun - -@defun {int append_history} (int nelements, char *filename) -Append @var{nelement} entries to @var{filename}. The entries appended -are from the end of the list minus @var{nelements} up to the end of the -list. -@end defun - -@defun {HIST_ENTRY *replace_history_entry} () -Make the history entry at @var{which} have @var{line} and @var{data}. -This returns the old entry so you can dispose of the data. In the case -of an invalid @var{which}, a @code{NULL} pointer is returned. -@end defun - -@defun {HIST_ENTRY *current_history} () -Return the history entry at the current position, as determined by -@code{history_offset}. If there is no entry there, return a @code{NULL} -pointer. -@end defun - -@defun {HIST_ENTRY *previous_history} () -Back up @var{history_offset} to the previous history entry, and return a -pointer to that entry. If there is no previous entry, return a -@code{NULL} pointer. -@end defun - -@defun {HIST_ENTRY *next_history} () -Move @code{history_offset} forward to the next history entry, and return -the a pointer to that entry. If there is no next entry, return a -@code{NULL} pointer. -@end defun - -@defun {HIST_ENTRY **history_list} () -Return a @code{NULL} terminated array of @code{HIST_ENTRY} which is the -current input history. Element 0 of this list is the beginning of time. -If there is no history, return @code{NULL}. -@end defun - -@defun {int history_search} (char *string, int direction) -Search the history for @var{string}, starting at @code{history_offset}. -If @var{direction} < 0, then the search is through previous entries, -else through subsequent. If @var{string} is found, then -@code{current_history ()} is the history entry, and the value of this -function is the offset in the line of that history entry that the -@var{string} was found in. Otherwise, nothing is changed, and a -1 is -returned. -@end defun - -@defun {int history_expand} (char *string, char **output) -Expand @var{string}, placing the result into @var{output}, a pointer -to a string. Returns: -@table @code -@item 0 -If no expansions took place (or, if the only change in -the text was the de-slashifying of the history expansion -character), -@item 1 -if expansions did take place, or -@item -1 -if there was an error in expansion. -@end table - -If an error ocurred in expansion, then @var{output} contains a descriptive -error message. -@end defun - -@defun {char *history_arg_extract} (int first, int last, char *string) -Extract a string segment consisting of the @var{first} through @var{last} -arguments present in @var{string}. Arguments are broken up as in -the GNU Bash shell. -@end defun - -@defun {int history_total_bytes} (); -Return the number of bytes that the primary history entries are using. -This just adds up the lengths of @code{the_history->lines}. -@end defun - -@node History Variables -@section History Variables - -This section describes the variables in GNU History that are externally -visible. - -@defvar {int history_base} -For convenience only. You set this when interpreting history commands. -It is the logical offset of the first history element. -@end defvar - -@node History Programming Example -@section History Programming Example - -The following snippet of code demonstrates simple use of the GNU History -Library. - -@smallexample -main () -@{ - char line[1024], *t; - int done = 0; - - line[0] = 0; - - while (!done) - @{ - fprintf (stdout, "history%% "); - t = gets (line); - - if (!t) - strcpy (line, "quit"); - - if (line[0]) - @{ - char *expansion; - int result; - - using_history (); - - result = history_expand (line, &expansion); - strcpy (line, expansion); - free (expansion); - if (result) - fprintf (stderr, "%s\n", line); - - if (result < 0) - continue; - - add_history (line); - @} - - if (strcmp (line, "quit") == 0) done = 1; - if (strcmp (line, "save") == 0) write_history (0); - if (strcmp (line, "read") == 0) read_history (0); - if (strcmp (line, "list") == 0) - @{ - register HIST_ENTRY **the_list = history_list (); - register int i; - - if (the_list) - for (i = 0; the_list[i]; i++) - fprintf (stdout, "%d: %s\n", - i + history_base, the_list[i]->line); - @} - if (strncmp (line, "delete", strlen ("delete")) == 0) - @{ - int which; - if ((sscanf (line + strlen ("delete"), "%d", &which)) == 1) - @{ - HIST_ENTRY *entry = remove_history (which); - if (!entry) - fprintf (stderr, "No such entry %d\n", which); - else - @{ - free (entry->line); - free (entry); - @} - @} - else - @{ - fprintf (stderr, "non-numeric arg given to `delete'\n"); - @} - @} - @} -@} -@end smallexample - - - |
