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.
69 Before declaring any functions using any functionality the History
70 library provides in other code, an application writer should include
71 the file @code{<readline/history.h>} in any file that uses the
72 History library's features. It supplies extern declarations for all
73 of the library's public functions and variables, and declares all of
74 the public data structures.
77 @section History Storage
79 The history list is an array of history entries. A history entry is
83 typedef struct _hist_entry @{
89 The history list itself might therefore be declared as
92 HIST_ENTRY **the_history_list;
95 The state of the History library is encapsulated into a single structure:
98 /* A structure used to pass the current state of the history stuff around. */
99 typedef struct _hist_state @{
100 HIST_ENTRY **entries; /* Pointer to the entries themselves. */
101 int offset; /* The location pointer within this array. */
102 int length; /* Number of elements within this array. */
103 int size; /* Number of slots allocated to this array. */
108 If the flags member includes @code{HS_STIFLED}, the history has been
111 @node History Functions
112 @section History Functions
114 This section describes the calling sequence for the various functions
115 present in GNU History.
118 * Initializing History and State Management:: Functions to call when you
119 want to use history in a
121 * History List Management:: Functions used to manage the list
123 * Information About the History List:: Functions returning information about
125 * Moving Around the History List:: Functions used to change the position
127 * Searching the History List:: Functions to search the history list
128 for entries containing a string.
129 * Managing the History File:: Functions that read and write a file
130 containing the history list.
131 * History Expansion:: Functions to perform csh-like history
135 @node Initializing History and State Management
136 @subsection Initializing History and State Management
138 This section describes functions used to initialize and manage
139 the state of the History library when you want to use the history
140 functions in your program.
142 @deftypefun void using_history ()
143 Begin a session in which the history functions might be used. This
144 initializes the interactive variables.
147 @deftypefun {HISTORY_STATE *} history_get_history_state ()
148 Return a structure describing the current state of the input history.
151 @deftypefun void history_set_history_state (HISTORY_STATE *state)
152 Set the state of the history list according to @var{state}.
155 @node History List Management
156 @subsection History List Management
158 These functions manage individual entries on the history list, or set
159 parameters managing the list itself.
161 @deftypefun void add_history (char *string)
162 Place @var{string} at the end of the history list. The associated data
163 field (if any) is set to @code{NULL}.
166 @deftypefun {HIST_ENTRY *} remove_history (int which)
167 Remove history entry at offset @var{which} from the history. The
168 removed element is returned so you can free the line, data,
169 and containing structure.
172 @deftypefun {HIST_ENTRY *} replace_history_entry (int which, char *line, char *data)
173 Make the history entry at offset @var{which} have @var{line} and @var{data}.
174 This returns the old entry so you can dispose of the data. In the case
175 of an invalid @var{which}, a @code{NULL} pointer is returned.
178 @deftypefun void clear_history ()
179 Clear the history list by deleting all the entries.
182 @deftypefun void stifle_history (int max)
183 Stifle the history list, remembering only the last @var{max} entries.
186 @deftypefun int unstifle_history ()
187 Stop stifling the history. This returns the previous amount the
188 history was stifled. The value is positive if the history was
189 stifled, negative if it wasn't.
192 @deftypefun int history_is_stifled ()
193 Returns non-zero if the history is stifled, zero if it is not.
196 @node Information About the History List
197 @subsection Information About the History List
199 These functions return information about the entire history list or
200 individual list entries.
202 @deftypefun {HIST_ENTRY **} history_list ()
203 Return a @code{NULL} terminated array of @code{HIST_ENTRY} which is the
204 current input history. Element 0 of this list is the beginning of time.
205 If there is no history, return @code{NULL}.
208 @deftypefun int where_history ()
209 Returns the offset of the current history element.
212 @deftypefun {HIST_ENTRY *} current_history ()
213 Return the history entry at the current position, as determined by
214 @code{where_history ()}. If there is no entry there, return a @code{NULL}
218 @deftypefun {HIST_ENTRY *} history_get (int offset)
219 Return the history entry at position @var{offset}, starting from
220 @code{history_base}. If there is no entry there, or if @var{offset}
221 is greater than the history length, return a @code{NULL} pointer.
224 @deftypefun int history_total_bytes ()
225 Return the number of bytes that the primary history entries are using.
226 This function returns the sum of the lengths of all the lines in the
230 @node Moving Around the History List
231 @subsection Moving Around the History List
233 These functions allow the current index into the history list to be
236 @deftypefun int history_set_pos (int pos)
237 Set the position in the history list to @var{pos}, an absolute index
241 @deftypefun {HIST_ENTRY *} previous_history ()
242 Back up the current history offset to the previous history entry, and
243 return a pointer to that entry. If there is no previous entry, return
244 a @code{NULL} pointer.
247 @deftypefun {HIST_ENTRY *} next_history ()
248 Move the current history offset forward to the next history entry, and
249 return the a pointer to that entry. If there is no next entry, return
250 a @code{NULL} pointer.
253 @node Searching the History List
254 @subsection Searching the History List
255 @cindex History Searching
257 These functions allow searching of the history list for entries containing
258 a specific string. Searching may be performed both forward and backward
259 from the current history position. The search may be @dfn{anchored},
260 meaning that the string must match at the beginning of the history entry.
261 @cindex anchored search
263 @deftypefun int history_search (char *string, int direction)
264 Search the history for @var{string}, starting at the current history
265 offset. If @var{direction} < 0, then the search is through previous entries,
266 else through subsequent. If @var{string} is found, then
267 the current history index is set to that history entry, and the value
268 returned is the offset in the line of the entry where
269 @var{string} was found. Otherwise, nothing is changed, and a -1 is
273 @deftypefun int history_search_prefix (char *string, int direction)
274 Search the history for @var{string}, starting at the current history
275 offset. The search is anchored: matching lines must begin with
276 @var{string}. If @var{direction} < 0, then the search is through previous
277 entries, else through subsequent. If @var{string} is found, then the
278 current history index is set to that entry, and the return value is 0.
279 Otherwise, nothing is changed, and a -1 is returned.
282 @deftypefun int history_search_pos (char *string, int direction, int pos)
283 Search for @var{string} in the history list, starting at @var{pos}, an
284 absolute index into the list. If @var{direction} is negative, the search
285 proceeds backward from @var{pos}, otherwise forward. Returns the absolute
286 index of the history element where @var{string} was found, or -1 otherwise.
289 @node Managing the History File
290 @subsection Managing the History File
292 The History library can read the history from and write it to a file.
293 This section documents the functions for managing a history file.
295 @deftypefun int read_history (char *filename)
296 Add the contents of @var{filename} to the history list, a line at a
297 time. If @var{filename} is @code{NULL}, then read from
298 @file{~/.history}. Returns 0 if successful, or errno if not.
301 @deftypefun int read_history_range (char *filename, int from, int to)
302 Read a range of lines from @var{filename}, adding them to the history list.
303 Start reading at line @var{from} and end at @var{to}. If
304 @var{from} is zero, start at the beginning. If @var{to} is less than
305 @var{from}, then read until the end of the file. If @var{filename} is
306 @code{NULL}, then read from @file{~/.history}. Returns 0 if successful,
307 or @code{errno} if not.
310 @deftypefun int write_history (char *filename)
311 Write the current history to @var{filename}, overwriting @var{filename}
312 if necessary. If @var{filename} is
313 @code{NULL}, then write the history list to @file{~/.history}. Values
314 returned are as in @code{read_history ()}.
317 @deftypefun int append_history (int nelements, char *filename)
318 Append the last @var{nelements} of the history list to @var{filename}.
321 @deftypefun int history_truncate_file (char *filename, int nlines)
322 Truncate the history file @var{filename}, leaving only the last
326 @node History Expansion
327 @subsection History Expansion
329 These functions implement @code{csh}-like history expansion.
331 @deftypefun int history_expand (char *string, char **output)
332 Expand @var{string}, placing the result into @var{output}, a pointer
333 to a string (@pxref{History Interaction}). Returns:
336 If no expansions took place (or, if the only change in
337 the text was the de-slashifying of the history expansion
340 if expansions did take place;
342 if there was an error in expansion;
344 if the returned line should be displayed, but not executed,
345 as with the @code{:p} modifier (@pxref{Modifiers}).
348 If an error ocurred in expansion, then @var{output} contains a descriptive
352 @deftypefun {char *} history_arg_extract (int first, int last, char *string)
353 Extract a string segment consisting of the @var{first} through @var{last}
354 arguments present in @var{string}. Arguments are broken up as in Bash.
357 @deftypefun {char *} get_history_event (char *string, int *cindex, int qchar)
358 Returns the text of the history event beginning at @var{string} +
359 @var{*cindex}. @var{*cindex} is modified to point to after the event
360 specifier. At function entry, @var{cindex} points to the index into
361 @var{string} where the history event specification begins. @var{qchar}
362 is a character that is allowed to end the event specification in addition
363 to the ``normal'' terminating characters.
366 @deftypefun {char **} history_tokenize (char *string)
367 Return an array of tokens parsed out of @var{string}, much as the
368 shell might. The tokens are split on white space and on the
369 characters @code{()<>;&|$}, and shell quoting conventions are
373 @node History Variables
374 @section History Variables
376 This section describes the externally visible variables exported by
377 the GNU History Library.
379 @deftypevar int history_base
380 The logical offset of the first entry in the history list.
383 @deftypevar int history_length
384 The number of entries currently stored in the history list.
387 @deftypevar int max_input_history
388 The maximum number of history entries. This must be changed using
389 @code{stifle_history ()}.
392 @deftypevar char history_expansion_char
393 The character that starts a history event. The default is @samp{!}.
396 @deftypevar char history_subst_char
397 The character that invokes word substitution if found at the start of
398 a line. The default is @samp{^}.
401 @deftypevar char history_comment_char
402 During tokenization, if this character is seen as the first character
403 of a word, then it and all subsequent characters up to a newline are
404 ignored, suppressing history expansion for the remainder of the line.
405 This is disabled by default.
408 @deftypevar {char *} history_no_expand_chars
409 The list of characters which inhibit history expansion if found immediately
410 following @var{history_expansion_char}. The default is whitespace and
414 @deftypevar {char *} history_search_delimiter_chars
415 The list of additional characters which can delimit a history search
416 string, in addition to whitespace, @samp{:} and @samp{?} in the case of
417 a substring search. The default is empty.
420 @deftypevar int history_quotes_inhibit_expansion
421 If non-zero, single-quoted words are not scanned for the history expansion
422 character. The default value is 0.
425 @deftypevar {Function *} history_inhibit_expansion_function
426 This should be set to the address of a function that takes two arguments:
427 a @code{char *} (@var{string}) and an integer index into that string (@var{i}).
428 It should return a non-zero value if the history expansion starting at
429 @var{string[i]} should not be performed; zero if the expansion should
431 It is intended for use by applications like Bash that use the history
432 expansion character for additional purposes.
433 By default, this variable is set to NULL.
436 @node History Programming Example
437 @section History Programming Example
439 The following program demonstrates simple use of the GNU History Library.
452 printf ("history$ ");
454 t = fgets (line, sizeof (line) - 1, stdin);
458 if (t[len - 1] == '\n')
463 strcpy (line, "quit");
470 result = history_expand (line, &expansion);
472 fprintf (stderr, "%s\n", expansion);
474 if (result < 0 || result == 2)
480 add_history (expansion);
481 strncpy (line, expansion, sizeof (line) - 1);
485 if (strcmp (line, "quit") == 0)
487 else if (strcmp (line, "save") == 0)
488 write_history ("history_file");
489 else if (strcmp (line, "read") == 0)
490 read_history ("history_file");
491 else if (strcmp (line, "list") == 0)
493 register HIST_ENTRY **the_list;
496 the_list = history_list ();
498 for (i = 0; the_list[i]; i++)
499 printf ("%d: %s\n", i + history_base, the_list[i]->line);
501 else if (strncmp (line, "delete", 6) == 0)
504 if ((sscanf (line + 6, "%d", &which)) == 1)
506 HIST_ENTRY *entry = remove_history (which);
508 fprintf (stderr, "No such entry %d\n", which);
517 fprintf (stderr, "non-numeric arg given to `delete'\n");