history.html

在非GUI环境下

<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 1.1.3 Modifiers </H3>
<!--docid::SEC5::-->
<P>

After the optional word designator, you can add a sequence of one or more
of the following modifiers, each preceded by a <SAMP>`:'</SAMP>.
</P><P>

<DL COMPACT>

<DT><CODE>h</CODE>
<DD>Remove a trailing pathname component, leaving only the head.
<P>

<DT><CODE>t</CODE>
<DD>Remove all leading  pathname  components, leaving the tail.
<P>

<DT><CODE>r</CODE>
<DD>Remove a trailing suffix of the form <SAMP>`.<VAR>suffix</VAR>'</SAMP>, leaving
the basename.
<P>

<DT><CODE>e</CODE>
<DD>Remove all but the trailing suffix.
<P>

<DT><CODE>p</CODE>
<DD>Print the new command but do not execute it.
<P>

<DT><CODE>s/<VAR>old</VAR>/<VAR>new</VAR>/</CODE>
<DD>Substitute <VAR>new</VAR> for the first occurrence of <VAR>old</VAR> in the
event line.  Any delimiter may be used in place of <SAMP>`/'</SAMP>.
The delimiter may be quoted in <VAR>old</VAR> and <VAR>new</VAR>
with a single backslash.  If <SAMP>`&#38;'</SAMP> appears in <VAR>new</VAR>,
it is replaced by <VAR>old</VAR>.  A single backslash will quote
the <SAMP>`&#38;'</SAMP>.  The final delimiter is optional if it is the last
character on the input line.
<P>

<DT><CODE>&#38;</CODE>
<DD>Repeat the previous substitution.
<P>

<DT><CODE>g</CODE>
<DD><DT><CODE>a</CODE>
<DD>Cause changes to be applied over the entire event line.  Used in
conjunction with <SAMP>`s'</SAMP>, as in <CODE>gs/<VAR>old</VAR>/<VAR>new</VAR>/</CODE>,
or with <SAMP>`&#38;'</SAMP>.
<P>

<DT><CODE>G</CODE>
<DD>Apply the following <SAMP>`s'</SAMP> modifier once to each word in the event.
<P>

</DL>
<P>

<A NAME="Programming with GNU History"></A>
<HR SIZE="6">
<A NAME="SEC6"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC5"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC7"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 2. Programming with GNU History </H1>
<!--docid::SEC6::-->
<P>

This chapter describes how to interface programs that you write
with the GNU History Library.
It should be considered a technical guide.
For information on the interactive use of GNU History, see section <A HREF="history.html#SEC1">1. Using History Interactively</A>.
</P><P>

<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0> 
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC7">2.1 Introduction to History</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">What is the GNU History library for?</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC8">2.2 History Storage</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">How information is stored.</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC9">2.3 History Functions</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Functions that you can use.</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC17">2.4 History Variables</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Variables that control behaviour.</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC18">2.5 History Programming Example</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Example of using the GNU History Library.</TD></TR>
</TABLE></BLOCKQUOTE>
<P>

<A NAME="Introduction to History"></A>
<HR SIZE="6">
<A NAME="SEC7"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC8"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 2.1 Introduction to History </H2>
<!--docid::SEC7::-->
<P>

Many programs read input from the user a line at a time.  The GNU
History library is able to keep track of those lines, associate arbitrary
data with each line, and utilize information from previous lines in
composing new ones. 
</P><P>

The programmer using the History library has available functions
for remembering lines on a history list, associating arbitrary data
with a line, removing lines from the list, searching through the list
for a line containing an arbitrary text string, and referencing any line
in the list directly.  In addition, a history <EM>expansion</EM> function
is available which provides for a consistent user interface across
different programs.
</P><P>

The user using programs written with the History library has the
benefit of a consistent user interface with a set of well-known
commands for manipulating the text of previous lines and using that text
in new commands.  The basic history manipulation commands are similar to
the history substitution provided by <CODE>csh</CODE>.
</P><P>

If the programmer desires, he can use the Readline library, which
includes some history manipulation by default, and has the added
advantage of command line editing.
</P><P>

Before declaring any functions using any functionality the History
library provides in other code, an application writer should include
the file <CODE>&#60;readline/history.h&#62;</CODE> in any file that uses the
History library's features.  It supplies extern declarations for all
of the library's public functions and variables, and declares all of
the public data structures.
</P><P>

<A NAME="History Storage"></A>
<HR SIZE="6">
<A NAME="SEC8"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC7"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC19"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 2.2 History Storage </H2>
<!--docid::SEC8::-->
<P>

The history list is an array of history entries.  A history entry is
declared as follows:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>typedef void *histdata_t;

typedef struct _hist_entry {
  char *line;
  char *timestamp;
  histdata_t data;
} HIST_ENTRY;
</pre></td></tr></table></P><P>

The history list itself might therefore be declared as
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>HIST_ENTRY **the_history_list;
</pre></td></tr></table></P><P>

The state of the History library is encapsulated into a single structure:
</P><P>

<TABLE><tr><td>&nbsp;</td><td class=example><pre>/*
 * 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;
</pre></td></tr></table></P><P>

If the flags member includes <CODE>HS_STIFLED</CODE>, the history has been
stifled.
</P><P>

<A NAME="History Functions"></A>
<HR SIZE="6">
<A NAME="SEC9"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC8"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC10"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC6"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 2.3 History Functions </H2>
<!--docid::SEC9::-->
<P>

This section describes the calling sequence for the various functions
exported by the GNU History library.
</P><P>

<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0> 
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC10">2.3.1 Initializing History and State Management</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Functions to call when you
						want to use history in a
						program.</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Functions used to manage the list
					of history entries.</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Functions returning information about
					the history list.</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC13">2.3.4 Moving Around the History List</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Functions used to change the position
					in the history list.</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Functions to search the history list
					for entries containing a string.</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC15">2.3.6 Managing the History File</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Functions that read and write a file
					containing the history list.</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="history.html#SEC16">2.3.7 History Expansion</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Functions to perform csh-like history
					expansion.</TD></TR>
</TABLE></BLOCKQUOTE>
<P>

<A NAME="Initializing History and State Management"></A>
<HR SIZE="6">
<A NAME="SEC10"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC11"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC22">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 2.3.1 Initializing History and State Management </H3>
<!--docid::SEC10::-->
<P>

This section describes functions used to initialize and manage
the state of the History library when you want to use the history
functions in your program.
</P><P>

<A NAME="IDX2"></A>
<DL>
<DT><U>Function:</U> void <B>using_history</B> <I>(void)</I>
<DD>Begin a session in which the history functions might be used.  This
initializes the interactive variables.
</DL>
</P><P>

<A NAME="IDX3"></A>
<DL>
<DT><U>Function:</U> HISTORY_STATE * <B>history_get_history_state</B> <I>(void)</I>
<DD>Return a structure describing the current state of the input history.
</DL>
</P><P>

<A NAME="IDX4"></A>
<DL>
<DT><U>Function:</U> void <B>history_set_history_state</B> <I>(HISTORY_STATE *state)</I>
<DD>Set the state of the history list according to <VAR>state</VAR>.
</DL>
</P><P>

<A NAME="History List Management"></A>
<HR SIZE="6">
<A NAME="SEC11"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC10"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC12"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC12"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC9"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC17"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_Top">Top</A>]</TD>