2 This file documents the user interface to the GNU History library.
4 Copyright (C) 1988-2001 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 @sc{gnu} History Library.
31 It should be considered a technical guide.
32 For information on the interactive use of @sc{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 @sc{gnu}
47 History library is able to keep track of those lines, associate arbitrary
48 data with each line, and utilize information from previous lines in
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 void *histdata_t;
85 typedef struct _hist_entry @{
91 The history list itself might therefore be declared as
94 HIST_ENTRY **the_history_list;
97 The state of the History library is encapsulated into a single structure:
101 * A structure used to pass around the current state of the history.
103 typedef struct _hist_state @{
104 HIST_ENTRY **entries; /* Pointer to the entries themselves. */
105 int offset; /* The location pointer within this array. */
106 int length; /* Number of elements within this array. */
107 int size; /* Number of slots allocated to this array. */
112 If the flags member includes @code{HS_STIFLED}, the history has been
115 @node History Functions
116 @section History Functions
118 This section describes the calling sequence for the various functions
119 exported by the @sc{gnu} History library.
122 * Initializing History and State Management:: Functions to call when you
123 want to use history in a
125 * History List Management:: Functions used to manage the list
127 * Information About the History List:: Functions returning information about
129 * Moving Around the History List:: Functions used to change the position
131 * Searching the History List:: Functions to search the history list
132 for entries containing a string.
133 * Managing the History File:: Functions that read and write a file
134 containing the history list.
135 * History Expansion:: Functions to perform csh-like history
139 @node Initializing History and State Management
140 @subsection Initializing History and State Management
142 This section describes functions used to initialize and manage
143 the state of the History library when you want to use the history
144 functions in your program.
146 @deftypefun void using_history (void)
147 Begin a session in which the history functions might be used. This
148 initializes the interactive variables.
151 @deftypefun {HISTORY_STATE *} history_get_history_state (void)
152 Return a structure describing the current state of the input history.
155 @deftypefun void history_set_history_state (HISTORY_STATE *state)
156 Set the state of the history list according to @var{state}.
159 @node History List Management
160 @subsection History List Management
162 These functions manage individual entries on the history list, or set
163 parameters managing the list itself.
165 @deftypefun void add_history (const char *string)
166 Place @var{string} at the end of the history list. The associated data
167 field (if any) is set to @code{NULL}.
170 @deftypefun {HIST_ENTRY *} remove_history (int which)
171 Remove history entry at offset @var{which} from the history. The
172 removed element is returned so you can free the line, data,
173 and containing structure.
176 @deftypefun {HIST_ENTRY *} replace_history_entry (int which, const char *line, histdata_t data)
177 Make the history entry at offset @var{which} have @var{line} and @var{data}.
178 This returns the old entry so you can dispose of the data. In the case
179 of an invalid @var{which}, a @code{NULL} pointer is returned.
182 @deftypefun void clear_history (void)
183 Clear the history list by deleting all the entries.
186 @deftypefun void stifle_history (int max)
187 Stifle the history list, remembering only the last @var{max} entries.
190 @deftypefun int unstifle_history (void)
191 Stop stifling the history. This returns the previous amount the
192 history was stifled. The value is positive if the history was
193 stifled, negative if it wasn't.
196 @deftypefun int history_is_stifled (void)
197 Returns non-zero if the history is stifled, zero if it is not.
200 @node Information About the History List
201 @subsection Information About the History List
203 These functions return information about the entire history list or
204 individual list entries.
206 @deftypefun {HIST_ENTRY **} history_list (void)
207 Return a @code{NULL} terminated array of @code{HIST_ENTRY *} which is the
208 current input history. Element 0 of this list is the beginning of time.
209 If there is no history, return @code{NULL}.
212 @deftypefun int where_history (void)
213 Returns the offset of the current history element.
216 @deftypefun {HIST_ENTRY *} current_history (void)
217 Return the history entry at the current position, as determined by
218 @code{where_history()}. If there is no entry there, return a @code{NULL}
222 @deftypefun {HIST_ENTRY *} history_get (int offset)
223 Return the history entry at position @var{offset}, starting from
224 @code{history_base} (@pxref{History Variables}).
225 If there is no entry there, or if @var{offset}
226 is greater than the history length, return a @code{NULL} pointer.
229 @deftypefun int history_total_bytes (void)
230 Return the number of bytes that the primary history entries are using.
231 This function returns the sum of the lengths of all the lines in the
235 @node Moving Around the History List
236 @subsection Moving Around the History List
238 These functions allow the current index into the history list to be
241 @deftypefun int history_set_pos (int pos)
242 Set the current history offset to @var{pos}, an absolute index
244 Returns 1 on success, 0 if @var{pos} is less than zero or greater
245 than the number of history entries.
248 @deftypefun {HIST_ENTRY *} previous_history (void)
249 Back up the current history offset to the previous history entry, and
250 return a pointer to that entry. If there is no previous entry, return
251 a @code{NULL} pointer.
254 @deftypefun {HIST_ENTRY *} next_history (void)
255 Move the current history offset forward to the next history entry, and
256 return the a pointer to that entry. If there is no next entry, return
257 a @code{NULL} pointer.
260 @node Searching the History List
261 @subsection Searching the History List
262 @cindex History Searching
264 These functions allow searching of the history list for entries containing
265 a specific string. Searching may be performed both forward and backward
266 from the current history position. The search may be @dfn{anchored},
267 meaning that the string must match at the beginning of the history entry.
268 @cindex anchored search
270 @deftypefun int history_search (const char *string, int direction)
271 Search the history for @var{string}, starting at the current history offset.
272 If @var{direction} is less than 0, then the search is through
273 previous entries, otherwise through subsequent entries.
274 If @var{string} is found, then
275 the current history index is set to that history entry, and the value
276 returned is the offset in the line of the entry where
277 @var{string} was found. Otherwise, nothing is changed, and a -1 is
281 @deftypefun int history_search_prefix (const char *string, int direction)
282 Search the history for @var{string}, starting at the current history
283 offset. The search is anchored: matching lines must begin with
284 @var{string}. If @var{direction} is less than 0, then the search is
285 through previous entries, otherwise through subsequent entries.
286 If @var{string} is found, then the
287 current history index is set to that entry, and the return value is 0.
288 Otherwise, nothing is changed, and a -1 is returned.
291 @deftypefun int history_search_pos (const char *string, int direction, int pos)
292 Search for @var{string} in the history list, starting at @var{pos}, an
293 absolute index into the list. If @var{direction} is negative, the search
294 proceeds backward from @var{pos}, otherwise forward. Returns the absolute
295 index of the history element where @var{string} was found, or -1 otherwise.
298 @node Managing the History File
299 @subsection Managing the History File
301 The History library can read the history from and write it to a file.
302 This section documents the functions for managing a history file.
304 @deftypefun int read_history (const char *filename)
305 Add the contents of @var{filename} to the history list, a line at a time.
306 If @var{filename} is @code{NULL}, then read from @file{~/.history}.
307 Returns 0 if successful, or @code{errno} if not.
310 @deftypefun int read_history_range (const char *filename, int from, int to)
311 Read a range of lines from @var{filename}, adding them to the history list.
312 Start reading at line @var{from} and end at @var{to}.
313 If @var{from} is zero, start at the beginning. If @var{to} is less than
314 @var{from}, then read until the end of the file. If @var{filename} is
315 @code{NULL}, then read from @file{~/.history}. Returns 0 if successful,
316 or @code{errno} if not.
319 @deftypefun int write_history (const char *filename)
320 Write the current history to @var{filename}, overwriting @var{filename}
322 If @var{filename} is @code{NULL}, then write the history list to
324 Returns 0 on success, or @code{errno} on a read or write error.
327 @deftypefun int append_history (int nelements, const char *filename)
328 Append the last @var{nelements} of the history list to @var{filename}.
329 If @var{filename} is @code{NULL}, then append to @file{~/.history}.
330 Returns 0 on success, or @code{errno} on a read or write error.
333 @deftypefun int history_truncate_file (const char *filename, int nlines)
334 Truncate the history file @var{filename}, leaving only the last
336 If @var{filename} is @code{NULL}, then @file{~/.history} is truncated.
337 Returns 0 on success, or @code{errno} on failure.
340 @node History Expansion
341 @subsection History Expansion
343 These functions implement history expansion.
345 @deftypefun int history_expand (char *string, char **output)
346 Expand @var{string}, placing the result into @var{output}, a pointer
347 to a string (@pxref{History Interaction}). Returns:
350 If no expansions took place (or, if the only change in
351 the text was the removal of escape characters preceding the history expansion
354 if expansions did take place;
356 if there was an error in expansion;
358 if the returned line should be displayed, but not executed,
359 as with the @code{:p} modifier (@pxref{Modifiers}).
362 If an error ocurred in expansion, then @var{output} contains a descriptive
366 @deftypefun {char *} get_history_event (const char *string, int *cindex, int qchar)
367 Returns the text of the history event beginning at @var{string} +
368 @var{*cindex}. @var{*cindex} is modified to point to after the event
369 specifier. At function entry, @var{cindex} points to the index into
370 @var{string} where the history event specification begins. @var{qchar}
371 is a character that is allowed to end the event specification in addition
372 to the ``normal'' terminating characters.
375 @deftypefun {char **} history_tokenize (const char *string)
376 Return an array of tokens parsed out of @var{string}, much as the
377 shell might. The tokens are split on the characters in the
378 @var{history_word_delimiters} variable,
379 and shell quoting conventions are obeyed.
382 @deftypefun {char *} history_arg_extract (int first, int last, const char *string)
383 Extract a string segment consisting of the @var{first} through @var{last}
384 arguments present in @var{string}. Arguments are split using
385 @code{history_tokenize}.
388 @node History Variables
389 @section History Variables
391 This section describes the externally-visible variables exported by
392 the @sc{gnu} History Library.
394 @deftypevar int history_base
395 The logical offset of the first entry in the history list.
398 @deftypevar int history_length
399 The number of entries currently stored in the history list.
402 @deftypevar int history_max_entries
403 The maximum number of history entries. This must be changed using
404 @code{stifle_history()}.
407 @deftypevar char history_expansion_char
408 The character that introduces a history event. The default is @samp{!}.
409 Setting this to 0 inhibits history expansion.
412 @deftypevar char history_subst_char
413 The character that invokes word substitution if found at the start of
414 a line. The default is @samp{^}.
417 @deftypevar char history_comment_char
418 During tokenization, if this character is seen as the first character
419 of a word, then it and all subsequent characters up to a newline are
420 ignored, suppressing history expansion for the remainder of the line.
421 This is disabled by default.
424 @deftypevar {char *} history_word_delimiters
425 The characters that separate tokens for @code{history_tokenize()}.
426 The default value is @code{" \t\n()<>;&|"}.
429 @deftypevar {char *} history_no_expand_chars
430 The list of characters which inhibit history expansion if found immediately
431 following @var{history_expansion_char}. The default is space, tab, newline,
432 carriage return, and @samp{=}.
435 @deftypevar {char *} history_search_delimiter_chars
436 The list of additional characters which can delimit a history search
437 string, in addition to space, TAB, @samp{:} and @samp{?} in the case of
438 a substring search. The default is empty.
441 @deftypevar int history_quotes_inhibit_expansion
442 If non-zero, single-quoted words are not scanned for the history expansion
443 character. The default value is 0.
446 @deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function
447 This should be set to the address of a function that takes two arguments:
448 a @code{char *} (@var{string})
449 and an @code{int} index into that string (@var{i}).
450 It should return a non-zero value if the history expansion starting at
451 @var{string[i]} should not be performed; zero if the expansion should
453 It is intended for use by applications like Bash that use the history
454 expansion character for additional purposes.
455 By default, this variable is set to @code{NULL}.
458 @node History Programming Example
459 @section History Programming Example
461 The following program demonstrates simple use of the @sc{gnu} History Library.
465 #include <readline/history.h>
479 printf ("history$ ");
481 t = fgets (line, sizeof (line) - 1, stdin);
485 if (t[len - 1] == '\n')
490 strcpy (line, "quit");
497 result = history_expand (line, &expansion);
499 fprintf (stderr, "%s\n", expansion);
501 if (result < 0 || result == 2)
507 add_history (expansion);
508 strncpy (line, expansion, sizeof (line) - 1);
512 if (strcmp (line, "quit") == 0)
514 else if (strcmp (line, "save") == 0)
515 write_history ("history_file");
516 else if (strcmp (line, "read") == 0)
517 read_history ("history_file");
518 else if (strcmp (line, "list") == 0)
520 register HIST_ENTRY **the_list;
523 the_list = history_list ();
525 for (i = 0; the_list[i]; i++)
526 printf ("%d: %s\n", i + history_base, the_list[i]->line);
528 else if (strncmp (line, "delete", 6) == 0)
531 if ((sscanf (line + 6, "%d", &which)) == 1)
533 HIST_ENTRY *entry = remove_history (which);
535 fprintf (stderr, "No such entry %d\n", which);
544 fprintf (stderr, "non-numeric arg given to `delete'\n");