Annotation of embedaddon/readline/doc/hstech.texi, revision 1.1
1.1 ! misho 1: @ignore
! 2: This file documents the user interface to the GNU History library.
! 3:
! 4: Copyright (C) 1988-2014 Free Software Foundation, Inc.
! 5: Authored by Brian Fox and Chet Ramey.
! 6:
! 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
! 9: all copies.
! 10:
! 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).
! 15:
! 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.
! 21:
! 22: Permission is granted to copy and distribute translations of this manual
! 23: into 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:
! 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}.
! 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:
! 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
! 49: composing new ones.
! 50:
! 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
! 57: different programs.
! 58:
! 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}.
! 64:
! 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.
! 68:
! 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.
! 75:
! 76: @node History Storage
! 77: @section History Storage
! 78:
! 79: The history list is an array of history entries. A history entry is
! 80: declared as follows:
! 81:
! 82: @example
! 83: typedef void *histdata_t;
! 84:
! 85: typedef struct _hist_entry @{
! 86: char *line;
! 87: char *timestamp;
! 88: histdata_t data;
! 89: @} HIST_ENTRY;
! 90: @end example
! 91:
! 92: The history list itself might therefore be declared as
! 93:
! 94: @example
! 95: HIST_ENTRY **the_history_list;
! 96: @end example
! 97:
! 98: The 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: */
! 104: typedef 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:
! 113: If the flags member includes @code{HS_STIFLED}, the history has been
! 114: stifled.
! 115:
! 116: @node History Functions
! 117: @section History Functions
! 118:
! 119: This section describes the calling sequence for the various functions
! 120: exported 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:
! 143: This section describes functions used to initialize and manage
! 144: the state of the History library when you want to use the history
! 145: functions in your program.
! 146:
! 147: @deftypefun void using_history (void)
! 148: Begin a session in which the history functions might be used. This
! 149: initializes the interactive variables.
! 150: @end deftypefun
! 151:
! 152: @deftypefun {HISTORY_STATE *} history_get_history_state (void)
! 153: Return a structure describing the current state of the input history.
! 154: @end deftypefun
! 155:
! 156: @deftypefun void history_set_history_state (HISTORY_STATE *state)
! 157: Set 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:
! 163: These functions manage individual entries on the history list, or set
! 164: parameters managing the list itself.
! 165:
! 166: @deftypefun void add_history (const char *string)
! 167: Place @var{string} at the end of the history list. The associated data
! 168: field (if any) is set to @code{NULL}.
! 169: @end deftypefun
! 170:
! 171: @deftypefun void add_history_time (const char *string)
! 172: Change 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)
! 177: Remove history entry at offset @var{which} from the history. The
! 178: removed element is returned so you can free the line, data,
! 179: and containing structure.
! 180: @end deftypefun
! 181:
! 182: @deftypefun {histdata_t} free_history_entry (HIST_ENTRY *histent)
! 183: Free the history entry @var{histent} and any history library private
! 184: data associated with it. Returns the application-specific data
! 185: so 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)
! 189: Make the history entry at offset @var{which} have @var{line} and @var{data}.
! 190: This returns the old entry so the caller can dispose of any
! 191: application-specific data. In the case
! 192: of an invalid @var{which}, a @code{NULL} pointer is returned.
! 193: @end deftypefun
! 194:
! 195: @deftypefun void clear_history (void)
! 196: Clear the history list by deleting all the entries.
! 197: @end deftypefun
! 198:
! 199: @deftypefun void stifle_history (int max)
! 200: Stifle the history list, remembering only the last @var{max} entries.
! 201: @end deftypefun
! 202:
! 203: @deftypefun int unstifle_history (void)
! 204: Stop stifling the history. This returns the previously-set
! 205: maximum number of history entries (as set by @code{stifle_history()}).
! 206: The value is positive if the history was
! 207: stifled, negative if it wasn't.
! 208: @end deftypefun
! 209:
! 210: @deftypefun int history_is_stifled (void)
! 211: Returns 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:
! 217: These functions return information about the entire history list or
! 218: individual list entries.
! 219:
! 220: @deftypefun {HIST_ENTRY **} history_list (void)
! 221: Return a @code{NULL} terminated array of @code{HIST_ENTRY *} which is the
! 222: current input history. Element 0 of this list is the beginning of time.
! 223: If there is no history, return @code{NULL}.
! 224: @end deftypefun
! 225:
! 226: @deftypefun int where_history (void)
! 227: Returns the offset of the current history element.
! 228: @end deftypefun
! 229:
! 230: @deftypefun {HIST_ENTRY *} current_history (void)
! 231: Return the history entry at the current position, as determined by
! 232: @code{where_history()}. If there is no entry there, return a @code{NULL}
! 233: pointer.
! 234: @end deftypefun
! 235:
! 236: @deftypefun {HIST_ENTRY *} history_get (int offset)
! 237: Return the history entry at position @var{offset}, starting from
! 238: @code{history_base} (@pxref{History Variables}).
! 239: If there is no entry there, or if @var{offset}
! 240: is greater than the history length, return a @code{NULL} pointer.
! 241: @end deftypefun
! 242:
! 243: @deftypefun time_t history_get_time (HIST_ENTRY *entry)
! 244: Return the time stamp associated with the history entry @var{entry}.
! 245: @end deftypefun
! 246:
! 247: @deftypefun int history_total_bytes (void)
! 248: Return the number of bytes that the primary history entries are using.
! 249: This function returns the sum of the lengths of all the lines in the
! 250: history.
! 251: @end deftypefun
! 252:
! 253: @node Moving Around the History List
! 254: @subsection Moving Around the History List
! 255:
! 256: These functions allow the current index into the history list to be
! 257: set or changed.
! 258:
! 259: @deftypefun int history_set_pos (int pos)
! 260: Set the current history offset to @var{pos}, an absolute index
! 261: into the list.
! 262: Returns 1 on success, 0 if @var{pos} is less than zero or greater
! 263: than the number of history entries.
! 264: @end deftypefun
! 265:
! 266: @deftypefun {HIST_ENTRY *} previous_history (void)
! 267: Back up the current history offset to the previous history entry, and
! 268: return a pointer to that entry. If there is no previous entry, return
! 269: a @code{NULL} pointer.
! 270: @end deftypefun
! 271:
! 272: @deftypefun {HIST_ENTRY *} next_history (void)
! 273: Move the current history offset forward to the next history entry, and
! 274: return the a pointer to that entry. If there is no next entry, return
! 275: a @code{NULL} pointer.
! 276: @end deftypefun
! 277:
! 278: @node Searching the History List
! 279: @subsection Searching the History List
! 280: @cindex History Searching
! 281:
! 282: These functions allow searching of the history list for entries containing
! 283: a specific string. Searching may be performed both forward and backward
! 284: from the current history position. The search may be @dfn{anchored},
! 285: meaning 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)
! 289: Search the history for @var{string}, starting at the current history offset.
! 290: If @var{direction} is less than 0, then the search is through
! 291: previous entries, otherwise through subsequent entries.
! 292: If @var{string} is found, then
! 293: the current history index is set to that history entry, and the value
! 294: returned is the offset in the line of the entry where
! 295: @var{string} was found. Otherwise, nothing is changed, and a -1 is
! 296: returned.
! 297: @end deftypefun
! 298:
! 299: @deftypefun int history_search_prefix (const char *string, int direction)
! 300: Search the history for @var{string}, starting at the current history
! 301: offset. The search is anchored: matching lines must begin with
! 302: @var{string}. If @var{direction} is less than 0, then the search is
! 303: through previous entries, otherwise through subsequent entries.
! 304: If @var{string} is found, then the
! 305: current history index is set to that entry, and the return value is 0.
! 306: Otherwise, 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)
! 310: Search for @var{string} in the history list, starting at @var{pos}, an
! 311: absolute index into the list. If @var{direction} is negative, the search
! 312: proceeds backward from @var{pos}, otherwise forward. Returns the absolute
! 313: index 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:
! 319: The History library can read the history from and write it to a file.
! 320: This section documents the functions for managing a history file.
! 321:
! 322: @deftypefun int read_history (const char *filename)
! 323: Add the contents of @var{filename} to the history list, a line at a time.
! 324: If @var{filename} is @code{NULL}, then read from @file{~/.history}.
! 325: Returns 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)
! 329: Read a range of lines from @var{filename}, adding them to the history list.
! 330: Start reading at line @var{from} and end at @var{to}.
! 331: If @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,
! 334: or @code{errno} if not.
! 335: @end deftypefun
! 336:
! 337: @deftypefun int write_history (const char *filename)
! 338: Write the current history to @var{filename}, overwriting @var{filename}
! 339: if necessary.
! 340: If @var{filename} is @code{NULL}, then write the history list to
! 341: @file{~/.history}.
! 342: Returns 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)
! 346: Append the last @var{nelements} of the history list to @var{filename}.
! 347: If @var{filename} is @code{NULL}, then append to @file{~/.history}.
! 348: Returns 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)
! 352: Truncate the history file @var{filename}, leaving only the last
! 353: @var{nlines} lines.
! 354: If @var{filename} is @code{NULL}, then @file{~/.history} is truncated.
! 355: Returns 0 on success, or @code{errno} on failure.
! 356: @end deftypefun
! 357:
! 358: @node History Expansion
! 359: @subsection History Expansion
! 360:
! 361: These functions implement history expansion.
! 362:
! 363: @deftypefun int history_expand (char *string, char **output)
! 364: Expand @var{string}, placing the result into @var{output}, a pointer
! 365: to a string (@pxref{History Interaction}). Returns:
! 366: @table @code
! 367: @item 0
! 368: If no expansions took place (or, if the only change in
! 369: the text was the removal of escape characters preceding the history expansion
! 370: character);
! 371: @item 1
! 372: if expansions did take place;
! 373: @item -1
! 374: if there was an error in expansion;
! 375: @item 2
! 376: if the returned line should be displayed, but not executed,
! 377: as with the @code{:p} modifier (@pxref{Modifiers}).
! 378: @end table
! 379:
! 380: If an error occurred in expansion, then @var{output} contains a descriptive
! 381: error message.
! 382: @end deftypefun
! 383:
! 384: @deftypefun {char *} get_history_event (const char *string, int *cindex, int qchar)
! 385: Returns the text of the history event beginning at @var{string} +
! 386: @var{*cindex}. @var{*cindex} is modified to point to after the event
! 387: specifier. At function entry, @var{cindex} points to the index into
! 388: @var{string} where the history event specification begins. @var{qchar}
! 389: is a character that is allowed to end the event specification in addition
! 390: to the ``normal'' terminating characters.
! 391: @end deftypefun
! 392:
! 393: @deftypefun {char **} history_tokenize (const char *string)
! 394: Return an array of tokens parsed out of @var{string}, much as the
! 395: shell might. The tokens are split on the characters in the
! 396: @var{history_word_delimiters} variable,
! 397: and shell quoting conventions are obeyed.
! 398: @end deftypefun
! 399:
! 400: @deftypefun {char *} history_arg_extract (int first, int last, const char *string)
! 401: Extract a string segment consisting of the @var{first} through @var{last}
! 402: arguments 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:
! 409: This section describes the externally-visible variables exported by
! 410: the @sc{gnu} History Library.
! 411:
! 412: @deftypevar int history_base
! 413: The logical offset of the first entry in the history list.
! 414: @end deftypevar
! 415:
! 416: @deftypevar int history_length
! 417: The number of entries currently stored in the history list.
! 418: @end deftypevar
! 419:
! 420: @deftypevar int history_max_entries
! 421: The maximum number of history entries. This must be changed using
! 422: @code{stifle_history()}.
! 423: @end deftypevar
! 424:
! 425: @deftypevar int history_write_timestamps
! 426: If non-zero, timestamps are written to the history file, so they can be
! 427: preserved between sessions. The default value is 0, meaning that
! 428: timestamps are not saved.
! 429:
! 430: The current timestamp format uses the value of @var{history_comment_char}
! 431: to delimit timestamp entries in the history file. If that variable does
! 432: not have a value (the default), timestamps will not be written.
! 433: @end deftypevar
! 434:
! 435: @deftypevar char history_expansion_char
! 436: The character that introduces a history event. The default is @samp{!}.
! 437: Setting this to 0 inhibits history expansion.
! 438: @end deftypevar
! 439:
! 440: @deftypevar char history_subst_char
! 441: The character that invokes word substitution if found at the start of
! 442: a line. The default is @samp{^}.
! 443: @end deftypevar
! 444:
! 445: @deftypevar char history_comment_char
! 446: During tokenization, if this character is seen as the first character
! 447: of a word, then it and all subsequent characters up to a newline are
! 448: ignored, suppressing history expansion for the remainder of the line.
! 449: This is disabled by default.
! 450: @end deftypevar
! 451:
! 452: @deftypevar {char *} history_word_delimiters
! 453: The characters that separate tokens for @code{history_tokenize()}.
! 454: The default value is @code{" \t\n()<>;&|"}.
! 455: @end deftypevar
! 456:
! 457: @deftypevar {char *} history_search_delimiter_chars
! 458: The list of additional characters which can delimit a history search
! 459: string, in addition to space, TAB, @samp{:} and @samp{?} in the case of
! 460: a substring search. The default is empty.
! 461: @end deftypevar
! 462:
! 463: @deftypevar {char *} history_no_expand_chars
! 464: The list of characters which inhibit history expansion if found immediately
! 465: following @var{history_expansion_char}. The default is space, tab, newline,
! 466: carriage return, and @samp{=}.
! 467: @end deftypevar
! 468:
! 469: @deftypevar int history_quotes_inhibit_expansion
! 470: If non-zero, single-quoted words are not scanned for the history expansion
! 471: character. The default value is 0.
! 472: @end deftypevar
! 473:
! 474: @deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function
! 475: This should be set to the address of a function that takes two arguments:
! 476: a @code{char *} (@var{string})
! 477: and an @code{int} index into that string (@var{i}).
! 478: It should return a non-zero value if the history expansion starting at
! 479: @var{string[i]} should not be performed; zero if the expansion should
! 480: be done.
! 481: It is intended for use by applications like Bash that use the history
! 482: expansion character for additional purposes.
! 483: By default, this variable is set to @code{NULL}.
! 484: @end deftypevar
! 485:
! 486: @node History Programming Example
! 487: @section History Programming Example
! 488:
! 489: The following program demonstrates simple use of the @sc{gnu} History Library.
! 490:
! 491: @smallexample
! 492: #include <stdio.h>
! 493: #include <readline/history.h>
! 494:
! 495: main (argc, argv)
! 496: int argc;
! 497: char **argv;
! 498: @{
! 499: char line[1024], *t;
! 500: int len, done = 0;
! 501:
! 502: line[0] = 0;
! 503:
! 504: using_history ();
! 505: while (!done)
! 506: @{
! 507: printf ("history$ ");
! 508: fflush (stdout);
! 509: t = fgets (line, sizeof (line) - 1, stdin);
! 510: if (t && *t)
! 511: @{
! 512: len = strlen (t);
! 513: if (t[len - 1] == '\n')
! 514: t[len - 1] = '\0';
! 515: @}
! 516:
! 517: if (!t)
! 518: strcpy (line, "quit");
! 519:
! 520: if (line[0])
! 521: @{
! 522: char *expansion;
! 523: int result;
! 524:
! 525: result = history_expand (line, &expansion);
! 526: if (result)
! 527: fprintf (stderr, "%s\n", expansion);
! 528:
! 529: if (result < 0 || result == 2)
! 530: @{
! 531: free (expansion);
! 532: continue;
! 533: @}
! 534:
! 535: add_history (expansion);
! 536: strncpy (line, expansion, sizeof (line) - 1);
! 537: free (expansion);
! 538: @}
! 539:
! 540: if (strcmp (line, "quit") == 0)
! 541: done = 1;
! 542: else if (strcmp (line, "save") == 0)
! 543: write_history ("history_file");
! 544: else if (strcmp (line, "read") == 0)
! 545: read_history ("history_file");
! 546: else if (strcmp (line, "list") == 0)
! 547: @{
! 548: register HIST_ENTRY **the_list;
! 549: register int i;
! 550:
! 551: the_list = history_list ();
! 552: if (the_list)
! 553: for (i = 0; the_list[i]; i++)
! 554: printf ("%d: %s\n", i + history_base, the_list[i]->line);
! 555: @}
! 556: else if (strncmp (line, "delete", 6) == 0)
! 557: @{
! 558: int which;
! 559: if ((sscanf (line + 6, "%d", &which)) == 1)
! 560: @{
! 561: HIST_ENTRY *entry = remove_history (which);
! 562: if (!entry)
! 563: fprintf (stderr, "No such entry %d\n", which);
! 564: else
! 565: @{
! 566: free (entry->line);
! 567: free (entry);
! 568: @}
! 569: @}
! 570: else
! 571: @{
! 572: fprintf (stderr, "non-numeric arg given to `delete'\n");
! 573: @}
! 574: @}
! 575: @}
! 576: @}
! 577: @end smallexample
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to hstech.texi CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc