1@ignore 2This file documents the user interface to the GNU History library. 3 4Copyright (C) 1988-2006 Free Software Foundation, Inc. 5Authored by Brian Fox and Chet Ramey. 6 7Permission is granted to make and distribute verbatim copies of this manual 8provided the copyright notice and this permission notice are preserved on 9all copies. 10 11Permission is granted to process this file through Tex and print the 12results, provided the printed document carries copying permission notice 13identical to this one except for the removal of this paragraph (this 14paragraph not being relevant to the printed manual). 15 16Permission is granted to copy and distribute modified versions of this 17manual under the conditions for verbatim copying, provided also that the 18GNU Copyright statement is available to the distributee, and provided that 19the entire resulting derived work is distributed under the terms of a 20permission notice identical to this one. 21 22Permission is granted to copy and distribute translations of this manual 23into another language, under the above conditions for modified versions. 24@end ignore 25 26@node Programming with GNU History 27@chapter Programming with GNU History 28 29This chapter describes how to interface programs that you write 30with the @sc{gnu} History Library. 31It should be considered a technical guide. 32For information on the interactive use of @sc{gnu} History, @pxref{Using 33History Interactively}. 34 35@menu 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. 41@end menu 42 43@node Introduction to History 44@section Introduction to History 45 46Many programs read input from the user a line at a time. The @sc{gnu} 47History library is able to keep track of those lines, associate arbitrary 48data with each line, and utilize information from previous lines in 49composing new ones. 50 51The programmer using the History library has available functions 52for remembering lines on a history list, associating arbitrary data 53with a line, removing lines from the list, searching through the list 54for a line containing an arbitrary text string, and referencing any line 55in the list directly. In addition, a history @dfn{expansion} function 56is available which provides for a consistent user interface across 57different programs. 58 59The user using programs written with the History library has the 60benefit of a consistent user interface with a set of well-known 61commands for manipulating the text of previous lines and using that text 62in new commands. The basic history manipulation commands are similar to 63the history substitution provided by @code{csh}. 64 65If the programmer desires, he can use the Readline library, which 66includes some history manipulation by default, and has the added 67advantage of command line editing. 68 69Before declaring any functions using any functionality the History 70library provides in other code, an application writer should include 71the file @code{<readline/history.h>} in any file that uses the 72History library's features. It supplies extern declarations for all 73of the library's public functions and variables, and declares all of 74the public data structures. 75 76@node History Storage 77@section History Storage 78 79The history list is an array of history entries. A history entry is 80declared as follows: 81 82@example 83typedef void *histdata_t; 84 85typedef struct _hist_entry @{ 86 char *line; 87 char *timestamp; 88 histdata_t data; 89@} HIST_ENTRY; 90@end example 91 92The history list itself might therefore be declared as 93 94@example 95HIST_ENTRY **the_history_list; 96@end example 97 98The state of the History library is encapsulated into a single structure: 99 100@example 101/* 102 * A structure used to pass around the current state of the history. 103 */ 104typedef struct _hist_state @{ 105 HIST_ENTRY **entries; /* Pointer to the entries themselves. */ 106 int offset; /* The location pointer within this array. */ 107 int length; /* Number of elements within this array. */ 108 int size; /* Number of slots allocated to this array. */ 109 int flags; 110@} HISTORY_STATE; 111@end example 112 113If the flags member includes @code{HS_STIFLED}, the history has been 114stifled. 115 116@node History Functions 117@section History Functions 118 119This section describes the calling sequence for the various functions 120exported by the @sc{gnu} History library. 121 122@menu 123* Initializing History and State Management:: Functions to call when you 124 want to use history in a 125 program. 126* History List Management:: Functions used to manage the list 127 of history entries. 128* Information About the History List:: Functions returning information about 129 the history list. 130* Moving Around the History List:: Functions used to change the position 131 in the history list. 132* Searching the History List:: Functions to search the history list 133 for entries containing a string. 134* Managing the History File:: Functions that read and write a file 135 containing the history list. 136* History Expansion:: Functions to perform csh-like history 137 expansion. 138@end menu 139 140@node Initializing History and State Management 141@subsection Initializing History and State Management 142 143This section describes functions used to initialize and manage 144the state of the History library when you want to use the history 145functions in your program. 146 147@deftypefun void using_history (void) 148Begin a session in which the history functions might be used. This 149initializes the interactive variables. 150@end deftypefun 151 152@deftypefun {HISTORY_STATE *} history_get_history_state (void) 153Return a structure describing the current state of the input history. 154@end deftypefun 155 156@deftypefun void history_set_history_state (HISTORY_STATE *state) 157Set the state of the history list according to @var{state}. 158@end deftypefun 159 160@node History List Management 161@subsection History List Management 162 163These functions manage individual entries on the history list, or set 164parameters managing the list itself. 165 166@deftypefun void add_history (const char *string) 167Place @var{string} at the end of the history list. The associated data 168field (if any) is set to @code{NULL}. 169@end deftypefun 170 171@deftypefun void add_history_time (const char *string) 172Change the time stamp associated with the most recent history entry to 173@var{string}. 174@end deftypefun 175 176@deftypefun {HIST_ENTRY *} remove_history (int which) 177Remove history entry at offset @var{which} from the history. The 178removed element is returned so you can free the line, data, 179and containing structure. 180@end deftypefun 181 182@deftypefun {histdata_t} free_history_entry (HIST_ENTRY *histent) 183Free the history entry @var{histent} and any history library private 184data associated with it. Returns the application-specific data 185so the caller can dispose of it. 186@end deftypefun 187 188@deftypefun {HIST_ENTRY *} replace_history_entry (int which, const char *line, histdata_t data) 189Make the history entry at offset @var{which} have @var{line} and @var{data}. 190This returns the old entry so the caller can dispose of any 191application-specific data. In the case 192of an invalid @var{which}, a @code{NULL} pointer is returned. 193@end deftypefun 194 195@deftypefun void clear_history (void) 196Clear the history list by deleting all the entries. 197@end deftypefun 198 199@deftypefun void stifle_history (int max) 200Stifle the history list, remembering only the last @var{max} entries. 201@end deftypefun 202 203@deftypefun int unstifle_history (void) 204Stop stifling the history. This returns the previously-set 205maximum number of history entries (as set by @code{stifle_history()}). 206The value is positive if the history was 207stifled, negative if it wasn't. 208@end deftypefun 209 210@deftypefun int history_is_stifled (void) 211Returns non-zero if the history is stifled, zero if it is not. 212@end deftypefun 213 214@node Information About the History List 215@subsection Information About the History List 216 217These functions return information about the entire history list or 218individual list entries. 219 220@deftypefun {HIST_ENTRY **} history_list (void) 221Return a @code{NULL} terminated array of @code{HIST_ENTRY *} which is the 222current input history. Element 0 of this list is the beginning of time. 223If there is no history, return @code{NULL}. 224@end deftypefun 225 226@deftypefun int where_history (void) 227Returns the offset of the current history element. 228@end deftypefun 229 230@deftypefun {HIST_ENTRY *} current_history (void) 231Return the history entry at the current position, as determined by 232@code{where_history()}. If there is no entry there, return a @code{NULL} 233pointer. 234@end deftypefun 235 236@deftypefun {HIST_ENTRY *} history_get (int offset) 237Return the history entry at position @var{offset}, starting from 238@code{history_base} (@pxref{History Variables}). 239If there is no entry there, or if @var{offset} 240is greater than the history length, return a @code{NULL} pointer. 241@end deftypefun 242 243@deftypefun time_t history_get_time (HIST_ENTRY *entry) 244Return the time stamp associated with the history entry @var{entry}. 245@end deftypefun 246 247@deftypefun int history_total_bytes (void) 248Return the number of bytes that the primary history entries are using. 249This function returns the sum of the lengths of all the lines in the 250history. 251@end deftypefun 252 253@node Moving Around the History List 254@subsection Moving Around the History List 255 256These functions allow the current index into the history list to be 257set or changed. 258 259@deftypefun int history_set_pos (int pos) 260Set the current history offset to @var{pos}, an absolute index 261into the list. 262Returns 1 on success, 0 if @var{pos} is less than zero or greater 263than the number of history entries. 264@end deftypefun 265 266@deftypefun {HIST_ENTRY *} previous_history (void) 267Back up the current history offset to the previous history entry, and 268return a pointer to that entry. If there is no previous entry, return 269a @code{NULL} pointer. 270@end deftypefun 271 272@deftypefun {HIST_ENTRY *} next_history (void) 273Move the current history offset forward to the next history entry, and 274return the a pointer to that entry. If there is no next entry, return 275a @code{NULL} pointer. 276@end deftypefun 277 278@node Searching the History List 279@subsection Searching the History List 280@cindex History Searching 281 282These functions allow searching of the history list for entries containing 283a specific string. Searching may be performed both forward and backward 284from the current history position. The search may be @dfn{anchored}, 285meaning that the string must match at the beginning of the history entry. 286@cindex anchored search 287 288@deftypefun int history_search (const char *string, int direction) 289Search the history for @var{string}, starting at the current history offset. 290If @var{direction} is less than 0, then the search is through 291previous entries, otherwise through subsequent entries. 292If @var{string} is found, then 293the current history index is set to that history entry, and the value 294returned is the offset in the line of the entry where 295@var{string} was found. Otherwise, nothing is changed, and a -1 is 296returned. 297@end deftypefun 298 299@deftypefun int history_search_prefix (const char *string, int direction) 300Search the history for @var{string}, starting at the current history 301offset. The search is anchored: matching lines must begin with 302@var{string}. If @var{direction} is less than 0, then the search is 303through previous entries, otherwise through subsequent entries. 304If @var{string} is found, then the 305current history index is set to that entry, and the return value is 0. 306Otherwise, nothing is changed, and a -1 is returned. 307@end deftypefun 308 309@deftypefun int history_search_pos (const char *string, int direction, int pos) 310Search for @var{string} in the history list, starting at @var{pos}, an 311absolute index into the list. If @var{direction} is negative, the search 312proceeds backward from @var{pos}, otherwise forward. Returns the absolute 313index of the history element where @var{string} was found, or -1 otherwise. 314@end deftypefun 315 316@node Managing the History File 317@subsection Managing the History File 318 319The History library can read the history from and write it to a file. 320This section documents the functions for managing a history file. 321 322@deftypefun int read_history (const char *filename) 323Add the contents of @var{filename} to the history list, a line at a time. 324If @var{filename} is @code{NULL}, then read from @file{~/.history}. 325Returns 0 if successful, or @code{errno} if not. 326@end deftypefun 327 328@deftypefun int read_history_range (const char *filename, int from, int to) 329Read a range of lines from @var{filename}, adding them to the history list. 330Start reading at line @var{from} and end at @var{to}. 331If @var{from} is zero, start at the beginning. If @var{to} is less than 332@var{from}, then read until the end of the file. If @var{filename} is 333@code{NULL}, then read from @file{~/.history}. Returns 0 if successful, 334or @code{errno} if not. 335@end deftypefun 336 337@deftypefun int write_history (const char *filename) 338Write the current history to @var{filename}, overwriting @var{filename} 339if necessary. 340If @var{filename} is @code{NULL}, then write the history list to 341@file{~/.history}. 342Returns 0 on success, or @code{errno} on a read or write error. 343@end deftypefun 344 345@deftypefun int append_history (int nelements, const char *filename) 346Append the last @var{nelements} of the history list to @var{filename}. 347If @var{filename} is @code{NULL}, then append to @file{~/.history}. 348Returns 0 on success, or @code{errno} on a read or write error. 349@end deftypefun 350 351@deftypefun int history_truncate_file (const char *filename, int nlines) 352Truncate the history file @var{filename}, leaving only the last 353@var{nlines} lines. 354If @var{filename} is @code{NULL}, then @file{~/.history} is truncated. 355Returns 0 on success, or @code{errno} on failure. 356@end deftypefun 357 358@node History Expansion 359@subsection History Expansion 360 361These functions implement history expansion. 362 363@deftypefun int history_expand (char *string, char **output) 364Expand @var{string}, placing the result into @var{output}, a pointer 365to a string (@pxref{History Interaction}). Returns: 366@table @code 367@item 0 368If no expansions took place (or, if the only change in 369the text was the removal of escape characters preceding the history expansion 370character); 371@item 1 372if expansions did take place; 373@item -1 374if there was an error in expansion; 375@item 2 376if the returned line should be displayed, but not executed, 377as with the @code{:p} modifier (@pxref{Modifiers}). 378@end table 379 380If an error ocurred in expansion, then @var{output} contains a descriptive 381error message. 382@end deftypefun 383 384@deftypefun {char *} get_history_event (const char *string, int *cindex, int qchar) 385Returns the text of the history event beginning at @var{string} + 386@var{*cindex}. @var{*cindex} is modified to point to after the event 387specifier. At function entry, @var{cindex} points to the index into 388@var{string} where the history event specification begins. @var{qchar} 389is a character that is allowed to end the event specification in addition 390to the ``normal'' terminating characters. 391@end deftypefun 392 393@deftypefun {char **} history_tokenize (const char *string) 394Return an array of tokens parsed out of @var{string}, much as the 395shell might. The tokens are split on the characters in the 396@var{history_word_delimiters} variable, 397and shell quoting conventions are obeyed. 398@end deftypefun 399 400@deftypefun {char *} history_arg_extract (int first, int last, const char *string) 401Extract a string segment consisting of the @var{first} through @var{last} 402arguments present in @var{string}. Arguments are split using 403@code{history_tokenize}. 404@end deftypefun 405 406@node History Variables 407@section History Variables 408 409This section describes the externally-visible variables exported by 410the @sc{gnu} History Library. 411 412@deftypevar int history_base 413The logical offset of the first entry in the history list. 414@end deftypevar 415 416@deftypevar int history_length 417The number of entries currently stored in the history list. 418@end deftypevar 419 420@deftypevar int history_max_entries 421The maximum number of history entries. This must be changed using 422@code{stifle_history()}. 423@end deftypevar 424 425@deftypevar int history_write_timestamps 426If non-zero, timestamps are written to the history file, so they can be 427preserved between sessions. The default value is 0, meaning that 428timestamps are not saved. 429@end deftypevar 430 431@deftypevar char history_expansion_char 432The character that introduces a history event. The default is @samp{!}. 433Setting this to 0 inhibits history expansion. 434@end deftypevar 435 436@deftypevar char history_subst_char 437The character that invokes word substitution if found at the start of 438a line. The default is @samp{^}. 439@end deftypevar 440 441@deftypevar char history_comment_char 442During tokenization, if this character is seen as the first character 443of a word, then it and all subsequent characters up to a newline are 444ignored, suppressing history expansion for the remainder of the line. 445This is disabled by default. 446@end deftypevar 447 448@deftypevar {char *} history_word_delimiters 449The characters that separate tokens for @code{history_tokenize()}. 450The default value is @code{" \t\n()<>;&|"}. 451@end deftypevar 452 453@deftypevar {char *} history_search_delimiter_chars 454The list of additional characters which can delimit a history search 455string, in addition to space, TAB, @samp{:} and @samp{?} in the case of 456a substring search. The default is empty. 457@end deftypevar 458 459@deftypevar {char *} history_no_expand_chars 460The list of characters which inhibit history expansion if found immediately 461following @var{history_expansion_char}. The default is space, tab, newline, 462carriage return, and @samp{=}. 463@end deftypevar 464 465@deftypevar int history_quotes_inhibit_expansion 466If non-zero, single-quoted words are not scanned for the history expansion 467character. The default value is 0. 468@end deftypevar 469 470@deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function 471This should be set to the address of a function that takes two arguments: 472a @code{char *} (@var{string}) 473and an @code{int} index into that string (@var{i}). 474It should return a non-zero value if the history expansion starting at 475@var{string[i]} should not be performed; zero if the expansion should 476be done. 477It is intended for use by applications like Bash that use the history 478expansion character for additional purposes. 479By default, this variable is set to @code{NULL}. 480@end deftypevar 481 482@node History Programming Example 483@section History Programming Example 484 485The following program demonstrates simple use of the @sc{gnu} History Library. 486 487@smallexample 488#include <stdio.h> 489#include <readline/history.h> 490 491main (argc, argv) 492 int argc; 493 char **argv; 494@{ 495 char line[1024], *t; 496 int len, done = 0; 497 498 line[0] = 0; 499 500 using_history (); 501 while (!done) 502 @{ 503 printf ("history$ "); 504 fflush (stdout); 505 t = fgets (line, sizeof (line) - 1, stdin); 506 if (t && *t) 507 @{ 508 len = strlen (t); 509 if (t[len - 1] == '\n') 510 t[len - 1] = '\0'; 511 @} 512 513 if (!t) 514 strcpy (line, "quit"); 515 516 if (line[0]) 517 @{ 518 char *expansion; 519 int result; 520 521 result = history_expand (line, &expansion); 522 if (result) 523 fprintf (stderr, "%s\n", expansion); 524 525 if (result < 0 || result == 2) 526 @{ 527 free (expansion); 528 continue; 529 @} 530 531 add_history (expansion); 532 strncpy (line, expansion, sizeof (line) - 1); 533 free (expansion); 534 @} 535 536 if (strcmp (line, "quit") == 0) 537 done = 1; 538 else if (strcmp (line, "save") == 0) 539 write_history ("history_file"); 540 else if (strcmp (line, "read") == 0) 541 read_history ("history_file"); 542 else if (strcmp (line, "list") == 0) 543 @{ 544 register HIST_ENTRY **the_list; 545 register int i; 546 547 the_list = history_list (); 548 if (the_list) 549 for (i = 0; the_list[i]; i++) 550 printf ("%d: %s\n", i + history_base, the_list[i]->line); 551 @} 552 else if (strncmp (line, "delete", 6) == 0) 553 @{ 554 int which; 555 if ((sscanf (line + 6, "%d", &which)) == 1) 556 @{ 557 HIST_ENTRY *entry = remove_history (which); 558 if (!entry) 559 fprintf (stderr, "No such entry %d\n", which); 560 else 561 @{ 562 free (entry->line); 563 free (entry); 564 @} 565 @} 566 else 567 @{ 568 fprintf (stderr, "non-numeric arg given to `delete'\n"); 569 @} 570 @} 571 @} 572@} 573@end smallexample 574