2 This file documents the user interface to the GNU History library.
4 Copyright (C) 1988, 1991, 1994, 1996 Free Software Foundation, Inc.
5 Authored by Brian Fox and Chet Ramey.
7 Permission is granted to make and distribute verbatim copies of this manual
8 provided the copyright notice and this permission notice are preserved on
11 Permission is granted to process this file through Tex and print the
12 results, provided the printed document carries copying permission notice
13 identical to this one except for the removal of this paragraph (this
14 paragraph not being relevant to the printed manual).
16 Permission is granted to copy and distribute modified versions of this
17 manual under the conditions for verbatim copying, provided also that the
18 GNU Copyright statement is available to the distributee, and provided that
19 the entire resulting derived work is distributed under the terms of a
20 permission notice identical to this one.
22 Permission is granted to copy and distribute translations of this manual
23 into another language, under the above conditions for modified versions.
26 @node Programming with GNU History
27 @chapter Programming with GNU History
29 This chapter describes how to interface programs that you write
30 with the GNU History Library.
31 It should be considered a technical guide.
32 For information on the interactive use of GNU History, @pxref{Using
33 History Interactively}.
36 * Introduction to History:: What is the GNU History library for?
37 * History Storage:: How information is stored.
38 * History Functions:: Functions that you can use.
39 * History Variables:: Variables that control behaviour.
40 * History Programming Example:: Example of using the GNU History Library.
43 @node Introduction to History
44 @section Introduction to History
46 Many programs read input from the user a line at a time. The GNU History
47 library is able to keep track of those lines, associate arbitrary data with
48 each line, and utilize information from previous lines in composing new
51 The programmer using the History library has available functions
52 for remembering lines on a history list, associating arbitrary data
53 with a line, removing lines from the list, searching through the list
54 for a line containing an arbitrary text string, and referencing any line
55 in the list directly. In addition, a history @dfn{expansion} function
56 is available which provides for a consistent user interface across
59 The user using programs written with the History library has the
60 benefit of a consistent user interface with a set of well-known
61 commands for manipulating the text of previous lines and using that text
62 in new commands. The basic history manipulation commands are similar to
63 the history substitution provided by @code{csh}.
65 If the programmer desires, he can use the Readline library, which
66 includes some history manipulation by default, and has the added
67 advantage of command line editing.
70 @section History Storage
72 The history list is an array of history entries. A history entry is
76 typedef struct _hist_entry @{
82 The history list itself might therefore be declared as
85 HIST_ENTRY **the_history_list;
88 The state of the History library is encapsulated into a single structure:
91 /* A structure used to pass the current state of the history stuff around. */
92 typedef struct _hist_state @{
93 HIST_ENTRY **entries; /* Pointer to the entries themselves. */
94 int offset; /* The location pointer within this array. */
95 int length; /* Number of elements within this array. */
96 int size; /* Number of slots allocated to this array. */
101 If the flags member includes @code{HS_STIFLED}, the history has been
104 @node History Functions
105 @section History Functions
107 This section describes the calling sequence for the various functions
108 present in GNU History.
111 * Initializing History and State Management:: Functions to call when you
112 want to use history in a
114 * History List Management:: Functions used to manage the list
116 * Information About the History List:: Functions returning information about
118 * Moving Around the History List:: Functions used to change the position
120 * Searching the History List:: Functions to search the history list
121 for entries containing a string.
122 * Managing the History File:: Functions that read and write a file
123 containing the history list.
124 * History Expansion:: Functions to perform csh-like history
128 @node Initializing History and State Management
129 @subsection Initializing History and State Management
131 This section describes functions used to initialize and manage
132 the state of the History library when you want to use the history
133 functions in your program.
135 @deftypefun void using_history ()
136 Begin a session in which the history functions might be used. This
137 initializes the interactive variables.
140 @deftypefun {HISTORY_STATE *} history_get_history_state ()
141 Return a structure describing the current state of the input history.
144 @deftypefun void history_set_history_state (HISTORY_STATE *state)
145 Set the state of the history list according to @var{state}.
148 @node History List Management
149 @subsection History List Management
151 These functions manage individual entries on the history list, or set
152 parameters managing the list itself.
154 @deftypefun void add_history (char *string)
155 Place @var{string} at the end of the history list. The associated data
156 field (if any) is set to @code{NULL}.
159 @deftypefun {HIST_ENTRY *} remove_history (int which)
160 Remove history entry at offset @var{which} from the history. The
161 removed element is returned so you can free the line, data,
162 and containing structure.
165 @deftypefun {HIST_ENTRY *} replace_history_entry (int which, char *line, char *data)
166 Make the history entry at offset @var{which} have @var{line} and @var{data}.
167 This returns the old entry so you can dispose of the data. In the case
168 of an invalid @var{which}, a @code{NULL} pointer is returned.
171 @deftypefun void clear_history ()
172 Clear the history list by deleting all the entries.
175 @deftypefun void stifle_history (int max)
176 Stifle the history list, remembering only the last @var{max} entries.
179 @deftypefun int unstifle_history ()
180 Stop stifling the history. This returns the previous amount the
181 history was stifled. The value is positive if the history was
182 stifled, negative if it wasn't.
185 @deftypefun int history_is_stifled ()
186 Returns non-zero if the history is stifled, zero if it is not.
189 @node Information About the History List
190 @subsection Information About the History List
192 These functions return information about the entire history list or
193 individual list entries.
195 @deftypefun {HIST_ENTRY **} history_list ()
196 Return a @code{NULL} terminated array of @code{HIST_ENTRY} which is the
197 current input history. Element 0 of this list is the beginning of time.
198 If there is no history, return @code{NULL}.
201 @deftypefun int where_history ()
202 Returns the offset of the current history element.
205 @deftypefun {HIST_ENTRY *} current_history ()
206 Return the history entry at the current position, as determined by
207 @code{where_history ()}. If there is no entry there, return a @code{NULL}
211 @deftypefun {HIST_ENTRY *} history_get (int offset)
212 Return the history entry at position @var{offset}, starting from
213 @code{history_base}. If there is no entry there, or if @var{offset}
214 is greater than the history length, return a @code{NULL} pointer.
217 @deftypefun int history_total_bytes ()
218 Return the number of bytes that the primary history entries are using.
219 This function returns the sum of the lengths of all the lines in the
223 @node Moving Around the History List
224 @subsection Moving Around the History List
226 These functions allow the current index into the history list to be
229 @deftypefun int history_set_pos (int pos)
230 Set the position in the history list to @var{pos}, an absolute index
234 @deftypefun {HIST_ENTRY *} previous_history ()
235 Back up the current history offset to the previous history entry, and
236 return a pointer to that entry. If there is no previous entry, return
237 a @code{NULL} pointer.
240 @deftypefun {HIST_ENTRY *} next_history ()
241 Move the current history offset forward to the next history entry, and
242 return the a pointer to that entry. If there is no next entry, return
243 a @code{NULL} pointer.
246 @node Searching the History List
247 @subsection Searching the History List
248 @cindex History Searching
250 These functions allow searching of the history list for entries containing
251 a specific string. Searching may be performed both forward and backward
252 from the current history position. The search may be @dfn{anchored},
253 meaning that the string must match at the beginning of the history entry.
254 @cindex anchored search
256 @deftypefun int history_search (char *string, int direction)
257 Search the history for @var{string}, starting at the current history
258 offset. If @var{direction} < 0, then the search is through previous entries,
259 else through subsequent. If @var{string} is found, then
260 the current history index is set to that history entry, and the value
261 returned is the offset in the line of the entry where
262 @var{string} was found. Otherwise, nothing is changed, and a -1 is
266 @deftypefun int history_search_prefix (char *string, int direction)
267 Search the history for @var{string}, starting at the current history
268 offset. The search is anchored: matching lines must begin with
269 @var{string}. If @var{direction} < 0, then the search is through previous
270 entries, else through subsequent. If @var{string} is found, then the
271 current history index is set to that entry, and the return value is 0.
272 Otherwise, nothing is changed, and a -1 is returned.
275 @deftypefun int history_search_pos (char *string, int direction, int pos)
276 Search for @var{string} in the history list, starting at @var{pos}, an
277 absolute index into the list. If @var{direction} is negative, the search
278 proceeds backward from @var{pos}, otherwise forward. Returns the absolute
279 index of the history element where @var{string} was found, or -1 otherwise.
282 @node Managing the History File
283 @subsection Managing the History File
285 The History library can read the history from and write it to a file.
286 This section documents the functions for managing a history file.
288 @deftypefun int read_history (char *filename)
289 Add the contents of @var{filename} to the history list, a line at a
290 time. If @var{filename} is @code{NULL}, then read from
291 @file{~/.history}. Returns 0 if successful, or errno if not.
294 @deftypefun int read_history_range (char *filename, int from, int to)
295 Read a range of lines from @var{filename}, adding them to the history list.
296 Start reading at line @var{from} and end at @var{to}. If
297 @var{from} is zero, start at the beginning. If @var{to} is less than
298 @var{from}, then read until the end of the file. If @var{filename} is
299 @code{NULL}, then read from @file{~/.history}. Returns 0 if successful,
300 or @code{errno} if not.
303 @deftypefun int write_history (char *filename)
304 Write the current history to @var{filename}, overwriting @var{filename}
305 if necessary. If @var{filename} is
306 @code{NULL}, then write the history list to @file{~/.history}. Values
307 returned are as in @code{read_history ()}.
310 @deftypefun int append_history (int nelements, char *filename)
311 Append the last @var{nelements} of the history list to @var{filename}.
314 @deftypefun int history_truncate_file (char *filename, int nlines)
315 Truncate the history file @var{filename}, leaving only the last
319 @node History Expansion
320 @subsection History Expansion
322 These functions implement @code{csh}-like history expansion.
324 @deftypefun int history_expand (char *string, char **output)
325 Expand @var{string}, placing the result into @var{output}, a pointer
326 to a string (@pxref{History Interaction}). Returns:
329 If no expansions took place (or, if the only change in
330 the text was the de-slashifying of the history expansion
333 if expansions did take place;
335 if there was an error in expansion;
337 if the returned line should only be displayed, but not executed,
338 as with the @code{:p} modifier (@pxref{Modifiers}).
341 If an error ocurred in expansion, then @var{output} contains a descriptive
345 @deftypefun {char *} history_arg_extract (int first, int last, char *string)
346 Extract a string segment consisting of the @var{first} through @var{last}
347 arguments present in @var{string}. Arguments are broken up as in Bash.
350 @deftypefun {char *} get_history_event (char *string, int *cindex, int qchar)
351 Returns the text of the history event beginning at @var{string} +
352 @var{*cindex}. @var{*cindex} is modified to point to after the event
353 specifier. At function entry, @var{cindex} points to the index into
354 @var{string} where the history event specification begins. @var{qchar}
355 is a character that is allowed to end the event specification in addition
356 to the ``normal'' terminating characters.
359 @deftypefun {char **} history_tokenize (char *string)
360 Return an array of tokens parsed out of @var{string}, much as the
361 shell might. The tokens are split on white space and on the
362 characters @code{()<>;&|$}, and shell quoting conventions are
366 @node History Variables
367 @section History Variables
369 This section describes the externally visible variables exported by
370 the GNU History Library.
372 @deftypevar int history_base
373 The logical offset of the first entry in the history list.
376 @deftypevar int history_length
377 The number of entries currently stored in the history list.
380 @deftypevar int max_input_history
381 The maximum number of history entries. This must be changed using
382 @code{stifle_history ()}.
385 @deftypevar char history_expansion_char
386 The character that starts a history event. The default is @samp{!}.
389 @deftypevar char history_subst_char
390 The character that invokes word substitution if found at the start of
391 a line. The default is @samp{^}.
394 @deftypevar char history_comment_char
395 During tokenization, if this character is seen as the first character
396 of a word, then it and all subsequent characters up to a newline are
397 ignored, suppressing history expansion for the remainder of the line.
398 This is disabled by default.
401 @deftypevar {char *} history_no_expand_chars
402 The list of characters which inhibit history expansion if found immediately
403 following @var{history_expansion_char}. The default is whitespace and
407 @deftypevar {char *} history_search_delimiter_chars
408 The list of additional characters which can delimit a history search
409 string, in addition to whitespace, @samp{:} and @samp{?} in the case of
410 a substring search. The default is empty.
413 @deftypevar int history_quotes_inhibit_expansion
414 If non-zero, single-quoted words are not scanned for the history expansion
415 character. The default value is 0.
418 @deftypevar {Function *} history_inhibit_expansion_function
419 This should be set to the address of a function that takes two arguments:
420 a @code{char *} (@var{string}) and an integer index into that string (@var{i}).
421 It should return a non-zero value if the history expansion starting at
422 @var{string[i]} should not be performed; zero if the expansion should
424 It is intended for use by applications like Bash that use the history
425 expansion character for additional purposes.
426 By default, this variable is set to NULL.
429 @node History Programming Example
430 @section History Programming Example
432 The following program demonstrates simple use of the GNU History Library.
445 printf ("history$ ");
447 t = fgets (line, sizeof (line) - 1, stdin);
451 if (t[len - 1] == '\n')
456 strcpy (line, "quit");
463 result = history_expand (line, &expansion);
465 fprintf (stderr, "%s\n", expansion);
467 if (result < 0 || result == 2)
473 add_history (expansion);
474 strncpy (line, expansion, sizeof (line) - 1);
478 if (strcmp (line, "quit") == 0)
480 else if (strcmp (line, "save") == 0)
481 write_history ("history_file");
482 else if (strcmp (line, "read") == 0)
483 read_history ("history_file");
484 else if (strcmp (line, "list") == 0)
486 register HIST_ENTRY **the_list;
489 the_list = history_list ();
491 for (i = 0; the_list[i]; i++)
492 printf ("%d: %s\n", i + history_base, the_list[i]->line);
494 else if (strncmp (line, "delete", 6) == 0)
497 if ((sscanf (line + 6, "%d", &which)) == 1)
499 HIST_ENTRY *entry = remove_history (which);
501 fprintf (stderr, "No such entry %d\n", which);
510 fprintf (stderr, "non-numeric arg given to `delete'\n");