readline/doc/hstech.texi

52 for remembering lines on a history list, associating arbitrary data
55 in the list directly.  In addition, a history @dfn{expansion} function
62 in new commands.  The basic history manipulation commands are similar to
63 the history substitution provided by @code{csh}.
66 includes some history manipulation by default, and has the added
71 the file @code{<readline/history.h>} in any file that uses the
79 The history list is an array of history entries.  A history entry is
92 The history list itself might therefore be declared as
102  * A structure used to pass around the current state of the history.
113 If the flags member includes @code{HS_STIFLED}, the history has been
114 stifled.
124 						want to use history in a
127 					of history entries.
129 					the history list.
131 					in the history list.
132 * Searching the History List::		Functions to search the history list
135 					containing the history list.
136 * History Expansion::			Functions to perform csh-like history
144 the state of the History library when you want to use the history
148 Begin a session in which the history functions might be used.  This
153 Return a structure describing the current state of the input history.
157 Set the state of the history list according to @var{state}.
163 These functions manage individual entries on the history list, or set
167 Place @var{string} at the end of the history list.  The associated data
169 If the maximum number of history entries has been set using
170 @code{stifle_history()}, and the new number of history entries would exceed
171 that maximum, the oldest history entry is removed.
175 Change the time stamp associated with the most recent history entry to
180 Remove history entry at offset @var{which} from the history.  The
186 Free the history entry @var{histent} and any history library private
192 Make the history entry at offset @var{which} have @var{line} and @var{data}.
199 Clear the history list by deleting all the entries.
203 Stifle the history list, remembering only the last @var{max} entries.
204 The history list will contain only @var{max} entries at a time.
208 Stop stifling the history.  This returns the previously-set
209 maximum number of history entries (as set by @code{stifle_history()}).
210 The value is positive if the history was
211 stifled, negative if it wasn't.
215 Returns non-zero if the history is stifled, zero if it is not.
221 These functions return information about the entire history list or
226 current input history.  Element 0 of this list is the beginning of time.
227 If there is no history, return @code{NULL}.
231 Returns the offset of the current history element.
235 Return the history entry at the current position, as determined by
241 Return the history entry at position @var{offset}.
250 Return the time stamp associated with the history entry @var{entry}.
255 Return the number of bytes that the primary history entries are using.
257 history.
263 These functions allow the current index into the history list to be
267 Set the current history offset to @var{pos}, an absolute index
270 than the number of history entries.
274 Back up the current history offset to the previous history entry, and
280 If the current history offset refers to a valid history entry,
281 increment the current history offset.
282 If the possibly-incremented history offset refers to a valid history
291 These functions allow searching of the history list for entries containing
293 from the current history position.  The search may be @dfn{anchored},
294 meaning that the string must match at the beginning of the history entry.
298 Search the history for @var{string}, starting at the current history offset.
302 the current history index is set to that history entry, and the value
309 Search the history for @var{string}, starting at the current history
314 current history index is set to that entry, and the return value is 0.
319 Search for @var{string} in the history list, starting at @var{pos}, an
322 index of the history element where @var{string} was found, or -1 otherwise.
328 The History library can read the history from and write it to a file.
329 This section documents the functions for managing a history file.
332 Add the contents of @var{filename} to the history list, a line at a time.
333 If @var{filename} is @code{NULL}, then read from @file{~/.history}.
338 Read a range of lines from @var{filename}, adding them to the history list.
342 @code{NULL}, then read from @file{~/.history}.  Returns 0 if successful,
347 Write the current history to @var{filename}, overwriting @var{filename}
349 If @var{filename} is @code{NULL}, then write the history list to
350 @file{~/.history}.
355 Append the last @var{nelements} of the history list to @var{filename}.
356 If @var{filename} is @code{NULL}, then append to @file{~/.history}.
361 Truncate the history file @var{filename}, leaving only the last
363 If @var{filename} is @code{NULL}, then @file{~/.history} is truncated.
370 These functions implement history expansion.
378 the text was the removal of escape characters preceding the history expansion
386 as with the @code{:p} modifier (@pxref{Modifiers}).
394 Returns the text of the history event beginning at @var{string} +
397 @var{string} where the history event specification begins.  @var{qchar}
422 The logical offset of the first entry in the history list.
426 The number of entries currently stored in the history list.
430 The maximum number of history entries.  This must be changed using
435 If non-zero, timestamps are written to the history file, so they can be
440 to delimit timestamp entries in the history file.  If that variable does
445 The character that introduces a history event.  The default is @samp{!}.
446 Setting this to 0 inhibits history expansion.
457 ignored, suppressing history expansion for the remainder of the line.
467 The list of additional characters which can delimit a history search
473 The list of characters which inhibit history expansion if found immediately
479 If non-zero, the history expansion code implements shell-like quoting:
480 single-quoted words are not scanned for the history expansion
481 character or the history comment character, and double-quoted words may
482 have history expansion performed, since single quotes are not special
490 history expansion function will assume that the line is single-quoted and
492 to @samp{"}, history expansion will assume the line is double quoted until
494 the history expansion function will assume the line is not quoted and
503 It should return a non-zero value if the history expansion starting at
506 It is intended for use by applications like Bash that use the history
518 #include <readline/history.h>
532       printf ("history$ ");