1214501Srpaulo@ignore 2214501SrpauloThis file documents the user interface to the GNU History library. 3214501Srpaulo 4214501SrpauloCopyright (C) 1988-2002 Free Software Foundation, Inc. 5214501SrpauloAuthored by Brian Fox and Chet Ramey. 6214501Srpaulo 7214501SrpauloPermission is granted to make and distribute verbatim copies of this manual 8214501Srpauloprovided the copyright notice and this permission notice are preserved on 9214501Srpauloall copies. 10214501Srpaulo 11214501SrpauloPermission is granted to process this file through Tex and print the 12214501Srpauloresults, provided the printed document carries copying permission notice 13214501Srpauloidentical to this one except for the removal of this paragraph (this 14214501Srpauloparagraph not being relevant to the printed manual). 15214501Srpaulo 16214501SrpauloPermission is granted to copy and distribute modified versions of this 17214501Srpaulomanual under the conditions for verbatim copying, provided also that the 18214501SrpauloGNU Copyright statement is available to the distributee, and provided that 19214501Srpaulothe entire resulting derived work is distributed under the terms of a 20214501Srpaulopermission notice identical to this one. 21214501Srpaulo 22214501SrpauloPermission is granted to copy and distribute translations of this manual 23214501Srpaulointo another language, under the above conditions for modified versions. 24214501Srpaulo@end ignore 25214501Srpaulo 26214501Srpaulo@node Programming with GNU History 27214501Srpaulo@chapter Programming with GNU History 28214501Srpaulo 29214501SrpauloThis chapter describes how to interface programs that you write 30214501Srpaulowith the @sc{gnu} History Library. 31214501SrpauloIt should be considered a technical guide. 32214501SrpauloFor information on the interactive use of @sc{gnu} History, @pxref{Using 33214501SrpauloHistory Interactively}. 34214501Srpaulo 35214501Srpaulo@menu 36214501Srpaulo* Introduction to History:: What is the GNU History library for? 37214501Srpaulo* History Storage:: How information is stored. 38214501Srpaulo* History Functions:: Functions that you can use. 39214501Srpaulo* History Variables:: Variables that control behaviour. 40214501Srpaulo* History Programming Example:: Example of using the GNU History Library. 41214501Srpaulo@end menu 42214501Srpaulo 43214501Srpaulo@node Introduction to History 44214501Srpaulo@section Introduction to History 45214501Srpaulo 46214501SrpauloMany programs read input from the user a line at a time. The @sc{gnu} 47214501SrpauloHistory library is able to keep track of those lines, associate arbitrary 48214501Srpaulodata with each line, and utilize information from previous lines in 49214501Srpaulocomposing new ones. 50214501Srpaulo 51214501SrpauloThe programmer using the History library has available functions 52214501Srpaulofor remembering lines on a history list, associating arbitrary data 53214501Srpaulowith a line, removing lines from the list, searching through the list 54214501Srpaulofor a line containing an arbitrary text string, and referencing any line 55214501Srpauloin the list directly. In addition, a history @dfn{expansion} function 56214501Srpaulois available which provides for a consistent user interface across 57214501Srpaulodifferent programs. 58214501Srpaulo 59214501SrpauloThe user using programs written with the History library has the 60214501Srpaulobenefit of a consistent user interface with a set of well-known 61214501Srpaulocommands for manipulating the text of previous lines and using that text 62214501Srpauloin new commands. The basic history manipulation commands are similar to 63214501Srpaulothe history substitution provided by @code{csh}. 64214501Srpaulo 65214501SrpauloIf the programmer desires, he can use the Readline library, which 66214501Srpauloincludes some history manipulation by default, and has the added 67214501Srpauloadvantage of command line editing. 68214501Srpaulo 69214501SrpauloBefore declaring any functions using any functionality the History 70214501Srpaulolibrary provides in other code, an application writer should include 71214501Srpaulothe file @code{<readline/history.h>} in any file that uses the 72214501SrpauloHistory library's features. It supplies extern declarations for all 73214501Srpauloof the library's public functions and variables, and declares all of 74214501Srpaulothe public data structures. 75214501Srpaulo 76214501Srpaulo@node History Storage 77214501Srpaulo@section History Storage 78214501Srpaulo 79214501SrpauloThe history list is an array of history entries. A history entry is 80214501Srpaulodeclared as follows: 81214501Srpaulo 82214501Srpaulo@example 83214501Srpaulotypedef void *histdata_t; 84214501Srpaulo 85214501Srpaulotypedef struct _hist_entry @{ 86214501Srpaulo char *line; 87214501Srpaulo histdata_t data; 88214501Srpaulo@} HIST_ENTRY; 89214501Srpaulo@end example 90214501Srpaulo 91214501SrpauloThe history list itself might therefore be declared as 92214501Srpaulo 93214501Srpaulo@example 94214501SrpauloHIST_ENTRY **the_history_list; 95214501Srpaulo@end example 96214501Srpaulo 97214501SrpauloThe state of the History library is encapsulated into a single structure: 98214501Srpaulo 99214501Srpaulo@example 100214501Srpaulo/* 101214501Srpaulo * A structure used to pass around the current state of the history. 102214501Srpaulo */ 103214501Srpaulotypedef struct _hist_state @{ 104214501Srpaulo HIST_ENTRY **entries; /* Pointer to the entries themselves. */ 105214501Srpaulo int offset; /* The location pointer within this array. */ 106214501Srpaulo int length; /* Number of elements within this array. */ 107214501Srpaulo int size; /* Number of slots allocated to this array. */ 108214501Srpaulo int flags; 109214501Srpaulo@} HISTORY_STATE; 110214501Srpaulo@end example 111214501Srpaulo 112214501SrpauloIf the flags member includes @code{HS_STIFLED}, the history has been 113214501Srpaulostifled. 114214501Srpaulo 115214501Srpaulo@node History Functions 116214501Srpaulo@section History Functions 117214501Srpaulo 118214501SrpauloThis section describes the calling sequence for the various functions 119214501Srpauloexported by the @sc{gnu} History library. 120214501Srpaulo 121214501Srpaulo@menu 122214501Srpaulo* Initializing History and State Management:: Functions to call when you 123214501Srpaulo want to use history in a 124214501Srpaulo program. 125214501Srpaulo* History List Management:: Functions used to manage the list 126214501Srpaulo of history entries. 127214501Srpaulo* Information About the History List:: Functions returning information about 128214501Srpaulo the history list. 129214501Srpaulo* Moving Around the History List:: Functions used to change the position 130214501Srpaulo in the history list. 131214501Srpaulo* Searching the History List:: Functions to search the history list 132214501Srpaulo for entries containing a string. 133214501Srpaulo* Managing the History File:: Functions that read and write a file 134214501Srpaulo containing the history list. 135214501Srpaulo* History Expansion:: Functions to perform csh-like history 136214501Srpaulo expansion. 137214501Srpaulo@end menu 138214501Srpaulo 139214501Srpaulo@node Initializing History and State Management 140214501Srpaulo@subsection Initializing History and State Management 141214501Srpaulo 142214501SrpauloThis section describes functions used to initialize and manage 143214501Srpaulothe state of the History library when you want to use the history 144214501Srpaulofunctions in your program. 145214501Srpaulo 146214501Srpaulo@deftypefun void using_history (void) 147214501SrpauloBegin a session in which the history functions might be used. This 148214501Srpauloinitializes the interactive variables. 149214501Srpaulo@end deftypefun 150214501Srpaulo 151214501Srpaulo@deftypefun {HISTORY_STATE *} history_get_history_state (void) 152214501SrpauloReturn a structure describing the current state of the input history. 153214501Srpaulo@end deftypefun 154214501Srpaulo 155214501Srpaulo@deftypefun void history_set_history_state (HISTORY_STATE *state) 156214501SrpauloSet the state of the history list according to @var{state}. 157214501Srpaulo@end deftypefun 158214501Srpaulo 159214501Srpaulo@node History List Management 160214501Srpaulo@subsection History List Management 161214501Srpaulo 162214501SrpauloThese functions manage individual entries on the history list, or set 163214501Srpauloparameters managing the list itself. 164214501Srpaulo 165214501Srpaulo@deftypefun void add_history (const char *string) 166214501SrpauloPlace @var{string} at the end of the history list. The associated data 167214501Srpaulofield (if any) is set to @code{NULL}. 168214501Srpaulo@end deftypefun 169214501Srpaulo 170214501Srpaulo@deftypefun {HIST_ENTRY *} remove_history (int which) 171214501SrpauloRemove history entry at offset @var{which} from the history. The 172214501Srpauloremoved element is returned so you can free the line, data, 173214501Srpauloand containing structure. 174214501Srpaulo@end deftypefun 175214501Srpaulo 176214501Srpaulo@deftypefun {HIST_ENTRY *} replace_history_entry (int which, const char *line, histdata_t data) 177214501SrpauloMake the history entry at offset @var{which} have @var{line} and @var{data}. 178214501SrpauloThis returns the old entry so you can dispose of the data. In the case 179214501Srpauloof an invalid @var{which}, a @code{NULL} pointer is returned. 180214501Srpaulo@end deftypefun 181214501Srpaulo 182214501Srpaulo@deftypefun void clear_history (void) 183214501SrpauloClear the history list by deleting all the entries. 184214501Srpaulo@end deftypefun 185214501Srpaulo 186214501Srpaulo@deftypefun void stifle_history (int max) 187214501SrpauloStifle the history list, remembering only the last @var{max} entries. 188214501Srpaulo@end deftypefun 189214501Srpaulo 190214501Srpaulo@deftypefun int unstifle_history (void) 191214501SrpauloStop stifling the history. This returns the previously-set 192214501Srpaulomaximum number of history entries (as set by @code{stifle_history()}). 193214501SrpauloThe value is positive if the history was 194214501Srpaulostifled, negative if it wasn't. 195214501Srpaulo@end deftypefun 196214501Srpaulo 197214501Srpaulo@deftypefun int history_is_stifled (void) 198214501SrpauloReturns non-zero if the history is stifled, zero if it is not. 199214501Srpaulo@end deftypefun 200214501Srpaulo 201214501Srpaulo@node Information About the History List 202214501Srpaulo@subsection Information About the History List 203214501Srpaulo 204214501SrpauloThese functions return information about the entire history list or 205214501Srpauloindividual list entries. 206214501Srpaulo 207214501Srpaulo@deftypefun {HIST_ENTRY **} history_list (void) 208214501SrpauloReturn a @code{NULL} terminated array of @code{HIST_ENTRY *} which is the 209214501Srpaulocurrent input history. Element 0 of this list is the beginning of time. 210214501SrpauloIf there is no history, return @code{NULL}. 211214501Srpaulo@end deftypefun 212214501Srpaulo 213214501Srpaulo@deftypefun int where_history (void) 214214501SrpauloReturns the offset of the current history element. 215214501Srpaulo@end deftypefun 216214501Srpaulo 217214501Srpaulo@deftypefun {HIST_ENTRY *} current_history (void) 218214501SrpauloReturn the history entry at the current position, as determined by 219214501Srpaulo@code{where_history()}. If there is no entry there, return a @code{NULL} 220214501Srpaulopointer. 221214501Srpaulo@end deftypefun 222214501Srpaulo 223214501Srpaulo@deftypefun {HIST_ENTRY *} history_get (int offset) 224214501SrpauloReturn the history entry at position @var{offset}, starting from 225214501Srpaulo@code{history_base} (@pxref{History Variables}). 226214501SrpauloIf there is no entry there, or if @var{offset} 227214501Srpaulois greater than the history length, return a @code{NULL} pointer. 228214501Srpaulo@end deftypefun 229214501Srpaulo 230214501Srpaulo@deftypefun int history_total_bytes (void) 231214501SrpauloReturn the number of bytes that the primary history entries are using. 232214501SrpauloThis function returns the sum of the lengths of all the lines in the 233214501Srpaulohistory. 234214501Srpaulo@end deftypefun 235214501Srpaulo 236214501Srpaulo@node Moving Around the History List 237214501Srpaulo@subsection Moving Around the History List 238214501Srpaulo 239214501SrpauloThese functions allow the current index into the history list to be 240214501Srpauloset or changed. 241214501Srpaulo 242214501Srpaulo@deftypefun int history_set_pos (int pos) 243214501SrpauloSet the current history offset to @var{pos}, an absolute index 244214501Srpaulointo the list. 245214501SrpauloReturns 1 on success, 0 if @var{pos} is less than zero or greater 246214501Srpaulothan the number of history entries. 247214501Srpaulo@end deftypefun 248214501Srpaulo 249214501Srpaulo@deftypefun {HIST_ENTRY *} previous_history (void) 250214501SrpauloBack up the current history offset to the previous history entry, and 251214501Srpauloreturn a pointer to that entry. If there is no previous entry, return 252214501Srpauloa @code{NULL} pointer. 253214501Srpaulo@end deftypefun 254214501Srpaulo 255214501Srpaulo@deftypefun {HIST_ENTRY *} next_history (void) 256214501SrpauloMove the current history offset forward to the next history entry, and 257214501Srpauloreturn the a pointer to that entry. If there is no next entry, return 258214501Srpauloa @code{NULL} pointer. 259214501Srpaulo@end deftypefun 260214501Srpaulo 261214501Srpaulo@node Searching the History List 262214501Srpaulo@subsection Searching the History List 263214501Srpaulo@cindex History Searching 264214501Srpaulo 265214501SrpauloThese functions allow searching of the history list for entries containing 266214501Srpauloa specific string. Searching may be performed both forward and backward 267214501Srpaulofrom the current history position. The search may be @dfn{anchored}, 268214501Srpaulomeaning that the string must match at the beginning of the history entry. 269214501Srpaulo@cindex anchored search 270214501Srpaulo 271214501Srpaulo@deftypefun int history_search (const char *string, int direction) 272214501SrpauloSearch the history for @var{string}, starting at the current history offset. 273214501SrpauloIf @var{direction} is less than 0, then the search is through 274214501Srpauloprevious entries, otherwise through subsequent entries. 275214501SrpauloIf @var{string} is found, then 276214501Srpaulothe current history index is set to that history entry, and the value 277214501Srpauloreturned is the offset in the line of the entry where 278214501Srpaulo@var{string} was found. Otherwise, nothing is changed, and a -1 is 279214501Srpauloreturned. 280214501Srpaulo@end deftypefun 281214501Srpaulo 282214501Srpaulo@deftypefun int history_search_prefix (const char *string, int direction) 283214501SrpauloSearch the history for @var{string}, starting at the current history 284214501Srpaulooffset. The search is anchored: matching lines must begin with 285214501Srpaulo@var{string}. If @var{direction} is less than 0, then the search is 286214501Srpaulothrough previous entries, otherwise through subsequent entries. 287214501SrpauloIf @var{string} is found, then the 288214501Srpaulocurrent history index is set to that entry, and the return value is 0. 289214501SrpauloOtherwise, nothing is changed, and a -1 is returned. 290214501Srpaulo@end deftypefun 291214501Srpaulo 292214501Srpaulo@deftypefun int history_search_pos (const char *string, int direction, int pos) 293214501SrpauloSearch for @var{string} in the history list, starting at @var{pos}, an 294214501Srpauloabsolute index into the list. If @var{direction} is negative, the search 295214501Srpauloproceeds backward from @var{pos}, otherwise forward. Returns the absolute 296214501Srpauloindex of the history element where @var{string} was found, or -1 otherwise. 297214501Srpaulo@end deftypefun 298214501Srpaulo 299214501Srpaulo@node Managing the History File 300214501Srpaulo@subsection Managing the History File 301214501Srpaulo 302214501SrpauloThe History library can read the history from and write it to a file. 303214501SrpauloThis section documents the functions for managing a history file. 304214501Srpaulo 305214501Srpaulo@deftypefun int read_history (const char *filename) 306214501SrpauloAdd the contents of @var{filename} to the history list, a line at a time. 307214501SrpauloIf @var{filename} is @code{NULL}, then read from @file{~/.history}. 308214501SrpauloReturns 0 if successful, or @code{errno} if not. 309214501Srpaulo@end deftypefun 310214501Srpaulo 311214501Srpaulo@deftypefun int read_history_range (const char *filename, int from, int to) 312214501SrpauloRead a range of lines from @var{filename}, adding them to the history list. 313214501SrpauloStart reading at line @var{from} and end at @var{to}. 314214501SrpauloIf @var{from} is zero, start at the beginning. If @var{to} is less than 315214501Srpaulo@var{from}, then read until the end of the file. If @var{filename} is 316214501Srpaulo@code{NULL}, then read from @file{~/.history}. Returns 0 if successful, 317214501Srpauloor @code{errno} if not. 318214501Srpaulo@end deftypefun 319214501Srpaulo 320214501Srpaulo@deftypefun int write_history (const char *filename) 321214501SrpauloWrite the current history to @var{filename}, overwriting @var{filename} 322214501Srpauloif necessary. 323214501SrpauloIf @var{filename} is @code{NULL}, then write the history list to 324214501Srpaulo@file{~/.history}. 325214501SrpauloReturns 0 on success, or @code{errno} on a read or write error. 326214501Srpaulo@end deftypefun 327214501Srpaulo 328214501Srpaulo@deftypefun int append_history (int nelements, const char *filename) 329214501SrpauloAppend the last @var{nelements} of the history list to @var{filename}. 330214501SrpauloIf @var{filename} is @code{NULL}, then append to @file{~/.history}. 331Returns 0 on success, or @code{errno} on a read or write error. 332@end deftypefun 333 334@deftypefun int history_truncate_file (const char *filename, int nlines) 335Truncate the history file @var{filename}, leaving only the last 336@var{nlines} lines. 337If @var{filename} is @code{NULL}, then @file{~/.history} is truncated. 338Returns 0 on success, or @code{errno} on failure. 339@end deftypefun 340 341@node History Expansion 342@subsection History Expansion 343 344These functions implement history expansion. 345 346@deftypefun int history_expand (char *string, char **output) 347Expand @var{string}, placing the result into @var{output}, a pointer 348to a string (@pxref{History Interaction}). Returns: 349@table @code 350@item 0 351If no expansions took place (or, if the only change in 352the text was the removal of escape characters preceding the history expansion 353character); 354@item 1 355if expansions did take place; 356@item -1 357if there was an error in expansion; 358@item 2 359if the returned line should be displayed, but not executed, 360as with the @code{:p} modifier (@pxref{Modifiers}). 361@end table 362 363If an error ocurred in expansion, then @var{output} contains a descriptive 364error message. 365@end deftypefun 366 367@deftypefun {char *} get_history_event (const char *string, int *cindex, int qchar) 368Returns the text of the history event beginning at @var{string} + 369@var{*cindex}. @var{*cindex} is modified to point to after the event 370specifier. At function entry, @var{cindex} points to the index into 371@var{string} where the history event specification begins. @var{qchar} 372is a character that is allowed to end the event specification in addition 373to the ``normal'' terminating characters. 374@end deftypefun 375 376@deftypefun {char **} history_tokenize (const char *string) 377Return an array of tokens parsed out of @var{string}, much as the 378shell might. The tokens are split on the characters in the 379@var{history_word_delimiters} variable, 380and shell quoting conventions are obeyed. 381@end deftypefun 382 383@deftypefun {char *} history_arg_extract (int first, int last, const char *string) 384Extract a string segment consisting of the @var{first} through @var{last} 385arguments present in @var{string}. Arguments are split using 386@code{history_tokenize}. 387@end deftypefun 388 389@node History Variables 390@section History Variables 391 392This section describes the externally-visible variables exported by 393the @sc{gnu} History Library. 394 395@deftypevar int history_base 396The logical offset of the first entry in the history list. 397@end deftypevar 398 399@deftypevar int history_length 400The number of entries currently stored in the history list. 401@end deftypevar 402 403@deftypevar int history_max_entries 404The maximum number of history entries. This must be changed using 405@code{stifle_history()}. 406@end deftypevar 407 408@deftypevar char history_expansion_char 409The character that introduces a history event. The default is @samp{!}. 410Setting this to 0 inhibits history expansion. 411@end deftypevar 412 413@deftypevar char history_subst_char 414The character that invokes word substitution if found at the start of 415a line. The default is @samp{^}. 416@end deftypevar 417 418@deftypevar char history_comment_char 419During tokenization, if this character is seen as the first character 420of a word, then it and all subsequent characters up to a newline are 421ignored, suppressing history expansion for the remainder of the line. 422This is disabled by default. 423@end deftypevar 424 425@deftypevar {char *} history_word_delimiters 426The characters that separate tokens for @code{history_tokenize()}. 427The default value is @code{" \t\n()<>;&|"}. 428@end deftypevar 429 430@deftypevar {char *} history_no_expand_chars 431The list of characters which inhibit history expansion if found immediately 432following @var{history_expansion_char}. The default is space, tab, newline, 433carriage return, and @samp{=}. 434@end deftypevar 435 436@deftypevar {char *} history_search_delimiter_chars 437The list of additional characters which can delimit a history search 438string, in addition to space, TAB, @samp{:} and @samp{?} in the case of 439a substring search. The default is empty. 440@end deftypevar 441 442@deftypevar int history_quotes_inhibit_expansion 443If non-zero, single-quoted words are not scanned for the history expansion 444character. The default value is 0. 445@end deftypevar 446 447@deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function 448This should be set to the address of a function that takes two arguments: 449a @code{char *} (@var{string}) 450and an @code{int} index into that string (@var{i}). 451It should return a non-zero value if the history expansion starting at 452@var{string}[@var{i}] should not be performed; zero if the expansion should 453be done. 454It is intended for use by applications like Bash that use the history 455expansion character for additional purposes. 456By default, this variable is set to @code{NULL}. 457@end deftypevar 458 459@node History Programming Example 460@section History Programming Example 461 462The following program demonstrates simple use of the @sc{gnu} History Library. 463 464@smallexample 465#include <stdio.h> 466#include <readline/history.h> 467 468main (argc, argv) 469 int argc; 470 char **argv; 471@{ 472 char line[1024], *t; 473 int len, done = 0; 474 475 line[0] = 0; 476 477 using_history (); 478 while (!done) 479 @{ 480 printf ("history$ "); 481 fflush (stdout); 482 t = fgets (line, sizeof (line) - 1, stdin); 483 if (t && *t) 484 @{ 485 len = strlen (t); 486 if (t[len - 1] == '\n') 487 t[len - 1] = '\0'; 488 @} 489 490 if (!t) 491 strcpy (line, "quit"); 492 493 if (line[0]) 494 @{ 495 char *expansion; 496 int result; 497 498 result = history_expand (line, &expansion); 499 if (result) 500 fprintf (stderr, "%s\n", expansion); 501 502 if (result < 0 || result == 2) 503 @{ 504 free (expansion); 505 continue; 506 @} 507 508 add_history (expansion); 509 strncpy (line, expansion, sizeof (line) - 1); 510 free (expansion); 511 @} 512 513 if (strcmp (line, "quit") == 0) 514 done = 1; 515 else if (strcmp (line, "save") == 0) 516 write_history ("history_file"); 517 else if (strcmp (line, "read") == 0) 518 read_history ("history_file"); 519 else if (strcmp (line, "list") == 0) 520 @{ 521 register HIST_ENTRY **the_list; 522 register int i; 523 524 the_list = history_list (); 525 if (the_list) 526 for (i = 0; the_list[i]; i++) 527 printf ("%d: %s\n", i + history_base, the_list[i]->line); 528 @} 529 else if (strncmp (line, "delete", 6) == 0) 530 @{ 531 int which; 532 if ((sscanf (line + 6, "%d", &which)) == 1) 533 @{ 534 HIST_ENTRY *entry = remove_history (which); 535 if (!entry) 536 fprintf (stderr, "No such entry %d\n", which); 537 else 538 @{ 539 free (entry->line); 540 free (entry); 541 @} 542 @} 543 else 544 @{ 545 fprintf (stderr, "non-numeric arg given to `delete'\n"); 546 @} 547 @} 548 @} 549@} 550@end smallexample 551