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, see section Using History Interactively.
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 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 some history manipulation by default, and has the added advantage of Emacs style command line editing.
typedef struct _hist_entry { char *line; char *data; } HIST_ENTRY;
This section describes the calling sequence for the various functions present in GNU History.
NULL
.
NULL
, then read from
`~/.history'. Returns 0 if successful, or errno if not.
NULL
, then read from `~/.history'. Returns 0 if successful,
or errno
if not.
NULL
, then append the history list to `~/.history'. Values
returned are as in read_history ()
.
NULL
pointer is returned.
history_offset
. If there is no entry there, return a NULL
pointer.
NULL
pointer.
history_offset
forward to the next history entry, and return
the a pointer to that entry. If there is no next entry, return a
NULL
pointer.
NULL
terminated array of HIST_ENTRY
which is the
current input history. Element 0 of this list is the beginning of time.
If there is no history, return NULL
.
history_offset
.
If direction < 0, then the search is through previous entries,
else through subsequent. If string is found, then
current_history ()
is the history entry, and the value of this
function is the offset in the line of that history entry that the
string was found in. Otherwise, nothing is changed, and a -1 is
returned.
0
1
-1
If an error ocurred in expansion, then output contains a descriptive error message.
the_history->lines
.
This section describes the variables in GNU History that are externally visible.
The following snippet of code demonstrates simple use of the GNU History Library.
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"); } } } }
Go to the first, previous, next, last section, table of contents.