.\".\" MAN PAGE COMMENTS to.\".\"	Chet Ramey.\"	Information Network Services.\"	Case Western Reserve University.\"	chet@ins.CWRU.Edu.\".\"	Last Change: Thu Jul 31 08:46:08 EDT 2003.\".TH HISTORY 3 "2003 July 31" "GNU History 5.0".\".\" File Name macro.  This used to be `.PN', for Path Name,.\" but Sun doesn't seem to like that very much..\".de FN\fI\|\\$1\|\fP...ds lp \fR\|(\fP.ds rp \fR\|)\fP.\" FnN return-value fun-name N arguments.de Fn1\fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3\fP\\*(rp.br...de Fn2.if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4\fP\\*(rp.if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4\fP\\*(rp.br...de Fn3.if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4,\|\\$5\fP\|\\*(rp.if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4, \\$5\fP\\*(rp.br...de Vb\fI\\$1\fP \fB\\$2\fP.br...SH NAMEhistory \- GNU History Library.SH COPYRIGHT.if t The GNU History Library is Copyright \(co 1989-2002 by the Free Software Foundation, Inc..if n The GNU History Library is Copyright (C) 1989-2002 by the Free Software Foundation, Inc..SH DESCRIPTIONMany programs read input from the user a line at a time.  The GNUHistory library is able to keep track of those lines, associate arbitrarydata with each line, and utilize information from previous lines incomposing new ones. .PP.SH "HISTORY EXPANSION".PPThe history library supports a history expansion feature thatis identical to the history expansion in.BR bash.This section describes what syntax features are available..PPHistory expansions introduce words from the history list intothe input stream, making it easy to repeat commands, insert thearguments to a previous command into the current input line, orfix errors in previous commands quickly..PPHistory expansion is usually performed immediately after a complete lineis read.It takes place in two parts.The first is to determine which line from the history listto use during substitution.The second is to select portions of that line for inclusion intothe current one.The line selected from the history is the \fIevent\fP,and the portions of that line that are acted upon are \fIwords\fP.Various \fImodifiers\fP are available to manipulate the selected words.The line is broken into words in the same fashion as \fBbash\fPdoes when reading input,so that several words that would otherwise be separated are considered one word when surrounded by quotes (see thedescription of \fBhistory_tokenize()\fP below).History expansions are introduced by the appearance of thehistory expansion character, which is \^\fB!\fP\^ by default.Only backslash (\^\fB\e\fP\^) and single quotes can quotethe history expansion character..SS Event Designators.PPAn event designator is a reference to a command line entry in thehistory list..PP.PD 0.TP.B !Start a history substitution, except when followed by a.BR blank ,newline, = or (..TP.B !\fIn\fRRefer to command line.IR n ..TP.B !\-\fIn\fRRefer to the current command line minus.IR n ..TP.B !!Refer to the previous command.  This is a synonym for `!\-1'..TP.B !\fIstring\fRRefer to the most recent command starting with .IR string ..TP.B !?\fIstring\fR\fB[?]\fRRefer to the most recent command containing.IR string .The trailing \fB?\fP may be omitted if.I stringis followed immediately by a newline..TP.B \d\s+2^\s-2\u\fIstring1\fP\d\s+2^\s-2\u\fIstring2\fP\d\s+2^\s-2\uQuick substitution.  Repeat the last command, replacing.I string1with.IR string2 .Equivalent to``!!:s/\fIstring1\fP/\fIstring2\fP/''(see \fBModifiers\fP below)..TP.B !#The entire command line typed so far..PD.SS Word Designators.PPWord designators are used to select desired words from the event.A .B :separates the event specification from the word designator.It may be omitted if the word designator begins with a.BR ^ ,.BR $ ,.BR * ,.BR \- ,or.BR % .Words are numbered from the beginning of the line,with the first word being denoted by 0 (zero).Words are inserted into the current line separated by single spaces..PP.PD 0.TP.B 0 (zero)The zeroth word.  For the shell, this is the commandword..TP.I nThe \fIn\fRth word..TP.B ^The first argument.  That is, word 1..TP.B $The last argument..TP.B %The word matched by the most recent `?\fIstring\fR?' search..TP.I x\fB\-\fPyA range of words; `\-\fIy\fR' abbreviates `0\-\fIy\fR'..TP.B *All of the words but the zeroth.  This is a synonymfor `\fI1\-$\fP'.  It is not an error to use.B *if there is just oneword in the event; the empty string is returned in that case..TP.B x*Abbreviates \fIx\-$\fP..TP.B x\-Abbreviates \fIx\-$\fP like \fBx*\fP, but omits the last word..PD.PPIf a word designator is supplied without an event specification, theprevious command is used as the event..SS Modifiers.PPAfter the optional word designator, there may appear a sequence ofone or more of the following modifiers, each preceded by a `:'..PP.PD 0.PP.TP.B hRemove a trailing file name component, leaving only the head..TP.B tRemove all leading file name components, leaving the tail..TP.B rRemove a trailing suffix of the form \fI.xxx\fP, leaving thebasename..TP.B eRemove all but the trailing suffix..TP.B pPrint the new command but do not execute it..TP.B qQuote the substituted words, escaping further substitutions..TP.B xQuote the substituted words as with.BR q ,but break into words at.B blanksand newlines..TP.B s/\fIold\fP/\fInew\fP/Substitute.I newfor the first occurrence of.I oldin the event line.  Any delimiter can be used in place of /.  Thefinal delimiter is optional if it is the last character of theevent line.  The delimiter may be quoted in.I oldand.I newwith a single backslash.  If & appears in.IR new ,it is replaced by.IR old .A single backslash will quote the &.  If.I oldis null, it is set to the last.I oldsubstituted, or, if no previous history substitutions took place,the last.I stringin a.B !?\fIstring\fR\fB[?]\fRsearch..TP.B &Repeat the previous substitution..TP.B gCause changes to be applied over the entire event line.  This isused in conjunction with `\fB:s\fP' (e.g., `\fB:gs/\fIold\fP/\fInew\fP/\fR')or `\fB:&\fP'.  If used with`\fB:s\fP', any delimiter can be usedin place of /, and the final delimiter is optionalif it is the last character of the event line.An \fBa\fP may be used as a synonym for \fBg\fP..TP.B GApply the following `\fBs\fP' modifier once to each word in the event line..PD.SH "PROGRAMMING WITH HISTORY FUNCTIONS"This section describes how to use the History library in other programs..SS Introduction to History.PPThe programmer using the History library has available functionsfor remembering lines on a history list, associating arbitrary datawith a line, removing lines from the list, searching through the listfor a line containing an arbitrary text string, and referencing any linein the list directly.  In addition, a history \fIexpansion\fP functionis available which provides for a consistent user interface acrossdifferent programs..PPThe user using programs written with the History library has thebenefit of a consistent user interface with a set of well-knowncommands for manipulating the text of previous lines and using that textin new commands.  The basic history manipulation commands areidentical tothe history substitution provided by \fBbash\fP..PPIf the programmer desires, he can use the Readline library, whichincludes some history manipulation by default, and has the addedadvantage of command line editing..PPBefore declaring any functions using any functionality the Historylibrary provides in other code, an application writer should includethe file.FN <readline/history.h>in any file that uses theHistory library's features.  It supplies extern declarations for allof the library's public functions and variables, and declares all ofthe public data structures..SS History Storage.PPThe history list is an array of history entries.  A history entry isdeclared as follows:.PP.Vb "typedef void *" histdata_t;.PP.nftypedef struct _hist_entry {  char *line;  char *timestamp;  histdata_t data;} HIST_ENTRY;.fi.PPThe history list itself might therefore be declared as.PP.Vb "HIST_ENTRY **" the_history_list;.PPThe state of the History library is encapsulated into a single structure:.PP.nf/* * A structure used to pass around the current state of the history. */typedef struct _hist_state {  HIST_ENTRY **entries; /* Pointer to the entries themselves. */  int offset;           /* The location pointer within this array. */  int length;           /* Number of elements within this array. */  int size;             /* Number of slots allocated to this array. */  int flags;} HISTORY_STATE;.fi.PPIf the flags member includes \fBHS_STIFLED\fP, the history has beenstifled..SH "History Functions".PPThis section describes the calling sequence for the various functionsexported by the GNU History library..SS Initializing History and State ManagementThis section describes functions used to initialize and managethe state of the History library when you want to use the historyfunctions in your program.