diff options
Diffstat (limited to 'readline/doc/hstech.texinfo')
| -rw-r--r-- | readline/doc/hstech.texinfo | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/readline/doc/hstech.texinfo b/readline/doc/hstech.texinfo new file mode 100644 index 0000000..c3fe3f6 --- /dev/null +++ b/readline/doc/hstech.texinfo @@ -0,0 +1,311 @@ +@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 + + + |