| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter describes how to interface programs that you write with the GNU History Library. It should be considered a technical guide. For information on the interactive use of GNU History, see section 1. Using History Interactively.
| 2.1 Introduction to History | What is the GNU History library for? | |
| 2.2 History Storage | How information is stored. | |
| 2.3 History Functions | Functions that you can use. | |
| 2.4 History Variables | Variables that control behaviour. | |
| 2.5 History Programming Example | Example of using the GNU History Library. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 composing new ones.
The programmer using the History library has available functions for remembering lines on a history list, associating arbitrary data with a line, removing lines from the list, searching through the list for a line containing an arbitrary text string, and referencing any line in the list directly. In addition, a history expansion function is available which provides for a consistent user interface across different programs.
The user using programs written with the History library has 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 provided 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 command line editing.
Before declaring any functions using any functionality the History
library provides in other code, an application writer should include
the file <readline/history.h> in any file that uses the
History library's features. It supplies extern declarations for all
of the library's public functions and variables, and declares all of
the public data structures.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The history list is an array of history entries. A history entry is declared as follows:
typedef void *histdata_t;
typedef struct _hist_entry {
char *line;
histdata_t data;
} HIST_ENTRY;
|
The history list itself might therefore be declared as
HIST_ENTRY **the_history_list; |
The state of the History library is encapsulated into a single structure:
/*
* A structure used to pass around the current state of the history.
*/
typedef struct _hist_state {
HIST_ENTRY **entries; /* Pointer to the entries themselves. */
int offset; /* The location pointer within this array. */
int length; /* Number of elements within this array. */
int size; /* Number of slots allocated to this array. */
int flags;
} HISTORY_STATE;
|
If the flags member includes HS_STIFLED, the history has been
stifled.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes the calling sequence for the various functions exported by the GNU History library.
| 2.3.1 Initializing History and State Management | Functions to call when you want to use history in a program. | |
| 2.3.2 History List Management | Functions used to manage the list of history entries. | |
| 2.3.3 Information About the History List | Functions returning information about the history list. | |
| 2.3.4 Moving Around the History List | Functions used to change the position in the history list. | |
| 2.3.5 Searching the History List | Functions to search the history list for entries containing a string. | |
| 2.3.6 Managing the History File | Functions that read and write a file containing the history list. | |
| 2.3.7 History Expansion | Functions to perform csh-like history expansion. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes functions used to initialize and manage the state of the History library when you want to use the history functions in your program.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These functions manage individual entries on the history list, or set parameters managing the list itself.
NULL.
NULL pointer is returned.
stifle_history()).
The value is positive if the history was
stifled, negative if it wasn't.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These functions return information about the entire history list or individual list entries.
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.
where_history(). If there is no entry there, return a NULL
pointer.
history_base (see section 2.4 History Variables).
If there is no entry there, or if offset
is greater than the history length, return a NULL pointer.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These functions allow the current index into the history list to be set or changed.
NULL pointer.
NULL pointer.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These functions allow searching of the history list for entries containing a specific string. Searching may be performed both forward and backward from the current history position. The search may be anchored, meaning that the string must match at the beginning of the history entry.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The History library can read the history from and write it to a file. This section documents the functions for managing a history file.
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 write the history list to
`~/.history'.
Returns 0 on success, or errno on a read or write error.
NULL, then append to `~/.history'.
Returns 0 on success, or errno on a read or write error.
NULL, then `~/.history' is truncated.
Returns 0 on success, or errno on failure.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These functions implement history expansion.
0
1
-1
2
:p modifier (see section 1.1.3 Modifiers).
If an error ocurred in expansion, then output contains a descriptive error message.
history_tokenize.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes the externally-visible variables exported by the GNU History Library.
stifle_history().
history_tokenize().
The default value is " \t\n()<>;&|".
char * (string)
and an int index into that string (i).
It should return a non-zero value if the history expansion starting at
string[i] should not be performed; zero if the expansion should
be done.
It is intended for use by applications like Bash that use the history
expansion character for additional purposes.
By default, this variable is set to NULL.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following program demonstrates simple use of the GNU History Library.
#include <stdio.h>
#include <readline/history.h>
main (argc, argv)
int argc;
char **argv;
{
char line[1024], *t;
int len, done = 0;
line[0] = 0;
using_history ();
while (!done)
{
printf ("history$ ");
fflush (stdout);
t = fgets (line, sizeof (line) - 1, stdin);
if (t && *t)
{
len = strlen (t);
if (t[len - 1] == '\n')
t[len - 1] = '\0';
}
if (!t)
strcpy (line, "quit");
if (line[0])
{
char *expansion;
int result;
result = history_expand (line, &expansion);
if (result)
fprintf (stderr, "%s\n", expansion);
if (result < 0 || result == 2)
{
free (expansion);
continue;
}
add_history (expansion);
strncpy (line, expansion, sizeof (line) - 1);
free (expansion);
}
if (strcmp (line, "quit") == 0)
done = 1;
else if (strcmp (line, "save") == 0)
write_history ("history_file");
else if (strcmp (line, "read") == 0)
read_history ("history_file");
else if (strcmp (line, "list") == 0)
{
register HIST_ENTRY **the_list;
register int i;
the_list = history_list ();
if (the_list)
for (i = 0; the_list[i]; i++)
printf ("%d: %s\n", i + history_base, the_list[i]->line);
}
else if (strncmp (line, "delete", 6) == 0)
{
int which;
if ((sscanf (line + 6, "%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");
}
}
}
}
|
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |