jpayne@68: .\" jpayne@68: .\" MAN PAGE COMMENTS to jpayne@68: .\" jpayne@68: .\" Chet Ramey jpayne@68: .\" Information Network Services jpayne@68: .\" Case Western Reserve University jpayne@68: .\" chet.ramey@case.edu jpayne@68: .\" jpayne@68: .\" Last Change: Fri Jul 17 09:43:01 EDT 2020 jpayne@68: .\" jpayne@68: .TH HISTORY 3 "2020 July 17" "GNU History 8.1" jpayne@68: .\" jpayne@68: .\" File Name macro. This used to be `.PN', for Path Name, jpayne@68: .\" but Sun doesn't seem to like that very much. jpayne@68: .\" jpayne@68: .de FN jpayne@68: \fI\|\\$1\|\fP jpayne@68: .. jpayne@68: .ds lp \fR\|(\fP jpayne@68: .ds rp \fR\|)\fP jpayne@68: .\" FnN return-value fun-name N arguments jpayne@68: .de Fn1 jpayne@68: \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3\fP\\*(rp jpayne@68: .br jpayne@68: .. jpayne@68: .de Fn2 jpayne@68: .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4\fP\\*(rp jpayne@68: .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4\fP\\*(rp jpayne@68: .br jpayne@68: .. jpayne@68: .de Fn3 jpayne@68: .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4,\|\\$5\fP\|\\*(rp jpayne@68: .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4, \\$5\fP\\*(rp jpayne@68: .br jpayne@68: .. jpayne@68: .de Vb jpayne@68: \fI\\$1\fP \fB\\$2\fP jpayne@68: .br jpayne@68: .. jpayne@68: .SH NAME jpayne@68: history \- GNU History Library jpayne@68: .SH COPYRIGHT jpayne@68: .if t The GNU History Library is Copyright \(co 1989-2020 by the Free Software Foundation, Inc. jpayne@68: .if n The GNU History Library is Copyright (C) 1989-2020 by the Free Software Foundation, Inc. jpayne@68: .SH DESCRIPTION jpayne@68: Many programs read input from the user a line at a time. The GNU jpayne@68: History library is able to keep track of those lines, associate arbitrary jpayne@68: data with each line, and utilize information from previous lines in jpayne@68: composing new ones. jpayne@68: .PP jpayne@68: .SH "HISTORY EXPANSION" jpayne@68: The history library supports a history expansion feature that jpayne@68: is identical to the history expansion in jpayne@68: .BR bash. jpayne@68: This section describes what syntax features are available. jpayne@68: .PP jpayne@68: History expansions introduce words from the history list into jpayne@68: the input stream, making it easy to repeat commands, insert the jpayne@68: arguments to a previous command into the current input line, or jpayne@68: fix errors in previous commands quickly. jpayne@68: .PP jpayne@68: History expansion is usually performed immediately after a complete line jpayne@68: is read. jpayne@68: It takes place in two parts. jpayne@68: The first is to determine which line from the history list jpayne@68: to use during substitution. jpayne@68: The second is to select portions of that line for inclusion into jpayne@68: the current one. jpayne@68: The line selected from the history is the \fIevent\fP, jpayne@68: and the portions of that line that are acted upon are \fIwords\fP. jpayne@68: Various \fImodifiers\fP are available to manipulate the selected words. jpayne@68: The line is broken into words in the same fashion as \fBbash\fP jpayne@68: does when reading input, jpayne@68: so that several words that would otherwise be separated jpayne@68: are considered one word when surrounded by quotes (see the jpayne@68: description of \fBhistory_tokenize()\fP below). jpayne@68: History expansions are introduced by the appearance of the jpayne@68: history expansion character, which is \^\fB!\fP\^ by default. jpayne@68: Only backslash (\^\fB\e\fP\^) and single quotes can quote jpayne@68: the history expansion character. jpayne@68: .SS Event Designators jpayne@68: An event designator is a reference to a command line entry in the jpayne@68: history list. jpayne@68: Unless the reference is absolute, events are relative to the current jpayne@68: position in the history list. jpayne@68: .PP jpayne@68: .PD 0 jpayne@68: .TP jpayne@68: .B ! jpayne@68: Start a history substitution, except when followed by a jpayne@68: .BR blank , jpayne@68: newline, = or (. jpayne@68: .TP jpayne@68: .B !\fIn\fR jpayne@68: Refer to command line jpayne@68: .IR n . jpayne@68: .TP jpayne@68: .B !\-\fIn\fR jpayne@68: Refer to the current command minus jpayne@68: .IR n . jpayne@68: .TP jpayne@68: .B !! jpayne@68: Refer to the previous command. This is a synonym for `!\-1'. jpayne@68: .TP jpayne@68: .B !\fIstring\fR jpayne@68: Refer to the most recent command jpayne@68: preceding the current position in the history list jpayne@68: starting with jpayne@68: .IR string . jpayne@68: .TP jpayne@68: .B !?\fIstring\fR\fB[?]\fR jpayne@68: Refer to the most recent command jpayne@68: preceding the current position in the history list jpayne@68: containing jpayne@68: .IR string . jpayne@68: The trailing \fB?\fP may be omitted if jpayne@68: .I string jpayne@68: is followed immediately by a newline. jpayne@68: If \fIstring\fP is missing, the string from the most recent search is used; jpayne@68: it is an error if there is no previous search string. jpayne@68: .TP jpayne@68: .B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u jpayne@68: Quick substitution. Repeat the last command, replacing jpayne@68: .I string1 jpayne@68: with jpayne@68: .IR string2 . jpayne@68: Equivalent to jpayne@68: ``!!:s\d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\u'' jpayne@68: (see \fBModifiers\fP below). jpayne@68: .TP jpayne@68: .B !# jpayne@68: The entire command line typed so far. jpayne@68: .PD jpayne@68: .SS Word Designators jpayne@68: Word designators are used to select desired words from the event. jpayne@68: A jpayne@68: .B : jpayne@68: separates the event specification from the word designator. jpayne@68: It may be omitted if the word designator begins with a jpayne@68: .BR ^ , jpayne@68: .BR $ , jpayne@68: .BR * , jpayne@68: .BR \- , jpayne@68: or jpayne@68: .BR % . jpayne@68: Words are numbered from the beginning of the line, jpayne@68: with the first word being denoted by 0 (zero). jpayne@68: Words are inserted into the current line separated by single spaces. jpayne@68: .PP jpayne@68: .PD 0 jpayne@68: .TP jpayne@68: .B 0 (zero) jpayne@68: The zeroth word. For the shell, this is the command jpayne@68: word. jpayne@68: .TP jpayne@68: .I n jpayne@68: The \fIn\fRth word. jpayne@68: .TP jpayne@68: .B ^ jpayne@68: The first argument. That is, word 1. jpayne@68: .TP jpayne@68: .B $ jpayne@68: The last word. This is usually the last argument, but will expand to the jpayne@68: zeroth word if there is only one word in the line. jpayne@68: .TP jpayne@68: .B % jpayne@68: The first word matched by the most recent `?\fIstring\fR?' search, jpayne@68: if the search string begins with a character that is part of a word. jpayne@68: .TP jpayne@68: .I x\fB\-\fPy jpayne@68: A range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'. jpayne@68: .TP jpayne@68: .B * jpayne@68: All of the words but the zeroth. This is a synonym jpayne@68: for `\fI1\-$\fP'. It is not an error to use jpayne@68: .B * jpayne@68: if there is just one jpayne@68: word in the event; the empty string is returned in that case. jpayne@68: .TP jpayne@68: .B x* jpayne@68: Abbreviates \fIx\-$\fP. jpayne@68: .TP jpayne@68: .B x\- jpayne@68: Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word. jpayne@68: If \fBx\fP is missing, it defaults to 0. jpayne@68: .PD jpayne@68: .PP jpayne@68: If a word designator is supplied without an event specification, the jpayne@68: previous command is used as the event. jpayne@68: .SS Modifiers jpayne@68: After the optional word designator, there may appear a sequence of jpayne@68: one or more of the following modifiers, each preceded by a `:'. jpayne@68: These modify, or edit, the word or words selected from the history event. jpayne@68: .PP jpayne@68: .PD 0 jpayne@68: .PP jpayne@68: .TP jpayne@68: .B h jpayne@68: Remove a trailing file name component, leaving only the head. jpayne@68: .TP jpayne@68: .B t jpayne@68: Remove all leading file name components, leaving the tail. jpayne@68: .TP jpayne@68: .B r jpayne@68: Remove a trailing suffix of the form \fI.xxx\fP, leaving the jpayne@68: basename. jpayne@68: .TP jpayne@68: .B e jpayne@68: Remove all but the trailing suffix. jpayne@68: .TP jpayne@68: .B p jpayne@68: Print the new command but do not execute it. jpayne@68: .TP jpayne@68: .B q jpayne@68: Quote the substituted words, escaping further substitutions. jpayne@68: .TP jpayne@68: .B x jpayne@68: Quote the substituted words as with jpayne@68: .BR q , jpayne@68: but break into words at jpayne@68: .B blanks jpayne@68: and newlines. jpayne@68: The \fBq\fP and \fBx\fP modifiers are mutually exclusive; the last one jpayne@68: supplied is used. jpayne@68: .TP jpayne@68: .B s/\fIold\fP/\fInew\fP/ jpayne@68: Substitute jpayne@68: .I new jpayne@68: for the first occurrence of jpayne@68: .I old jpayne@68: in the event line. jpayne@68: Any character may be used as the delimiter in place of /. jpayne@68: The final delimiter is optional if it is the last character of the jpayne@68: event line. jpayne@68: The delimiter may be quoted in jpayne@68: .I old jpayne@68: and jpayne@68: .I new jpayne@68: with a single backslash. If & appears in jpayne@68: .IR new , jpayne@68: it is replaced by jpayne@68: .IR old . jpayne@68: A single backslash will quote the &. jpayne@68: If jpayne@68: .I old jpayne@68: is null, it is set to the last jpayne@68: .I old jpayne@68: substituted, or, if no previous history substitutions took place, jpayne@68: the last jpayne@68: .I string jpayne@68: in a jpayne@68: .B !?\fIstring\fR\fB[?]\fR jpayne@68: search. jpayne@68: If jpayne@68: .I new jpayne@68: is null, each matching jpayne@68: .I old jpayne@68: is deleted. jpayne@68: .TP jpayne@68: .B & jpayne@68: Repeat the previous substitution. jpayne@68: .TP jpayne@68: .B g jpayne@68: Cause changes to be applied over the entire event line. This is jpayne@68: used in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR') jpayne@68: or `\fB:&\fP'. If used with jpayne@68: `\fB:s\fP', any delimiter can be used jpayne@68: in place of /, and the final delimiter is optional jpayne@68: if it is the last character of the event line. jpayne@68: An \fBa\fP may be used as a synonym for \fBg\fP. jpayne@68: .TP jpayne@68: .B G jpayne@68: Apply the following `\fBs\fP' or `\fB&\fP' modifier once to each word jpayne@68: in the event line. jpayne@68: .PD jpayne@68: .SH "PROGRAMMING WITH HISTORY FUNCTIONS" jpayne@68: This section describes how to use the History library in other programs. jpayne@68: .SS Introduction to History jpayne@68: A programmer using the History library has available functions jpayne@68: for remembering lines on a history list, associating arbitrary data jpayne@68: with a line, removing lines from the list, searching through the list jpayne@68: for a line containing an arbitrary text string, and referencing any line jpayne@68: in the list directly. In addition, a history \fIexpansion\fP function jpayne@68: is available which provides for a consistent user interface across jpayne@68: different programs. jpayne@68: .PP jpayne@68: The user using programs written with the History library has the jpayne@68: benefit of a consistent user interface with a set of well-known jpayne@68: commands for manipulating the text of previous lines and using that text jpayne@68: in new commands. The basic history manipulation commands are jpayne@68: identical to jpayne@68: the history substitution provided by \fBbash\fP. jpayne@68: .PP jpayne@68: The programmer can also use the readline library, which jpayne@68: includes some history manipulation by default, and has the added jpayne@68: advantage of command line editing. jpayne@68: .PP jpayne@68: Before declaring any functions using any functionality the History jpayne@68: library provides in other code, an application writer should include jpayne@68: the file jpayne@68: .FN jpayne@68: in any file that uses the jpayne@68: History library's features. It supplies extern declarations for all jpayne@68: of the library's public functions and variables, and declares all of jpayne@68: the public data structures. jpayne@68: .SS History Storage jpayne@68: The history list is an array of history entries. A history entry is jpayne@68: declared as follows: jpayne@68: .PP jpayne@68: .Vb "typedef void *" histdata_t; jpayne@68: .PP jpayne@68: .nf jpayne@68: typedef struct _hist_entry { jpayne@68: char *line; jpayne@68: char *timestamp; jpayne@68: histdata_t data; jpayne@68: } HIST_ENTRY; jpayne@68: .fi jpayne@68: .PP jpayne@68: The history list itself might therefore be declared as jpayne@68: .PP jpayne@68: .Vb "HIST_ENTRY **" the_history_list; jpayne@68: .PP jpayne@68: The state of the History library is encapsulated into a single structure: jpayne@68: .PP jpayne@68: .nf jpayne@68: /* jpayne@68: * A structure used to pass around the current state of the history. jpayne@68: */ jpayne@68: typedef struct _hist_state { jpayne@68: HIST_ENTRY **entries; /* Pointer to the entries themselves. */ jpayne@68: int offset; /* The location pointer within this array. */ jpayne@68: int length; /* Number of elements within this array. */ jpayne@68: int size; /* Number of slots allocated to this array. */ jpayne@68: int flags; jpayne@68: } HISTORY_STATE; jpayne@68: .fi jpayne@68: .PP jpayne@68: If the flags member includes \fBHS_STIFLED\fP, the history has been jpayne@68: stifled. jpayne@68: .SH "History Functions" jpayne@68: This section describes the calling sequence for the various functions jpayne@68: exported by the GNU History library. jpayne@68: .SS Initializing History and State Management jpayne@68: This section describes functions used to initialize and manage jpayne@68: the state of the History library when you want to use the history jpayne@68: functions in your program. jpayne@68: jpayne@68: .Fn1 void using_history void jpayne@68: Begin a session in which the history functions might be used. This jpayne@68: initializes the interactive variables. jpayne@68: jpayne@68: .Fn1 "HISTORY_STATE *" history_get_history_state void jpayne@68: Return a structure describing the current state of the input history. jpayne@68: jpayne@68: .Fn1 void history_set_history_state "HISTORY_STATE *state" jpayne@68: Set the state of the history list according to \fIstate\fP. jpayne@68: jpayne@68: .SS History List Management jpayne@68: These functions manage individual entries on the history list, or set jpayne@68: parameters managing the list itself. jpayne@68: jpayne@68: .Fn1 void add_history "const char *string" jpayne@68: Place \fIstring\fP at the end of the history list. The associated data jpayne@68: field (if any) is set to \fBNULL\fP. jpayne@68: If the maximum number of history entries has been set using jpayne@68: \fBstifle_history()\fP, and the new number of history entries would exceed jpayne@68: that maximum, the oldest history entry is removed. jpayne@68: jpayne@68: .Fn1 void add_history_time "const char *string" jpayne@68: Change the time stamp associated with the most recent history entry to jpayne@68: \fIstring\fP. jpayne@68: jpayne@68: .Fn1 "HIST_ENTRY *" remove_history "int which" jpayne@68: Remove history entry at offset \fIwhich\fP from the history. The jpayne@68: removed element is returned so you can free the line, data, jpayne@68: and containing structure. jpayne@68: jpayne@68: .Fn1 "histdata_t" free_history_entry "HIST_ENTRY *histent" jpayne@68: Free the history entry \fIhistent\fP and any history library private jpayne@68: data associated with it. Returns the application-specific data jpayne@68: so the caller can dispose of it. jpayne@68: jpayne@68: .Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" "histdata_t data" jpayne@68: Make the history entry at offset \fIwhich\fP have \fIline\fP and \fIdata\fP. jpayne@68: This returns the old entry so the caller can dispose of any jpayne@68: application-specific data. In the case jpayne@68: of an invalid \fIwhich\fP, a \fBNULL\fP pointer is returned. jpayne@68: jpayne@68: .Fn1 void clear_history "void" jpayne@68: Clear the history list by deleting all the entries. jpayne@68: jpayne@68: .Fn1 void stifle_history "int max" jpayne@68: Stifle the history list, remembering only the last \fImax\fP entries. jpayne@68: The history list will contain only \fImax\fP entries at a time. jpayne@68: jpayne@68: .Fn1 int unstifle_history "void" jpayne@68: Stop stifling the history. This returns the previously-set jpayne@68: maximum number of history entries (as set by \fBstifle_history()\fP). jpayne@68: history was stifled. The value is positive if the history was jpayne@68: stifled, negative if it wasn't. jpayne@68: jpayne@68: .Fn1 int history_is_stifled "void" jpayne@68: Returns non-zero if the history is stifled, zero if it is not. jpayne@68: jpayne@68: .SS Information About the History List jpayne@68: jpayne@68: These functions return information about the entire history list or jpayne@68: individual list entries. jpayne@68: jpayne@68: .Fn1 "HIST_ENTRY **" history_list "void" jpayne@68: Return a \fBNULL\fP terminated array of \fIHIST_ENTRY *\fP which is the jpayne@68: current input history. Element 0 of this list is the beginning of time. jpayne@68: If there is no history, return \fBNULL\fP. jpayne@68: jpayne@68: .Fn1 int where_history "void" jpayne@68: Returns the offset of the current history element. jpayne@68: jpayne@68: .Fn1 "HIST_ENTRY *" current_history "void" jpayne@68: Return the history entry at the current position, as determined by jpayne@68: \fBwhere_history()\fP. If there is no entry there, return a \fBNULL\fP jpayne@68: pointer. jpayne@68: jpayne@68: .Fn1 "HIST_ENTRY *" history_get "int offset" jpayne@68: Return the history entry at position \fIoffset\fP. jpayne@68: The range of valid values of \fIoffset\fP starts at \fBhistory_base\fP jpayne@68: and ends at \fBhistory_length\fP \- 1. jpayne@68: If there is no entry there, or if \fIoffset\fP is outside the valid jpayne@68: range, return a \fBNULL\fP pointer. jpayne@68: jpayne@68: .Fn1 "time_t" history_get_time "HIST_ENTRY *" jpayne@68: Return the time stamp associated with the history entry passed as the argument. jpayne@68: jpayne@68: .Fn1 int history_total_bytes "void" jpayne@68: Return the number of bytes that the primary history entries are using. jpayne@68: This function returns the sum of the lengths of all the lines in the jpayne@68: history. jpayne@68: jpayne@68: .SS Moving Around the History List jpayne@68: jpayne@68: These functions allow the current index into the history list to be jpayne@68: set or changed. jpayne@68: jpayne@68: .Fn1 int history_set_pos "int pos" jpayne@68: Set the current history offset to \fIpos\fP, an absolute index jpayne@68: into the list. jpayne@68: Returns 1 on success, 0 if \fIpos\fP is less than zero or greater jpayne@68: than the number of history entries. jpayne@68: jpayne@68: .Fn1 "HIST_ENTRY *" previous_history "void" jpayne@68: Back up the current history offset to the previous history entry, and jpayne@68: return a pointer to that entry. If there is no previous entry, return jpayne@68: a \fBNULL\fP pointer. jpayne@68: jpayne@68: .Fn1 "HIST_ENTRY *" next_history "void" jpayne@68: If the current history offset refers to a valid history entry, jpayne@68: increment the current history offset. jpayne@68: If the possibly-incremented history offset refers to a valid history jpayne@68: entry, return a pointer to that entry; jpayne@68: otherwise, return a \fBNULL\fP pointer. jpayne@68: jpayne@68: .SS Searching the History List jpayne@68: jpayne@68: These functions allow searching of the history list for entries containing jpayne@68: a specific string. Searching may be performed both forward and backward jpayne@68: from the current history position. The search may be \fIanchored\fP, jpayne@68: meaning that the string must match at the beginning of the history entry. jpayne@68: jpayne@68: .Fn2 int history_search "const char *string" "int direction" jpayne@68: Search the history for \fIstring\fP, starting at the current history offset. jpayne@68: If \fIdirection\fP is less than 0, then the search is through jpayne@68: previous entries, otherwise through subsequent entries. jpayne@68: If \fIstring\fP is found, then jpayne@68: the current history index is set to that history entry, and the value jpayne@68: returned is the offset in the line of the entry where jpayne@68: \fIstring\fP was found. Otherwise, nothing is changed, and a -1 is jpayne@68: returned. jpayne@68: jpayne@68: .Fn2 int history_search_prefix "const char *string" "int direction" jpayne@68: Search the history for \fIstring\fP, starting at the current history jpayne@68: offset. The search is anchored: matching lines must begin with jpayne@68: \fIstring\fP. If \fIdirection\fP is less than 0, then the search is jpayne@68: through previous entries, otherwise through subsequent entries. jpayne@68: If \fIstring\fP is found, then the jpayne@68: current history index is set to that entry, and the return value is 0. jpayne@68: Otherwise, nothing is changed, and a -1 is returned. jpayne@68: jpayne@68: .Fn3 int history_search_pos "const char *string" "int direction" "int pos" jpayne@68: Search for \fIstring\fP in the history list, starting at \fIpos\fP, an jpayne@68: absolute index into the list. If \fIdirection\fP is negative, the search jpayne@68: proceeds backward from \fIpos\fP, otherwise forward. Returns the absolute jpayne@68: index of the history element where \fIstring\fP was found, or -1 otherwise. jpayne@68: jpayne@68: .SS Managing the History File jpayne@68: The History library can read the history from and write it to a file. jpayne@68: This section documents the functions for managing a history file. jpayne@68: jpayne@68: .Fn1 int read_history "const char *filename" jpayne@68: Add the contents of \fIfilename\fP to the history list, a line at a time. jpayne@68: If \fIfilename\fP is \fBNULL\fP, then read from \fI~/.history\fP. jpayne@68: Returns 0 if successful, or \fBerrno\fP if not. jpayne@68: jpayne@68: .Fn3 int read_history_range "const char *filename" "int from" "int to" jpayne@68: Read a range of lines from \fIfilename\fP, adding them to the history list. jpayne@68: Start reading at line \fIfrom\fP and end at \fIto\fP. jpayne@68: If \fIfrom\fP is zero, start at the beginning. If \fIto\fP is less than jpayne@68: \fIfrom\fP, then read until the end of the file. If \fIfilename\fP is jpayne@68: \fBNULL\fP, then read from \fI~/.history\fP. Returns 0 if successful, jpayne@68: or \fBerrno\fP if not. jpayne@68: jpayne@68: .Fn1 int write_history "const char *filename" jpayne@68: Write the current history to \fIfilename\fP, overwriting \fIfilename\fP jpayne@68: if necessary. jpayne@68: If \fIfilename\fP is \fBNULL\fP, then write the history list to \fI~/.history\fP. jpayne@68: Returns 0 on success, or \fBerrno\fP on a read or write error. jpayne@68: jpayne@68: jpayne@68: .Fn2 int append_history "int nelements" "const char *filename" jpayne@68: Append the last \fInelements\fP of the history list to \fIfilename\fP. jpayne@68: If \fIfilename\fP is \fBNULL\fP, then append to \fI~/.history\fP. jpayne@68: Returns 0 on success, or \fBerrno\fP on a read or write error. jpayne@68: jpayne@68: .Fn2 int history_truncate_file "const char *filename" "int nlines" jpayne@68: Truncate the history file \fIfilename\fP, leaving only the last jpayne@68: \fInlines\fP lines. jpayne@68: If \fIfilename\fP is \fBNULL\fP, then \fI~/.history\fP is truncated. jpayne@68: Returns 0 on success, or \fBerrno\fP on failure. jpayne@68: jpayne@68: .SS History Expansion jpayne@68: jpayne@68: These functions implement history expansion. jpayne@68: jpayne@68: .Fn2 int history_expand "char *string" "char **output" jpayne@68: Expand \fIstring\fP, placing the result into \fIoutput\fP, a pointer jpayne@68: to a string. Returns: jpayne@68: .RS jpayne@68: .PD 0 jpayne@68: .TP jpayne@68: 0 jpayne@68: If no expansions took place (or, if the only change in jpayne@68: the text was the removal of escape characters preceding the history expansion jpayne@68: character); jpayne@68: .TP jpayne@68: 1 jpayne@68: if expansions did take place; jpayne@68: .TP jpayne@68: -1 jpayne@68: if there was an error in expansion; jpayne@68: .TP jpayne@68: 2 jpayne@68: if the returned line should be displayed, but not executed, jpayne@68: as with the \fB:p\fP modifier. jpayne@68: .PD jpayne@68: .RE jpayne@68: If an error occurred in expansion, then \fIoutput\fP contains a descriptive jpayne@68: error message. jpayne@68: jpayne@68: .Fn3 "char *" get_history_event "const char *string" "int *cindex" "int qchar" jpayne@68: Returns the text of the history event beginning at \fIstring\fP + jpayne@68: \fI*cindex\fP. \fI*cindex\fP is modified to point to after the event jpayne@68: specifier. At function entry, \fIcindex\fP points to the index into jpayne@68: \fIstring\fP where the history event specification begins. \fIqchar\fP jpayne@68: is a character that is allowed to end the event specification in addition jpayne@68: to the ``normal'' terminating characters. jpayne@68: jpayne@68: .Fn1 "char **" history_tokenize "const char *string" jpayne@68: Return an array of tokens parsed out of \fIstring\fP, much as the jpayne@68: shell might. jpayne@68: The tokens are split on the characters in the jpayne@68: \fBhistory_word_delimiters\fP variable, jpayne@68: and shell quoting conventions are obeyed. jpayne@68: jpayne@68: .Fn3 "char *" history_arg_extract "int first" "int last" "const char *string" jpayne@68: Extract a string segment consisting of the \fIfirst\fP through \fIlast\fP jpayne@68: arguments present in \fIstring\fP. Arguments are split using jpayne@68: \fBhistory_tokenize()\fP. jpayne@68: jpayne@68: .SS History Variables jpayne@68: jpayne@68: This section describes the externally-visible variables exported by jpayne@68: the GNU History Library. jpayne@68: jpayne@68: .Vb int history_base jpayne@68: The logical offset of the first entry in the history list. jpayne@68: jpayne@68: .Vb int history_length jpayne@68: The number of entries currently stored in the history list. jpayne@68: jpayne@68: .Vb int history_max_entries jpayne@68: The maximum number of history entries. This must be changed using jpayne@68: \fBstifle_history()\fP. jpayne@68: jpayne@68: .Vb int history_write_timestamps jpayne@68: If non-zero, timestamps are written to the history file, so they can be jpayne@68: preserved between sessions. The default value is 0, meaning that jpayne@68: timestamps are not saved. jpayne@68: The current timestamp format uses the value of \fIhistory_comment_char\fP jpayne@68: to delimit timestamp entries in the history file. If that variable does jpayne@68: not have a value (the default), timestamps will not be written. jpayne@68: jpayne@68: .Vb char history_expansion_char jpayne@68: The character that introduces a history event. The default is \fB!\fP. jpayne@68: Setting this to 0 inhibits history expansion. jpayne@68: jpayne@68: .Vb char history_subst_char jpayne@68: The character that invokes word substitution if found at the start of jpayne@68: a line. The default is \fB^\fP. jpayne@68: jpayne@68: .Vb char history_comment_char jpayne@68: During tokenization, if this character is seen as the first character jpayne@68: of a word, then it and all subsequent characters up to a newline are jpayne@68: ignored, suppressing history expansion for the remainder of the line. jpayne@68: This is disabled by default. jpayne@68: jpayne@68: .Vb "char *" history_word_delimiters jpayne@68: The characters that separate tokens for \fBhistory_tokenize()\fP. jpayne@68: The default value is \fB"\ \et\en()<>;&|"\fP. jpayne@68: jpayne@68: .Vb "char *" history_no_expand_chars jpayne@68: The list of characters which inhibit history expansion if found immediately jpayne@68: following \fBhistory_expansion_char\fP. The default is space, tab, newline, jpayne@68: \fB\er\fP, and \fB=\fP. jpayne@68: jpayne@68: .Vb "char *" history_search_delimiter_chars jpayne@68: The list of additional characters which can delimit a history search jpayne@68: string, in addition to space, tab, \fI:\fP and \fI?\fP in the case of jpayne@68: a substring search. The default is empty. jpayne@68: jpayne@68: .Vb int history_quotes_inhibit_expansion jpayne@68: If non-zero, double-quoted words are not scanned for the history expansion jpayne@68: character or the history comment character. The default value is 0. jpayne@68: jpayne@68: .Vb "rl_linebuf_func_t *" history_inhibit_expansion_function jpayne@68: This should be set to the address of a function that takes two arguments: jpayne@68: a \fBchar *\fP (\fIstring\fP) jpayne@68: and an \fBint\fP index into that string (\fIi\fP). jpayne@68: It should return a non-zero value if the history expansion starting at jpayne@68: \fIstring[i]\fP should not be performed; zero if the expansion should jpayne@68: be done. jpayne@68: It is intended for use by applications like \fBbash\fP that use the history jpayne@68: expansion character for additional purposes. jpayne@68: By default, this variable is set to \fBNULL\fP. jpayne@68: .SH FILES jpayne@68: .PD 0 jpayne@68: .TP jpayne@68: .FN ~/.history jpayne@68: Default filename for reading and writing saved history jpayne@68: .PD jpayne@68: .SH "SEE ALSO" jpayne@68: .PD 0 jpayne@68: .TP jpayne@68: \fIThe Gnu Readline Library\fP, Brian Fox and Chet Ramey jpayne@68: .TP jpayne@68: \fIThe Gnu History Library\fP, Brian Fox and Chet Ramey jpayne@68: .TP jpayne@68: \fIbash\fP(1) jpayne@68: .TP jpayne@68: \fIreadline\fP(3) jpayne@68: .PD jpayne@68: .SH AUTHORS jpayne@68: Brian Fox, Free Software Foundation jpayne@68: .br jpayne@68: bfox@gnu.org jpayne@68: .PP jpayne@68: Chet Ramey, Case Western Reserve University jpayne@68: .br jpayne@68: chet.ramey@case.edu jpayne@68: .SH BUG REPORTS jpayne@68: If you find a bug in the jpayne@68: .B history jpayne@68: library, you should report it. But first, you should jpayne@68: make sure that it really is a bug, and that it appears in the latest jpayne@68: version of the jpayne@68: .B history jpayne@68: library that you have. jpayne@68: .PP jpayne@68: Once you have determined that a bug actually exists, mail a jpayne@68: bug report to \fIbug\-readline\fP@\fIgnu.org\fP. jpayne@68: If you have a fix, you are welcome to mail that jpayne@68: as well! Suggestions and `philosophical' bug reports may be mailed jpayne@68: to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet jpayne@68: newsgroup jpayne@68: .BR gnu.bash.bug . jpayne@68: .PP jpayne@68: Comments and bug reports concerning jpayne@68: this manual page should be directed to jpayne@68: .IR chet.ramey@case.edu .