mirror of
https://https.git.savannah.gnu.org/git/bash.git
synced 2026-06-25 06:47:56 +02:00
third set of documentation updates: readline and history
This commit is contained in:
Chet Ramey
+56
-16
@@ -50,6 +50,8 @@ PSDPI = 300 # I don't have any 600-dpi printers
|
||||
DVIPS = dvips -D ${PSDPI} $(QUIETPS) -o $@ # tricky
|
||||
DVIPDF = dvipdfm -o $@ -p ${PAPERSIZE}
|
||||
PSPDF = gs -sPAPERSIZE=${PAPERSIZE} -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -sOutputFile=$@
|
||||
# experimental; uses external texi2dvi for now; this needs pdftex to be present
|
||||
TEXI2PDF = texi2dvi --pdf
|
||||
|
||||
RLSRC = $(srcdir)/rlman.texi $(srcdir)/rluser.texi \
|
||||
$(srcdir)/rltech.texi $(srcdir)/version.texi \
|
||||
@@ -58,7 +60,7 @@ HISTSRC = $(srcdir)/history.texi $(srcdir)/hsuser.texi \
|
||||
$(srcdir)/hstech.texi $(srcdir)/version.texi
|
||||
|
||||
# This should be a program that converts troff to an ascii-readable format
|
||||
NROFF = groff -Tascii
|
||||
NROFF = groff -Tascii -P -c
|
||||
|
||||
# This should be a program that converts troff to postscript
|
||||
GROFF = groff
|
||||
@@ -67,45 +69,75 @@ DVIOBJ = readline.dvi history.dvi rluserman.dvi
|
||||
INFOOBJ = readline.info history.info rluserman.info
|
||||
PSOBJ = readline.ps history.ps rluserman.ps
|
||||
HTMLOBJ = readline.html history.html rluserman.html
|
||||
PDFOBJ = readline.pdf history.pdf rluserman.pdf
|
||||
TEXTOBJ = readline.0 history.0
|
||||
PDFOBJ = readline.pdf history.pdf rluserman.pdf readline_3.pdf history_3.pdf
|
||||
|
||||
INTERMEDIATE_OBJ = rlman.dvi
|
||||
|
||||
CREATED_DOCS = $(DVIOBJ) $(INFOOBJ) $(PSOBJ) $(HTMLOBJ) $(PDFOBJ)
|
||||
|
||||
.SUFFIXES: .ps .txt .dvi .html .pdf
|
||||
.SUFFIXES: .0 .3 .ps .txt .dvi .html .pdf
|
||||
|
||||
.ps.pdf:
|
||||
.3.0:
|
||||
$(RM) $@
|
||||
-${PSPDF} $<
|
||||
-${NROFF} -man $< > $@
|
||||
|
||||
.3.pdf:
|
||||
$(RM) $@
|
||||
-${GROFF} -man -T pdf $< > $@
|
||||
|
||||
.3.ps:
|
||||
$(RM) $@
|
||||
-${GROFF} -man $< > $@
|
||||
|
||||
#.ps.pdf:
|
||||
# $(RM) $@
|
||||
# -${PSPDF} $<
|
||||
|
||||
.dvi.pdf:
|
||||
$(RM) $@
|
||||
-${DVIPDF} $<
|
||||
|
||||
all: info dvi html ps
|
||||
nodvi: info html
|
||||
all: info html text pdf ps dvi
|
||||
nodvi: info html text
|
||||
pdf: $(PDFOBJ)
|
||||
|
||||
readline.dvi: $(RLSRC)
|
||||
TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/rlman.texi
|
||||
mv rlman.dvi readline.dvi
|
||||
$(RM) $@
|
||||
TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) -o $@ $(srcdir)/rlman.texi
|
||||
|
||||
readline.info: $(RLSRC)
|
||||
$(RM) $@
|
||||
$(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/rlman.texi
|
||||
|
||||
readline.pdf: $(RLSRC)
|
||||
$(RM) $@
|
||||
$(TEXI2PDF) -I $(TEXINPUTDIR) -o $@ $(srcdir)/rlman.texi
|
||||
|
||||
rluserman.dvi: $(RLSRC)
|
||||
$(RM) $@
|
||||
TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/rluserman.texi
|
||||
|
||||
rluserman.info: $(RLSRC)
|
||||
$(RM) $@
|
||||
$(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/rluserman.texi
|
||||
|
||||
rluserman.pdf: $(RLSRC)
|
||||
$(RM) $@
|
||||
$(TEXI2PDF) -I $(TEXINPUTDIR) -o $@ $(srcdir)/rluserman.texi
|
||||
|
||||
history.dvi: ${HISTSRC}
|
||||
$(RM) $@
|
||||
TEXINPUTS=.:$(TEXINPUTDIR):$$TEXINPUTS $(TEXI2DVI) $(srcdir)/history.texi
|
||||
|
||||
history.info: ${HISTSRC}
|
||||
$(RM) $@
|
||||
$(MAKEINFO) --no-split -I $(TEXINPUTDIR) -o $@ $(srcdir)/history.texi
|
||||
|
||||
history.pdf: $(HISTSRC)
|
||||
$(RM) $@
|
||||
$(TEXI2PDF) -I $(TEXINPUTDIR) -o $@ $(srcdir)/history.texi
|
||||
|
||||
readline.ps: readline.dvi
|
||||
$(RM) $@
|
||||
$(DVIPS) readline.dvi
|
||||
@@ -119,9 +151,8 @@ history.ps: history.dvi
|
||||
$(DVIPS) history.dvi
|
||||
|
||||
readline.html: ${RLSRC}
|
||||
$(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/rlman.texi
|
||||
sed -e 's:rlman.html:readline.html:' rlman.html > readline.html
|
||||
$(RM) rlman.html
|
||||
$(RM) $@
|
||||
$(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) -o $@ $(srcdir)/rlman.texi
|
||||
|
||||
rluserman.html: ${RLSRC}
|
||||
$(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/rluserman.texi
|
||||
@@ -129,14 +160,23 @@ rluserman.html: ${RLSRC}
|
||||
history.html: ${HISTSRC}
|
||||
$(TEXI2HTML) -menu -monolithic -I $(TEXINPUTDIR) $(srcdir)/history.texi
|
||||
|
||||
history.0: $(srcdir)/history.3
|
||||
readline.0: $(srcdir)/readline.3
|
||||
|
||||
history_3.pdf: $(srcdir)/history.3
|
||||
$(RM) $@
|
||||
-${GROFF} -man -T pdf $< > $@
|
||||
|
||||
readline_3.pdf: $(srcdir)/readline.3
|
||||
$(RM) $@
|
||||
-${GROFF} -man -T pdf $< > $@
|
||||
|
||||
info: $(INFOOBJ)
|
||||
dvi: $(DVIOBJ)
|
||||
ps: $(PSOBJ)
|
||||
html: $(HTMLOBJ)
|
||||
|
||||
readline.pdf: readline.dvi
|
||||
history.pdf: history.dvi
|
||||
rluserman.pdf: rluserman.dvi
|
||||
text: $(TEXTOBJ)
|
||||
pdf: $(PDFOBJ)
|
||||
|
||||
clean:
|
||||
$(RM) *.aux *.cp *.fn *.ky *.log *.pg *.toc *.tp *.vr *.cps *.pgs \
|
||||
|
||||
@@ -0,0 +1,536 @@
|
||||
_H_I_S_T_O_R_Y(3) Library Functions Manual _H_I_S_T_O_R_Y(3)
|
||||
|
||||
NNAAMMEE
|
||||
history - GNU History Library
|
||||
|
||||
CCOOPPYYRRIIGGHHTT
|
||||
The GNU History Library is Copyright (C) 1989-2024 by the Free Software
|
||||
Foundation, Inc.
|
||||
|
||||
DDEESSCCRRIIPPTTIIOONN
|
||||
Many programs read input from the user a line at a time. The GNU His-
|
||||
tory library is able to keep track of those lines, associate arbitrary
|
||||
data with each line, and utilize information from previous lines when
|
||||
composing new ones.
|
||||
|
||||
The History library provides functions that allow applications to their
|
||||
_h_i_s_t_o_r_y, the set of previously-typed lines, which it keeps in a list.
|
||||
Applications can choose which lines to save into a history list, how
|
||||
many commands to save, save a history list to a file, read a history
|
||||
list from a file, and display lines from the history in various for-
|
||||
mats.
|
||||
|
||||
HHIISSTTOORRYY EEXXPPAANNSSIIOONN
|
||||
The history library supports a history expansion feature that is iden-
|
||||
tical to the history expansion in bbaasshh. This section describes what
|
||||
syntax features are available.
|
||||
|
||||
History expansions introduce words from the history list into the input
|
||||
stream, making it easy to repeat commands, insert the arguments to a
|
||||
previous command into the current input line, or fix errors in previous
|
||||
commands quickly.
|
||||
|
||||
History expansion is usually performed immediately after a complete
|
||||
line is read. It takes place in two parts. The first is to determine
|
||||
which history list entry to use during substitution. The second is to
|
||||
select portions of that entry to include into the current one.
|
||||
|
||||
The entry selected from the history is the _e_v_e_n_t, and the portions of
|
||||
that entry that are acted upon are _w_o_r_d_s. Various _m_o_d_i_f_i_e_r_s are avail-
|
||||
able to manipulate the selected words. The entry is split into words
|
||||
in the same fashion as bbaasshh does when reading input, so that several
|
||||
words that would otherwise be separated are considered one word when
|
||||
surrounded by quotes (see the description of hhiissttoorryy__ttookkeenniizzee(()) below).
|
||||
The _e_v_e_n_t _d_e_s_i_g_n_a_t_o_r selects the event, the optional _w_o_r_d _d_e_s_i_g_n_a_t_o_r
|
||||
selects words from the event, and various optional _m_o_d_i_f_i_e_r_s are avail-
|
||||
able to manipulate the selected words.
|
||||
|
||||
History expansions are introduced by the appearance of the history ex-
|
||||
pansion character, which is !! by default. History expansions may ap-
|
||||
pear anywhere in the input, but do not nest.
|
||||
|
||||
Only backslash (\\) and single quotes can quote the history expansion
|
||||
character.
|
||||
|
||||
There is a special abbreviation for substitution, active when the _q_u_i_c_k
|
||||
_s_u_b_s_t_i_t_u_t_i_o_n character (default ^^) is the first character on the line.
|
||||
It selects the previous history list entry, using an event designator
|
||||
equivalent to !!!!, and substitutes one string for another in that entry.
|
||||
It is described below under EEvveenntt DDeessiiggnnaattoorrss. This is the only his-
|
||||
tory expansion that does not begin with the history expansion charac-
|
||||
ter.
|
||||
|
||||
EEvveenntt DDeessiiggnnaattoorrss
|
||||
An event designator is a reference to an entry in the history list.
|
||||
The event designator consists of the portion of the word beginning with
|
||||
the history expansion character and ending with the word designator if
|
||||
present, or the end of the word. Unless the reference is absolute,
|
||||
events are relative to the current position in the history list.
|
||||
|
||||
!! Start a history substitution, except when followed by a bbllaannkk,
|
||||
newline, carriage return, =, or (.
|
||||
!!_n Refer to history list entry _n.
|
||||
!!--_n Refer to the current entry minus _n.
|
||||
!!!! Refer to the previous entry. This is a synonym for "!-1".
|
||||
!!_s_t_r_i_n_g
|
||||
Refer to the most recent command preceding the current position
|
||||
in the history list starting with _s_t_r_i_n_g.
|
||||
!!??_s_t_r_i_n_g[[??]]
|
||||
Refer to the most recent command preceding the current position
|
||||
in the history list containing _s_t_r_i_n_g. The trailing ?? may be
|
||||
omitted if _s_t_r_i_n_g is followed immediately by a newline. If
|
||||
_s_t_r_i_n_g is missing, this uses the string from the most recent
|
||||
search; it is an error if there is no previous search string.
|
||||
^^_s_t_r_i_n_g_1^^_s_t_r_i_n_g_2^^
|
||||
Quick substitution. Repeat the previous command, replacing
|
||||
_s_t_r_i_n_g_1 with _s_t_r_i_n_g_2. Equivalent to "!!:s^_s_t_r_i_n_g_1^_s_t_r_i_n_g_2^"
|
||||
(see MMooddiiffiieerrss below).
|
||||
!!## The entire command line typed so far.
|
||||
|
||||
WWoorrdd DDeessiiggnnaattoorrss
|
||||
Word designators are used to select desired words from the event. They
|
||||
are optional; if the word designator isn't supplied, the history expan-
|
||||
sion uses the entire event. A :: separates the event specification from
|
||||
the word designator. It may be omitted if the word designator begins
|
||||
with a ^^, $$, **, --, or %%. Words are numbered from the beginning of the
|
||||
line, with the first word being denoted by 0 (zero). Words are in-
|
||||
serted into the current line separated by single spaces.
|
||||
|
||||
00 ((zzeerroo))
|
||||
The zeroth word. For the shell, and many other applications,
|
||||
this is the command word.
|
||||
_n The _nth word.
|
||||
^^ The first argument: word 1.
|
||||
$$ The last word. This is usually the last argument, but will ex-
|
||||
pand to the zeroth word if there is only one word in the line.
|
||||
%% The first word matched by the most recent "?_s_t_r_i_n_g?" search, if
|
||||
the search string begins with a character that is part of a
|
||||
word. By default, searches begin at the end of each line and
|
||||
proceed to the beginning, so the first word matched is the one
|
||||
closest to the end of the line.
|
||||
_x--_y A range of words; "-_y" abbreviates "0-_y".
|
||||
** All of the words but the zeroth. This is a synonym for "_1_-_$".
|
||||
It is not an error to use ** if there is just one word in the
|
||||
event; it expands to the empty string in that case.
|
||||
xx** Abbreviates _x_-_$.
|
||||
xx-- Abbreviates _x_-_$ like xx**, but omits the last word. If xx is miss-
|
||||
ing, it defaults to 0.
|
||||
|
||||
If a word designator is supplied without an event specification, the
|
||||
previous command is used as the event, equivalent to !!!!.
|
||||
|
||||
MMooddiiffiieerrss
|
||||
After the optional word designator, the expansion may include a se-
|
||||
quence of one or more of the following modifiers, each preceded by a
|
||||
":". These modify, or edit, the word or words selected from the his-
|
||||
tory event.
|
||||
|
||||
hh Remove a trailing filename component, leaving only the head.
|
||||
tt Remove all leading filename components, leaving the tail.
|
||||
rr Remove a trailing suffix of the form _._x_x_x, leaving the basename.
|
||||
ee Remove all but the trailing suffix.
|
||||
pp Print the new command but do not execute it.
|
||||
qq Quote the substituted words, escaping further substitutions.
|
||||
xx Quote the substituted words as with qq, but break into words at
|
||||
bbllaannkkss and newlines. The qq and xx modifiers are mutually exclu-
|
||||
sive; expansion uses the last one supplied.
|
||||
ss//_o_l_d//_n_e_w//
|
||||
Substitute _n_e_w for the first occurrence of _o_l_d in the event
|
||||
line. Any character may be used as the delimiter in place of /.
|
||||
The final delimiter is optional if it is the last character of
|
||||
the event line. A single backslash will quote the delimiter in
|
||||
_o_l_d and _n_e_w. If & appears in _n_e_w, it is replaced with _o_l_d. A
|
||||
single backslash will quote the &. If _o_l_d is null, it is set to
|
||||
the last _o_l_d substituted, or, if no previous history substitu-
|
||||
tions took place, the last _s_t_r_i_n_g in a !!??_s_t_r_i_n_g[[??]] search. If
|
||||
_n_e_w is null, each matching _o_l_d is deleted.
|
||||
&& Repeat the previous substitution.
|
||||
gg Cause changes to be applied over the entire event line. This is
|
||||
used in conjunction with "::ss" (e.g., "::ggss//_o_l_d//_n_e_w//") or "::&&".
|
||||
If used with "::ss", any delimiter can be used in place of /, and
|
||||
the final delimiter is optional if it is the last character of
|
||||
the event line. An aa may be used as a synonym for gg.
|
||||
GG Apply the following "ss" or "&&" modifier once to each word in the
|
||||
event line.
|
||||
|
||||
PPRROOGGRRAAMMMMIINNGG WWIITTHH HHIISSTTOORRYY FFUUNNCCTTIIOONNSS
|
||||
This section describes how to use the History library in other pro-
|
||||
grams.
|
||||
|
||||
IInnttrroodduuccttiioonn ttoo HHiissttoorryy
|
||||
A programmer using the History library has available functions for re-
|
||||
membering 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 _e_x_p_a_n_s_i_o_n function is avail-
|
||||
able which provides for a consistent user interface across different
|
||||
programs.
|
||||
|
||||
The user using programs written with the History library has the bene-
|
||||
fit 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 identical to the
|
||||
history substitution provided by bbaasshh.
|
||||
|
||||
The programmer can also use the readline library, which includes some
|
||||
history manipulation by default, and has the added advantage of command
|
||||
line editing.
|
||||
|
||||
Before declaring any functions using any functionality the History li-
|
||||
brary provides in other code, an application writer should include the
|
||||
file _<_r_e_a_d_l_i_n_e_/_h_i_s_t_o_r_y_._h_> 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.
|
||||
|
||||
HHiissttoorryy SSttoorraaggee
|
||||
The history list is an array of history entries. A history entry is
|
||||
declared as follows:
|
||||
|
||||
_t_y_p_e_d_e_f _v_o_i_d _* hhiissttddaattaa__tt;;
|
||||
|
||||
typedef struct _hist_entry {
|
||||
char *line;
|
||||
char *timestamp;
|
||||
histdata_t data;
|
||||
} HIST_ENTRY;
|
||||
|
||||
The history list itself might therefore be declared as
|
||||
|
||||
_H_I_S_T___E_N_T_R_Y _*_* tthhee__hhiissttoorryy__lliisstt;;
|
||||
|
||||
The state of the History library is encapsulated into a single struc-
|
||||
ture:
|
||||
|
||||
/*
|
||||
* A structure used to pass around the current state of the history.
|
||||
*/
|
||||
typedef struct _hist_state {
|
||||
HIST_ENTRY **entries; /* Pointer to entry records. */
|
||||
int offset; /* The current record. */
|
||||
int length; /* Number of records in list. */
|
||||
int size; /* Number of records allocated. */
|
||||
int flags;
|
||||
} HISTORY_STATE;
|
||||
|
||||
If the flags member includes HHSS__SSTTIIFFLLEEDD, the history has been stifled.
|
||||
|
||||
HHiissttoorryy FFuunnccttiioonnss
|
||||
This section describes the calling sequence for the various functions
|
||||
exported by the GNU History library.
|
||||
|
||||
IInniittiiaalliizziinngg HHiissttoorryy aanndd SSttaattee MMaannaaggeemmeenntt
|
||||
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.
|
||||
|
||||
_v_o_i_d uussiinngg__hhiissttoorryy (_v_o_i_d)
|
||||
Begin a session in which the history functions might be used. This
|
||||
initializes the interactive variables.
|
||||
|
||||
_H_I_S_T_O_R_Y___S_T_A_T_E _* hhiissttoorryy__ggeett__hhiissttoorryy__ssttaattee (_v_o_i_d)
|
||||
Return a structure describing the current state of the input history.
|
||||
|
||||
_v_o_i_d hhiissttoorryy__sseett__hhiissttoorryy__ssttaattee (_H_I_S_T_O_R_Y___S_T_A_T_E _*_s_t_a_t_e)
|
||||
Set the state of the history list according to _s_t_a_t_e.
|
||||
|
||||
HHiissttoorryy LLiisstt MMaannaaggeemmeenntt
|
||||
These functions manage individual entries on the history list, or set
|
||||
parameters managing the list itself.
|
||||
|
||||
_v_o_i_d aadddd__hhiissttoorryy (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g)
|
||||
Place _s_t_r_i_n_g at the end of the history list. The associated data field
|
||||
(if any) is set to NNUULLLL. If the maximum number of history entries has
|
||||
been set using ssttiiffllee__hhiissttoorryy(()), and the new number of history entries
|
||||
would exceed that maximum, the oldest history entry is removed.
|
||||
|
||||
_v_o_i_d aadddd__hhiissttoorryy__ttiimmee (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g)
|
||||
Change the time stamp associated with the most recent history entry to
|
||||
_s_t_r_i_n_g.
|
||||
|
||||
_H_I_S_T___E_N_T_R_Y _* rreemmoovvee__hhiissttoorryy (_i_n_t _w_h_i_c_h)
|
||||
Remove history entry at offset _w_h_i_c_h from the history. The removed el-
|
||||
ement is returned so you can free the line, data, and containing struc-
|
||||
ture.
|
||||
|
||||
_h_i_s_t_d_a_t_a___t ffrreeee__hhiissttoorryy__eennttrryy (_H_I_S_T___E_N_T_R_Y _*_h_i_s_t_e_n_t)
|
||||
Free the history entry _h_i_s_t_e_n_t and any history library private data as-
|
||||
sociated with it. Returns the application-specific data so the caller
|
||||
can dispose of it.
|
||||
|
||||
_H_I_S_T___E_N_T_R_Y _* rreeppllaaccee__hhiissttoorryy__eennttrryy (_i_n_t _w_h_i_c_h_, _c_o_n_s_t _c_h_a_r _*_l_i_n_e_, _h_i_s_t_-
|
||||
_d_a_t_a___t _d_a_t_a)
|
||||
Make the history entry at offset _w_h_i_c_h have _l_i_n_e and _d_a_t_a. This re-
|
||||
turns the old entry so the caller can dispose of any application-spe-
|
||||
cific data. In the case of an invalid _w_h_i_c_h, a NNUULLLL pointer is re-
|
||||
turned.
|
||||
|
||||
_v_o_i_d cclleeaarr__hhiissttoorryy (_v_o_i_d)
|
||||
Clear the history list by deleting all the entries.
|
||||
|
||||
_v_o_i_d ssttiiffllee__hhiissttoorryy (_i_n_t _m_a_x)
|
||||
Stifle the history list, remembering only the last _m_a_x entries. The
|
||||
history list will contain only _m_a_x entries at a time.
|
||||
|
||||
_i_n_t uunnssttiiffllee__hhiissttoorryy (_v_o_i_d)
|
||||
Stop stifling the history. This returns the previously-set maximum
|
||||
number of history entries (as set by ssttiiffllee__hhiissttoorryy(())). history was
|
||||
stifled. The value is positive if the history was stifled, negative if
|
||||
it wasn't.
|
||||
|
||||
_i_n_t hhiissttoorryy__iiss__ssttiifflleedd (_v_o_i_d)
|
||||
Returns non-zero if the history is stifled, zero if it is not.
|
||||
|
||||
IInnffoorrmmaattiioonn AAbboouutt tthhee HHiissttoorryy LLiisstt
|
||||
These functions return information about the entire history list or in-
|
||||
dividual list entries.
|
||||
|
||||
_H_I_S_T___E_N_T_R_Y _*_* hhiissttoorryy__lliisstt (_v_o_i_d)
|
||||
Return a NNUULLLL terminated array of _H_I_S_T___E_N_T_R_Y _* which is the current in-
|
||||
put history. Element 0 of this list is the beginning of time. If
|
||||
there is no history, return NNUULLLL.
|
||||
|
||||
_i_n_t wwhheerree__hhiissttoorryy (_v_o_i_d)
|
||||
Returns the offset of the current history element.
|
||||
|
||||
_H_I_S_T___E_N_T_R_Y _* ccuurrrreenntt__hhiissttoorryy (_v_o_i_d)
|
||||
Return the history entry at the current position, as determined by
|
||||
wwhheerree__hhiissttoorryy(()). If there is no entry there, return a NNUULLLL pointer.
|
||||
|
||||
_H_I_S_T___E_N_T_R_Y _* hhiissttoorryy__ggeett (_i_n_t _o_f_f_s_e_t)
|
||||
Return the history entry at position _o_f_f_s_e_t. The range of valid values
|
||||
of _o_f_f_s_e_t starts at hhiissttoorryy__bbaassee and ends at hhiissttoorryy__lleennggtthh - 1. If
|
||||
there is no entry there, or if _o_f_f_s_e_t is outside the valid range, re-
|
||||
turn a NNUULLLL pointer.
|
||||
|
||||
_t_i_m_e___t hhiissttoorryy__ggeett__ttiimmee (_H_I_S_T___E_N_T_R_Y _*)
|
||||
Return the time stamp associated with the history entry passed as the
|
||||
argument.
|
||||
|
||||
_i_n_t hhiissttoorryy__ttoottaall__bbyytteess (_v_o_i_d)
|
||||
Return the number of bytes that the primary history entries are using.
|
||||
This function returns the sum of the lengths of all the lines in the
|
||||
history.
|
||||
|
||||
MMoovviinngg AArroouunndd tthhee HHiissttoorryy LLiisstt
|
||||
These functions allow the current index into the history list to be set
|
||||
or changed.
|
||||
|
||||
_i_n_t hhiissttoorryy__sseett__ppooss (_i_n_t _p_o_s)
|
||||
Set the current history offset to _p_o_s, an absolute index into the list.
|
||||
Returns 1 on success, 0 if _p_o_s is less than zero or greater than the
|
||||
number of history entries.
|
||||
|
||||
_H_I_S_T___E_N_T_R_Y _* pprreevviioouuss__hhiissttoorryy (_v_o_i_d)
|
||||
Back up the current history offset to the previous history entry, and
|
||||
return a pointer to that entry. If there is no previous entry, return
|
||||
a NNUULLLL pointer.
|
||||
|
||||
_H_I_S_T___E_N_T_R_Y _* nneexxtt__hhiissttoorryy (_v_o_i_d)
|
||||
If the current history offset refers to a valid history entry, incre-
|
||||
ment the current history offset. If the possibly-incremented history
|
||||
offset refers to a valid history entry, return a pointer to that entry;
|
||||
otherwise, return a NNUULLLL pointer.
|
||||
|
||||
SSeeaarrcchhiinngg tthhee HHiissttoorryy LLiisstt
|
||||
These functions allow searching of the history list for entries con-
|
||||
taining a specific string. Searching may be performed both forward and
|
||||
backward from the current history position. The search may be _a_n_-
|
||||
_c_h_o_r_e_d, meaning that the string must match at the beginning of the his-
|
||||
tory entry.
|
||||
|
||||
_i_n_t hhiissttoorryy__sseeaarrcchh (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _i_n_t _d_i_r_e_c_t_i_o_n)
|
||||
Search the history for _s_t_r_i_n_g, starting at the current history offset.
|
||||
If _d_i_r_e_c_t_i_o_n is less than 0, then the search is through previous en-
|
||||
tries, otherwise through subsequent entries. If _s_t_r_i_n_g is found, then
|
||||
the current history index is set to that history entry, and the value
|
||||
returned is the offset in the line of the entry where _s_t_r_i_n_g was found.
|
||||
Otherwise, nothing is changed, and the function returns -1.
|
||||
|
||||
_i_n_t hhiissttoorryy__sseeaarrcchh__pprreeffiixx (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _i_n_t _d_i_r_e_c_t_i_o_n)
|
||||
Search the history for _s_t_r_i_n_g, starting at the current history offset.
|
||||
The search is anchored: matching lines must begin with _s_t_r_i_n_g. If _d_i_-
|
||||
_r_e_c_t_i_o_n is less than 0, then the search is through previous entries,
|
||||
otherwise through subsequent entries. If _s_t_r_i_n_g is found, then the
|
||||
current history index is set to that entry, and the return value is 0.
|
||||
Otherwise, nothing is changed, and the function returns -1.
|
||||
|
||||
_i_n_t hhiissttoorryy__sseeaarrcchh__ppooss (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _i_n_t _d_i_r_e_c_t_i_o_n_, _i_n_t _p_o_s)
|
||||
Search for _s_t_r_i_n_g in the history list, starting at _p_o_s, an absolute in-
|
||||
dex into the list. If _d_i_r_e_c_t_i_o_n is negative, the search proceeds back-
|
||||
ward from _p_o_s, otherwise forward. Returns the absolute index of the
|
||||
history element where _s_t_r_i_n_g was found, or -1 otherwise.
|
||||
|
||||
MMaannaaggiinngg tthhee HHiissttoorryy FFiillee
|
||||
The History library can read the history from and write it to a file.
|
||||
This section documents the functions for managing a history file.
|
||||
|
||||
_i_n_t rreeaadd__hhiissttoorryy (_c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e)
|
||||
Add the contents of _f_i_l_e_n_a_m_e to the history list, a line at a time. If
|
||||
_f_i_l_e_n_a_m_e is NNUULLLL, then read from _~_/_._h_i_s_t_o_r_y. Returns 0 if successful,
|
||||
or eerrrrnnoo if not.
|
||||
|
||||
_i_n_t rreeaadd__hhiissttoorryy__rraannggee (_c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e_, _i_n_t _f_r_o_m_, _i_n_t _t_o)
|
||||
Read a range of lines from _f_i_l_e_n_a_m_e, adding them to the history list.
|
||||
Start reading at line _f_r_o_m and end at _t_o. If _f_r_o_m is zero, start at
|
||||
the beginning. If _t_o is less than _f_r_o_m, then read until the end of the
|
||||
file. If _f_i_l_e_n_a_m_e is NNUULLLL, then read from _~_/_._h_i_s_t_o_r_y. Returns 0 if
|
||||
successful, or eerrrrnnoo if not.
|
||||
|
||||
_i_n_t wwrriittee__hhiissttoorryy (_c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e)
|
||||
Write the current history to _f_i_l_e_n_a_m_e, overwriting _f_i_l_e_n_a_m_e if neces-
|
||||
sary. If _f_i_l_e_n_a_m_e is NNUULLLL, then write the history list to _~_/_._h_i_s_t_o_r_y.
|
||||
Returns 0 on success, or eerrrrnnoo on a read or write error.
|
||||
|
||||
_i_n_t aappppeenndd__hhiissttoorryy (_i_n_t _n_e_l_e_m_e_n_t_s_, _c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e)
|
||||
Append the last _n_e_l_e_m_e_n_t_s of the history list to _f_i_l_e_n_a_m_e. If _f_i_l_e_n_a_m_e
|
||||
is NNUULLLL, then append to _~_/_._h_i_s_t_o_r_y. Returns 0 on success, or eerrrrnnoo on
|
||||
a read or write error.
|
||||
|
||||
_i_n_t hhiissttoorryy__ttrruunnccaattee__ffiillee (_c_o_n_s_t _c_h_a_r _*_f_i_l_e_n_a_m_e_, _i_n_t _n_l_i_n_e_s)
|
||||
Truncate the history file _f_i_l_e_n_a_m_e, leaving only the last _n_l_i_n_e_s lines.
|
||||
If _f_i_l_e_n_a_m_e is NNUULLLL, then _~_/_._h_i_s_t_o_r_y is truncated. Returns 0 on suc-
|
||||
cess, or eerrrrnnoo on failure.
|
||||
|
||||
HHiissttoorryy EExxppaannssiioonn
|
||||
These functions implement history expansion.
|
||||
|
||||
_i_n_t hhiissttoorryy__eexxppaanndd (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _c_h_a_r _*_*_o_u_t_p_u_t)
|
||||
Expand _s_t_r_i_n_g, placing the result into _o_u_t_p_u_t, a pointer to a string.
|
||||
Returns:
|
||||
0 If no expansions took place (or, if the only change in
|
||||
the text was the removal of escape characters preceding
|
||||
the history expansion character);
|
||||
1 if expansions did take place;
|
||||
-1 if there was an error in expansion;
|
||||
2 if the returned line should be displayed, but not exe-
|
||||
cuted, as with the ::pp modifier.
|
||||
If an error occurred in expansion, then _o_u_t_p_u_t contains a descriptive
|
||||
error message.
|
||||
|
||||
_c_h_a_r _* ggeett__hhiissttoorryy__eevveenntt (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g_, _i_n_t _*_c_i_n_d_e_x_, _i_n_t _q_c_h_a_r)
|
||||
Returns the text of the history event beginning at _s_t_r_i_n_g + _*_c_i_n_d_e_x.
|
||||
_*_c_i_n_d_e_x is modified to point to after the event specifier. At function
|
||||
entry, _c_i_n_d_e_x points to the index into _s_t_r_i_n_g where the history event
|
||||
specification begins. _q_c_h_a_r is a character that is allowed to end the
|
||||
event specification in addition to the ``normal'' terminating charac-
|
||||
ters.
|
||||
|
||||
_c_h_a_r _*_* hhiissttoorryy__ttookkeenniizzee (_c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g)
|
||||
Return an array of tokens parsed out of _s_t_r_i_n_g, much as the shell
|
||||
might. The tokens are split on the characters in the hhiissttoorryy__wwoorrdd__ddee--
|
||||
lliimmiitteerrss variable, and shell quoting conventions are obeyed.
|
||||
|
||||
_c_h_a_r _* hhiissttoorryy__aarrgg__eexxttrraacctt (_i_n_t _f_i_r_s_t_, _i_n_t _l_a_s_t_, _c_o_n_s_t _c_h_a_r _*_s_t_r_i_n_g)
|
||||
Extract a string segment consisting of the _f_i_r_s_t through _l_a_s_t arguments
|
||||
present in _s_t_r_i_n_g. Arguments are split using hhiissttoorryy__ttookkeenniizzee(()).
|
||||
|
||||
HHiissttoorryy VVaarriiaabblleess
|
||||
This section describes the externally-visible variables exported by the
|
||||
GNU History Library.
|
||||
|
||||
_i_n_t hhiissttoorryy__bbaassee
|
||||
The logical offset of the first entry in the history list.
|
||||
|
||||
_i_n_t hhiissttoorryy__lleennggtthh
|
||||
The number of entries currently stored in the history list.
|
||||
|
||||
_i_n_t hhiissttoorryy__mmaaxx__eennttrriieess
|
||||
The maximum number of history entries. This must be changed using ssttii--
|
||||
ffllee__hhiissttoorryy(()).
|
||||
|
||||
_i_n_t hhiissttoorryy__wwrriittee__ttiimmeessttaammppss
|
||||
If non-zero, timestamps are written to the history file, so they can be
|
||||
preserved between sessions. The default value is 0, meaning that time-
|
||||
stamps are not saved. The current timestamp format uses the value of
|
||||
_h_i_s_t_o_r_y___c_o_m_m_e_n_t___c_h_a_r to delimit timestamp entries in the history file.
|
||||
If that variable does not have a value (the default), timestamps will
|
||||
not be written.
|
||||
|
||||
_c_h_a_r hhiissttoorryy__eexxppaannssiioonn__cchhaarr
|
||||
The character that introduces a history event. The default is !!. Set-
|
||||
ting this to 0 inhibits history expansion.
|
||||
|
||||
_c_h_a_r hhiissttoorryy__ssuubbsstt__cchhaarr
|
||||
The character that invokes word substitution if found at the start of a
|
||||
line. The default is ^^.
|
||||
|
||||
_c_h_a_r hhiissttoorryy__ccoommmmeenntt__cchhaarr
|
||||
During tokenization, if this character is seen as the first character
|
||||
of a word, then it and all subsequent characters up to a newline are
|
||||
ignored, suppressing history expansion for the remainder of the line.
|
||||
This is disabled by default.
|
||||
|
||||
_c_h_a_r _* hhiissttoorryy__wwoorrdd__ddeelliimmiitteerrss
|
||||
The characters that separate tokens for hhiissttoorryy__ttookkeenniizzee(()). The de-
|
||||
fault value is "" \\tt\\nn(())<<>>;;&&||"".
|
||||
|
||||
_c_h_a_r _* hhiissttoorryy__nnoo__eexxppaanndd__cchhaarrss
|
||||
The list of characters which inhibit history expansion if found immedi-
|
||||
ately following hhiissttoorryy__eexxppaannssiioonn__cchhaarr. The default is space, tab,
|
||||
newline, \\rr, and ==.
|
||||
|
||||
_c_h_a_r _* hhiissttoorryy__sseeaarrcchh__ddeelliimmiitteerr__cchhaarrss
|
||||
The list of additional characters which can delimit a history search
|
||||
string, in addition to space, tab, _: and _? in the case of a substring
|
||||
search. The default is empty.
|
||||
|
||||
_i_n_t hhiissttoorryy__qquuootteess__iinnhhiibbiitt__eexxppaannssiioonn
|
||||
If non-zero, the history expansion code implements shell-like quoting:
|
||||
single-quoted words are not scanned for the history expansion character
|
||||
or the history comment character, and double-quoted words may have his-
|
||||
tory expansion performed, since single quotes are not special within
|
||||
double quotes. The default value is 0.
|
||||
|
||||
_i_n_t hhiissttoorryy__qquuoottiinngg__ssttaattee
|
||||
An application may set this variable to indicate that the current line
|
||||
being expanded is subject to existing quoting. If set to _', the history
|
||||
expansion function will assume that the line is single-quoted and in-
|
||||
hibit expansion until it reads an unquoted closing single quote; if set
|
||||
to _", history expansion will assume the line is double quoted until it
|
||||
reads an unquoted closing double quote. If set to zero, the default,
|
||||
the history expansion function will assume the line is not quoted and
|
||||
treat quote characters within the line as described above. This is
|
||||
only effective if hhiissttoorryy__qquuootteess__iinnhhiibbiitt__eexxppaannssiioonn is set.
|
||||
|
||||
_r_l___l_i_n_e_b_u_f___f_u_n_c___t _* hhiissttoorryy__iinnhhiibbiitt__eexxppaannssiioonn__ffuunnccttiioonn
|
||||
This should be set to the address of a function that takes two argu-
|
||||
ments: a cchhaarr ** (_s_t_r_i_n_g) and an iinntt index into that string (_i). It
|
||||
should return a non-zero value if the history expansion starting at
|
||||
_s_t_r_i_n_g_[_i_] should not be performed; zero if the expansion should be
|
||||
done. It is intended for use by applications like bbaasshh that use the
|
||||
history expansion character for additional purposes. By default, this
|
||||
variable is set to NNUULLLL.
|
||||
|
||||
FFIILLEESS
|
||||
_~_/_._h_i_s_t_o_r_y
|
||||
Default filename for reading and writing saved history
|
||||
|
||||
SSEEEE AALLSSOO
|
||||
_T_h_e _G_n_u _R_e_a_d_l_i_n_e _L_i_b_r_a_r_y, Brian Fox and Chet Ramey
|
||||
_T_h_e _G_n_u _H_i_s_t_o_r_y _L_i_b_r_a_r_y, Brian Fox and Chet Ramey
|
||||
_b_a_s_h(1)
|
||||
_r_e_a_d_l_i_n_e(3)
|
||||
|
||||
AAUUTTHHOORRSS
|
||||
Brian Fox, Free Software Foundation
|
||||
bfox@gnu.org
|
||||
|
||||
Chet Ramey, Case Western Reserve University
|
||||
chet.ramey@case.edu
|
||||
|
||||
BBUUGG RREEPPOORRTTSS
|
||||
If you find a bug in the hhiissttoorryy library, you should report it. But
|
||||
first, you should make sure that it really is a bug, and that it ap-
|
||||
pears in the latest version of the hhiissttoorryy library that you have.
|
||||
|
||||
Once you have determined that a bug actually exists, mail a bug report
|
||||
to _b_u_g_-_r_e_a_d_l_i_n_e@_g_n_u_._o_r_g. If you have a fix, you are welcome to mail
|
||||
that as well! Suggestions and `philosophical' bug reports may be
|
||||
mailed to _b_u_g_-_r_e_a_d_l_i_n_e@_g_n_u_._o_r_g or posted to the Usenet newsgroup
|
||||
ggnnuu..bbaasshh..bbuugg.
|
||||
|
||||
Comments and bug reports concerning this manual page should be directed
|
||||
to _c_h_e_t_._r_a_m_e_y_@_c_a_s_e_._e_d_u.
|
||||
|
||||
GNU History 8.3 2024 October 10 _H_I_S_T_O_R_Y(3)
|
||||
@@ -79,7 +79,7 @@ history \- GNU History Library
|
||||
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
|
||||
data with each line, and utilize information from previous lines when
|
||||
composing new ones.
|
||||
.PP
|
||||
The History library provides functions that allow applications to their
|
||||
|
||||
@@ -4,15 +4,15 @@
|
||||
@xrdef{History Interaction-snt}{Section@tie 1.1}
|
||||
@xrdef{Event Designators-title}{Event Designators}
|
||||
@xrdef{Event Designators-snt}{Section@tie 1.1.1}
|
||||
@xrdef{Word Designators-title}{Word Designators}
|
||||
@xrdef{Word Designators-snt}{Section@tie 1.1.2}
|
||||
@xrdef{Using History Interactively-pg}{1}
|
||||
@xrdef{History Interaction-pg}{1}
|
||||
@xrdef{Event Designators-pg}{1}
|
||||
@xrdef{Word Designators-title}{Word Designators}
|
||||
@xrdef{Word Designators-snt}{Section@tie 1.1.2}
|
||||
@xrdef{Word Designators-pg}{2}
|
||||
@xrdef{Modifiers-title}{Modifiers}
|
||||
@xrdef{Modifiers-snt}{Section@tie 1.1.3}
|
||||
@xrdef{Word Designators-pg}{2}
|
||||
@xrdef{Modifiers-pg}{2}
|
||||
@xrdef{Modifiers-pg}{3}
|
||||
@xrdef{Programming with GNU History-title}{Programming with GNU History}
|
||||
@xrdef{Programming with GNU History-snt}{Chapter@tie 2}
|
||||
@xrdef{Introduction to History-title}{Introduction to History}
|
||||
@@ -45,19 +45,19 @@
|
||||
@xrdef{Managing the History File-pg}{7}
|
||||
@xrdef{History Expansion-title}{History Expansion}
|
||||
@xrdef{History Expansion-snt}{Section@tie 2.3.7}
|
||||
@xrdef{History Expansion-pg}{8}
|
||||
@xrdef{History Variables-title}{History Variables}
|
||||
@xrdef{History Variables-snt}{Section@tie 2.4}
|
||||
@xrdef{History Expansion-pg}{8}
|
||||
@xrdef{History Variables-pg}{9}
|
||||
@xrdef{History Programming Example-title}{History Programming Example}
|
||||
@xrdef{History Programming Example-snt}{Section@tie 2.5}
|
||||
@xrdef{History Programming Example-pg}{10}
|
||||
@xrdef{GNU Free Documentation License-title}{GNU Free Documentation License}
|
||||
@xrdef{GNU Free Documentation License-snt}{Appendix@tie @char65{}}
|
||||
@xrdef{GNU Free Documentation License-pg}{12}
|
||||
@xrdef{GNU Free Documentation License-pg}{13}
|
||||
@xrdef{Concept Index-title}{Concept Index}
|
||||
@xrdef{Concept Index-snt}{Appendix@tie @char66{}}
|
||||
@xrdef{Concept Index-pg}{20}
|
||||
@xrdef{Concept Index-pg}{21}
|
||||
@xrdef{Function and Variable Index-title}{Function and Variable Index}
|
||||
@xrdef{Function and Variable Index-snt}{Appendix@tie @char67{}}
|
||||
@xrdef{Function and Variable Index-pg}{21}
|
||||
@xrdef{Function and Variable Index-pg}{22}
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
\initial {A}
|
||||
\entry {anchored search}{7}
|
||||
\entry{anchored search}{7}
|
||||
\initial {E}
|
||||
\entry {event designators}{1}
|
||||
\entry{event designators}{1}
|
||||
\initial {H}
|
||||
\entry {history events}{1}
|
||||
\entry {history expansion}{1}
|
||||
\entry {History Searching}{7}
|
||||
\entry{history events}{1}
|
||||
\entry{history expansion}{1}
|
||||
\entry{History Searching}{7}
|
||||
|
||||
Binary file not shown.
@@ -29,5 +29,5 @@
|
||||
\entry{history_truncate_file}{8}{\code {history_truncate_file}}
|
||||
\entry{history_expand}{8}{\code {history_expand}}
|
||||
\entry{get_history_event}{8}{\code {get_history_event}}
|
||||
\entry{history_tokenize}{8}{\code {history_tokenize}}
|
||||
\entry{history_arg_extract}{8}{\code {history_arg_extract}}
|
||||
\entry{history_tokenize}{9}{\code {history_tokenize}}
|
||||
\entry{history_arg_extract}{9}{\code {history_arg_extract}}
|
||||
|
||||
@@ -1,44 +1,44 @@
|
||||
\initial {A}
|
||||
\entry {\code {add_history}}{5}
|
||||
\entry {\code {add_history_time}}{5}
|
||||
\entry {\code {append_history}}{8}
|
||||
\entry{\code {add_history}}{5}
|
||||
\entry{\code {add_history_time}}{5}
|
||||
\entry{\code {append_history}}{8}
|
||||
\initial {C}
|
||||
\entry {\code {clear_history}}{6}
|
||||
\entry {\code {current_history}}{6}
|
||||
\entry{\code {clear_history}}{6}
|
||||
\entry{\code {current_history}}{6}
|
||||
\initial {F}
|
||||
\entry {\code {free_history_entry}}{5}
|
||||
\entry{\code {free_history_entry}}{5}
|
||||
\initial {G}
|
||||
\entry {\code {get_history_event}}{8}
|
||||
\entry{\code {get_history_event}}{8}
|
||||
\initial {H}
|
||||
\entry {\code {history_arg_extract}}{8}
|
||||
\entry {\code {history_expand}}{8}
|
||||
\entry {\code {history_get}}{6}
|
||||
\entry {\code {history_get_history_state}}{5}
|
||||
\entry {\code {history_get_time}}{6}
|
||||
\entry {\code {history_is_stifled}}{6}
|
||||
\entry {\code {history_list}}{6}
|
||||
\entry {\code {history_search}}{7}
|
||||
\entry {\code {history_search_pos}}{7}
|
||||
\entry {\code {history_search_prefix}}{7}
|
||||
\entry {\code {history_set_history_state}}{5}
|
||||
\entry {\code {history_set_pos}}{7}
|
||||
\entry {\code {history_tokenize}}{8}
|
||||
\entry {\code {history_total_bytes}}{6}
|
||||
\entry {\code {history_truncate_file}}{8}
|
||||
\entry{\code {history_arg_extract}}{9}
|
||||
\entry{\code {history_expand}}{8}
|
||||
\entry{\code {history_get}}{6}
|
||||
\entry{\code {history_get_history_state}}{5}
|
||||
\entry{\code {history_get_time}}{6}
|
||||
\entry{\code {history_is_stifled}}{6}
|
||||
\entry{\code {history_list}}{6}
|
||||
\entry{\code {history_search}}{7}
|
||||
\entry{\code {history_search_pos}}{7}
|
||||
\entry{\code {history_search_prefix}}{7}
|
||||
\entry{\code {history_set_history_state}}{5}
|
||||
\entry{\code {history_set_pos}}{7}
|
||||
\entry{\code {history_tokenize}}{9}
|
||||
\entry{\code {history_total_bytes}}{6}
|
||||
\entry{\code {history_truncate_file}}{8}
|
||||
\initial {N}
|
||||
\entry {\code {next_history}}{7}
|
||||
\entry{\code {next_history}}{7}
|
||||
\initial {P}
|
||||
\entry {\code {previous_history}}{7}
|
||||
\entry{\code {previous_history}}{7}
|
||||
\initial {R}
|
||||
\entry {\code {read_history}}{7}
|
||||
\entry {\code {read_history_range}}{8}
|
||||
\entry {\code {remove_history}}{5}
|
||||
\entry {\code {replace_history_entry}}{6}
|
||||
\entry{\code {read_history}}{7}
|
||||
\entry{\code {read_history_range}}{8}
|
||||
\entry{\code {remove_history}}{5}
|
||||
\entry{\code {replace_history_entry}}{6}
|
||||
\initial {S}
|
||||
\entry {\code {stifle_history}}{6}
|
||||
\entry{\code {stifle_history}}{6}
|
||||
\initial {U}
|
||||
\entry {\code {unstifle_history}}{6}
|
||||
\entry {\code {using_history}}{5}
|
||||
\entry{\code {unstifle_history}}{6}
|
||||
\entry{\code {using_history}}{5}
|
||||
\initial {W}
|
||||
\entry {\code {where_history}}{6}
|
||||
\entry {\code {write_history}}{8}
|
||||
\entry{\code {where_history}}{6}
|
||||
\entry{\code {write_history}}{8}
|
||||
|
||||
+276
-149
@@ -1,6 +1,6 @@
|
||||
<HTML>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<!-- Created on January, 2 2018 by texi2html 1.64 -->
|
||||
<!-- Created on October, 12 2024 by texi2html 1.64 -->
|
||||
<!--
|
||||
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
|
||||
Karl Berry <karl@freefriends.org>
|
||||
@@ -65,9 +65,10 @@ typed input.
|
||||
<!--docid::SEC1::-->
|
||||
<P>
|
||||
|
||||
This chapter describes how to use the GNU History Library interactively,
|
||||
from a user's standpoint. It should be considered a user's guide. For
|
||||
information on using the GNU History Library in your own programs,
|
||||
This chapter describes how to use the GNU History Library
|
||||
interactively, from a user's standpoint.
|
||||
It should be considered a user's guide.
|
||||
For information on using the GNU History Library in your own programs,
|
||||
see section <A HREF="history.html#SEC6">2. Programming with GNU History</A>.
|
||||
</P><P>
|
||||
|
||||
@@ -94,9 +95,12 @@ see section <A HREF="history.html#SEC6">2. Programming with GNU History</A>.
|
||||
<!--docid::SEC2::-->
|
||||
<P>
|
||||
|
||||
The History library provides a history expansion feature that is similar
|
||||
to the history expansion provided by <CODE>csh</CODE>. This section
|
||||
describes the syntax used to manipulate the history information.
|
||||
The History library
|
||||
provides a history expansion feature that is similar
|
||||
to the history expansion provided by <CODE>csh</CODE>
|
||||
(also referred to as history substitution where appropriate).
|
||||
This section describes the syntax used to manipulate the
|
||||
history information.
|
||||
</P><P>
|
||||
|
||||
History expansions introduce words from the history list into
|
||||
@@ -105,17 +109,50 @@ arguments to a previous command into the current input line, or
|
||||
fix errors in previous commands quickly.
|
||||
</P><P>
|
||||
|
||||
History expansion takes place in two parts. The first is to determine
|
||||
which line from the history list should be used during substitution.
|
||||
The second is to select portions of that line for inclusion into the
|
||||
current one. The line selected from the history is called the
|
||||
<EM>event</EM>, and the portions of that line that are acted upon are
|
||||
called <EM>words</EM>. Various <EM>modifiers</EM> are available to manipulate
|
||||
the selected words. The line is broken into words in the same fashion
|
||||
that Bash does, so that several words
|
||||
surrounded by quotes are considered one word.
|
||||
History expansion takes place in two parts.
|
||||
The first is to determine
|
||||
which entry from the history list should be used during substitution.
|
||||
The second is to select portions of that entry to include into the
|
||||
current one.
|
||||
</P><P>
|
||||
|
||||
The entry selected from the history is called the <EM>event</EM>,
|
||||
and the portions of that entry that are acted upon are <EM>words</EM>.
|
||||
Various <EM>modifiers</EM> are available to manipulate the selected words.
|
||||
The entry is split into words in the same fashion that Bash
|
||||
does when reading input,
|
||||
so that several words surrounded by quotes are considered one word.
|
||||
The <EM>event designator</EM> selects the event, the optional
|
||||
<EM>word designator</EM> selects words from the event, and
|
||||
various optional <EM>modifiers</EM> are available to manipulate the
|
||||
selected words.
|
||||
</P><P>
|
||||
|
||||
History expansions are introduced by the appearance of the
|
||||
history expansion character, which is <SAMP>`!'</SAMP> by default.
|
||||
History expansions may appear anywhere in the input, but do not nest.
|
||||
</P><P>
|
||||
|
||||
History expansion implements shell-like quoting conventions:
|
||||
a backslash can be used to remove the special handling for the next character;
|
||||
single quotes enclose verbatim sequences of characters, and can be used to
|
||||
inhibit history expansion;
|
||||
and characters enclosed within double quotes may be subject to history
|
||||
expansion, since backslash can escape the history expansion character,
|
||||
but single quotes may not, since they are not treated specially within
|
||||
double quotes.
|
||||
</P><P>
|
||||
|
||||
There is a special abbreviation for substitution, active when the
|
||||
<VAR>quick substitution</VAR> character
|
||||
(default <SAMP>`^'</SAMP>)
|
||||
is the first character on the line.
|
||||
It selects the previous history list entry, using an event designator
|
||||
equivalent to <CODE>!!</CODE>,
|
||||
and substitutes one string for another in that entry.
|
||||
It is described below (see section <A HREF="history.html#SEC3">1.1.1 Event Designators</A>).
|
||||
This is the only history expansion that does not begin with the history
|
||||
expansion character.
|
||||
</P><P>
|
||||
|
||||
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
|
||||
@@ -143,8 +180,10 @@ history expansion character, which is <SAMP>`!'</SAMP> by default.
|
||||
<!--docid::SEC3::-->
|
||||
<P>
|
||||
|
||||
An event designator is a reference to a command line entry in the
|
||||
history list.
|
||||
An event designator is a reference to an entry in the history list.
|
||||
The event designator consists of the portion of the word beginning
|
||||
with the history expansion character, and ending with the word designator
|
||||
if one is present, or the end of the word.
|
||||
Unless the reference is absolute, events are relative to the current
|
||||
position in the history list.
|
||||
<A NAME="IDX1"></A>
|
||||
@@ -158,15 +197,16 @@ the end of the line, or <SAMP>`='</SAMP>.
|
||||
<P>
|
||||
|
||||
<DT><CODE>!<VAR>n</VAR></CODE>
|
||||
<DD>Refer to command line <VAR>n</VAR>.
|
||||
<DD>Refer to history list entry <VAR>n</VAR>.
|
||||
<P>
|
||||
|
||||
<DT><CODE>!-<VAR>n</VAR></CODE>
|
||||
<DD>Refer to the command <VAR>n</VAR> lines back.
|
||||
<DD>Refer to the history entry minus <VAR>n</VAR>.
|
||||
<P>
|
||||
|
||||
<DT><CODE>!!</CODE>
|
||||
<DD>Refer to the previous command. This is a synonym for <SAMP>`!-1'</SAMP>.
|
||||
<DD>Refer to the previous entry.
|
||||
This is a synonym for <SAMP>`!-1'</SAMP>.
|
||||
<P>
|
||||
|
||||
<DT><CODE>!<VAR>string</VAR></CODE>
|
||||
@@ -182,12 +222,15 @@ containing <VAR>string</VAR>.
|
||||
The trailing
|
||||
<SAMP>`?'</SAMP> may be omitted if the <VAR>string</VAR> is followed immediately by
|
||||
a newline.
|
||||
If <VAR>string</VAR> is missing, this uses
|
||||
the string from the most recent search;
|
||||
it is an error if there is no previous search string.
|
||||
<P>
|
||||
|
||||
<DT><CODE>^<VAR>string1</VAR>^<VAR>string2</VAR>^</CODE>
|
||||
<DD>Quick Substitution. Repeat the last command, replacing <VAR>string1</VAR>
|
||||
with <VAR>string2</VAR>. Equivalent to
|
||||
<CODE>!!:s/<VAR>string1</VAR>/<VAR>string2</VAR>/</CODE>.
|
||||
<DD>Quick Substitution.
|
||||
Repeat the last command, replacing <VAR>string1</VAR> with <VAR>string2</VAR>.
|
||||
Equivalent to <CODE>!!:s^<VAR>string1</VAR>^<VAR>string2</VAR>^</CODE>.
|
||||
<P>
|
||||
|
||||
<DT><CODE>!#</CODE>
|
||||
@@ -216,11 +259,14 @@ with <VAR>string2</VAR>. Equivalent to
|
||||
<P>
|
||||
|
||||
Word designators are used to select desired words from the event.
|
||||
A <SAMP>`:'</SAMP> separates the event specification from the word designator. It
|
||||
may be omitted if the word designator begins with a <SAMP>`^'</SAMP>, <SAMP>`$'</SAMP>,
|
||||
<SAMP>`*'</SAMP>, <SAMP>`-'</SAMP>, or <SAMP>`%'</SAMP>. 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.
|
||||
They are optional; if the word designator isn't supplied, the history
|
||||
expansion uses the entire event.
|
||||
A <SAMP>`:'</SAMP> separates the event specification from the word designator.
|
||||
It may be omitted if the word designator begins with a <SAMP>`^'</SAMP>, <SAMP>`$'</SAMP>,
|
||||
<SAMP>`*'</SAMP>, <SAMP>`-'</SAMP>, or <SAMP>`%'</SAMP>.
|
||||
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.
|
||||
</P><P>
|
||||
|
||||
For example,
|
||||
@@ -228,13 +274,13 @@ For example,
|
||||
|
||||
<DL COMPACT>
|
||||
<DT><CODE>!!</CODE>
|
||||
<DD>designates the preceding command. When you type this, the preceding
|
||||
command is repeated in toto.
|
||||
<DD>designates the preceding command.
|
||||
When you type this, the preceding command is repeated in toto.
|
||||
<P>
|
||||
|
||||
<DT><CODE>!!:$</CODE>
|
||||
<DD>designates the last argument of the preceding command. This may be
|
||||
shortened to <CODE>!$</CODE>.
|
||||
<DD>designates the last argument of the preceding command.
|
||||
This may be shortened to <CODE>!$</CODE>.
|
||||
<P>
|
||||
|
||||
<DT><CODE>!fi:2</CODE>
|
||||
@@ -244,11 +290,13 @@ the letters <CODE>fi</CODE>.
|
||||
<P>
|
||||
|
||||
Here are the word designators:
|
||||
|
||||
</P><P>
|
||||
|
||||
<DL COMPACT>
|
||||
|
||||
<DT><CODE>0 (zero)</CODE>
|
||||
<DD>The <CODE>0</CODE>th word. For many applications, this is the command word.
|
||||
<DD>The <CODE>0</CODE>th word.
|
||||
For the shell, and many other, applications, this is the command word.
|
||||
<P>
|
||||
|
||||
<DT><CODE><VAR>n</VAR></CODE>
|
||||
@@ -256,15 +304,21 @@ Here are the word designators:
|
||||
<P>
|
||||
|
||||
<DT><CODE>^</CODE>
|
||||
<DD>The first argument; that is, word 1.
|
||||
<DD>The first argument: word 1.
|
||||
<P>
|
||||
|
||||
<DT><CODE>$</CODE>
|
||||
<DD>The last argument.
|
||||
<DD>The last word.
|
||||
This is usually the last argument, but will expand to the
|
||||
zeroth word if there is only one word in the line.
|
||||
<P>
|
||||
|
||||
<DT><CODE>%</CODE>
|
||||
<DD>The word matched by the most recent <SAMP>`?<VAR>string</VAR>?'</SAMP> search.
|
||||
<DD>The first word matched by the most recent <SAMP>`?<VAR>string</VAR>?'</SAMP> search,
|
||||
if the search string begins with a character that is part of a word.
|
||||
By default, searches begin at the end of each line and proceed to the
|
||||
beginning, so the first word matched is the one closest to the end of
|
||||
the line.
|
||||
<P>
|
||||
|
||||
<DT><CODE><VAR>x</VAR>-<VAR>y</VAR></CODE>
|
||||
@@ -272,24 +326,26 @@ Here are the word designators:
|
||||
<P>
|
||||
|
||||
<DT><CODE>*</CODE>
|
||||
<DD>All of the words, except the <CODE>0</CODE>th. This is a synonym for <SAMP>`1-$'</SAMP>.
|
||||
<DD>All of the words, except the <CODE>0</CODE>th.
|
||||
This is a synonym for <SAMP>`1-$'</SAMP>.
|
||||
It is not an error to use <SAMP>`*'</SAMP> if there is just one word in the event;
|
||||
the empty string is returned in that case.
|
||||
it expands to the empty string in that case.
|
||||
<P>
|
||||
|
||||
<DT><CODE><VAR>x</VAR>*</CODE>
|
||||
<DD>Abbreviates <SAMP>`<VAR>x</VAR>-$'</SAMP>
|
||||
<DD>Abbreviates <SAMP>`<VAR>x</VAR>-$'</SAMP>.
|
||||
<P>
|
||||
|
||||
<DT><CODE><VAR>x</VAR>-</CODE>
|
||||
<DD>Abbreviates <SAMP>`<VAR>x</VAR>-$'</SAMP> like <SAMP>`<VAR>x</VAR>*'</SAMP>, but omits the last word.
|
||||
If <SAMP>`x'</SAMP> is missing, it defaults to 0.
|
||||
<P>
|
||||
|
||||
</DL>
|
||||
<P>
|
||||
|
||||
If a word designator is supplied without an event specification, the
|
||||
previous command is used as the event.
|
||||
previous command is used as the event, equivalent to <CODE>!!</CODE>.
|
||||
</P><P>
|
||||
|
||||
<A NAME="Modifiers"></A>
|
||||
@@ -312,16 +368,17 @@ previous command is used as the event.
|
||||
|
||||
After the optional word designator, you can add a sequence of one or more
|
||||
of the following modifiers, each preceded by a <SAMP>`:'</SAMP>.
|
||||
These modify, or edit, the word or words selected from the history event.
|
||||
</P><P>
|
||||
|
||||
<DL COMPACT>
|
||||
|
||||
<DT><CODE>h</CODE>
|
||||
<DD>Remove a trailing pathname component, leaving only the head.
|
||||
<DD>Remove a trailing filename component, leaving only the head.
|
||||
<P>
|
||||
|
||||
<DT><CODE>t</CODE>
|
||||
<DD>Remove all leading pathname components, leaving the tail.
|
||||
<DD>Remove all leading filename components, leaving the tail.
|
||||
<P>
|
||||
|
||||
<DT><CODE>r</CODE>
|
||||
@@ -339,11 +396,19 @@ the basename.
|
||||
|
||||
<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>.
|
||||
event line.
|
||||
Any character may be used as the delimiter in place of <SAMP>`/'</SAMP>.
|
||||
The delimiter may be quoted in <VAR>old</VAR> and <VAR>new</VAR>
|
||||
with a single backslash. If <SAMP>`&'</SAMP> appears in <VAR>new</VAR>,
|
||||
it is replaced by <VAR>old</VAR>. A single backslash will quote
|
||||
the <SAMP>`&'</SAMP>. The final delimiter is optional if it is the last
|
||||
with a single backslash.
|
||||
If <SAMP>`&'</SAMP> appears in <VAR>new</VAR>, it is replaced with <VAR>old</VAR>.
|
||||
A single backslash will quote the <SAMP>`&'</SAMP> in <VAR>old</VAR> and <VAR>new</VAR>.
|
||||
If <VAR>old</VAR> is null, it is set to the last <VAR>old</VAR>
|
||||
substituted, or, if no previous history substitutions took place,
|
||||
the last <VAR>string</VAR>
|
||||
in a !?<VAR>string</VAR><CODE>[?]</CODE>
|
||||
search.
|
||||
If <VAR>new</VAR> is null, each matching <VAR>old</VAR> is deleted.
|
||||
The final delimiter is optional if it is the last
|
||||
character on the input line.
|
||||
<P>
|
||||
|
||||
@@ -353,13 +418,15 @@ character on the input line.
|
||||
|
||||
<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>,
|
||||
<DD>Cause changes to be applied over the entire event line.
|
||||
This is used in conjunction with
|
||||
<SAMP>`s'</SAMP>, as in <CODE>gs/<VAR>old</VAR>/<VAR>new</VAR>/</CODE>,
|
||||
or with <SAMP>`&'</SAMP>.
|
||||
<P>
|
||||
|
||||
<DT><CODE>G</CODE>
|
||||
<DD>Apply the following <SAMP>`s'</SAMP> modifier once to each word in the event.
|
||||
<DD>Apply the following <SAMP>`s'</SAMP> or <SAMP>`&'</SAMP> modifier once to each word
|
||||
in the event.
|
||||
<P>
|
||||
|
||||
</DL>
|
||||
@@ -386,7 +453,8 @@ or with <SAMP>`&'</SAMP>.
|
||||
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>.
|
||||
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>
|
||||
@@ -416,29 +484,33 @@ For information on the interactive use of GNU History, see section <A HREF="hist
|
||||
<!--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.
|
||||
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 when 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
|
||||
A programmer using the History library can use functions
|
||||
to save commands on a history list,
|
||||
associate arbitrary data with history list entries,
|
||||
remove entries from the list,
|
||||
search through the list for a line containing an arbitrary text string,
|
||||
reference any entry in the list directly,
|
||||
and read and write the history list from and to a file.
|
||||
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
|
||||
Someone 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
|
||||
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
|
||||
The programmer can also use the Readline library, which
|
||||
includes some history manipulation by default, and has the added
|
||||
advantage of command line editing.
|
||||
</P><P>
|
||||
@@ -446,9 +518,10 @@ advantage of command line editing.
|
||||
Before declaring any functions using any functionality the History
|
||||
library provides in other code, an application writer should include
|
||||
the file <CODE><readline/history.h></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.
|
||||
History library's features.
|
||||
It supplies 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>
|
||||
@@ -469,8 +542,8 @@ the public data structures.
|
||||
<!--docid::SEC8::-->
|
||||
<P>
|
||||
|
||||
The history list is an array of history entries. A history entry is
|
||||
declared as follows:
|
||||
The history list is an array of history entries.
|
||||
A history entry is declared as follows:
|
||||
</P><P>
|
||||
|
||||
<TABLE><tr><td> </td><td class=example><pre>typedef void *histdata_t;
|
||||
@@ -504,7 +577,7 @@ typedef struct _hist_state {
|
||||
</pre></td></tr></table></P><P>
|
||||
|
||||
If the flags member includes <CODE>HS_STIFLED</CODE>, the history has been
|
||||
stifled.
|
||||
stifled (limited to a maximum number of entries).
|
||||
</P><P>
|
||||
|
||||
<A NAME="History Functions"></A>
|
||||
@@ -574,8 +647,8 @@ functions in your program.
|
||||
<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.
|
||||
<DD>Begin a session that will use the history functions.
|
||||
This initializes the interactive variables.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -618,11 +691,11 @@ parameters managing the list itself.
|
||||
<A NAME="IDX5"></A>
|
||||
<DL>
|
||||
<DT><U>Function:</U> void <B>add_history</B> <I>(const char *string)</I>
|
||||
<DD>Place <VAR>string</VAR> at the end of the history list. The associated data
|
||||
field (if any) is set to <CODE>NULL</CODE>.
|
||||
<DD>Add <VAR>string</VAR> to the end of the history list, and
|
||||
set the associated data field (if any) to <CODE>NULL</CODE>.
|
||||
If the maximum number of history entries has been set using
|
||||
<CODE>stifle_history()</CODE>, and the new number of history entries would exceed
|
||||
that maximum, the oldest history entry is removed.
|
||||
<CODE>stifle_history()</CODE>, and the new number of history entries
|
||||
would exceed that maximum, this removes the oldest history entry.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -637,9 +710,11 @@ that maximum, the oldest history entry is removed.
|
||||
<A NAME="IDX7"></A>
|
||||
<DL>
|
||||
<DT><U>Function:</U> HIST_ENTRY * <B>remove_history</B> <I>(int which)</I>
|
||||
<DD>Remove history entry at offset <VAR>which</VAR> from the history. The
|
||||
removed element is returned so you can free the line, data,
|
||||
<DD>Remove the history entry at offset <VAR>which</VAR> from the history list.
|
||||
This returns the removed element so you can free the line, data,
|
||||
and containing structure.
|
||||
Since the data is private to your application, the History library
|
||||
doesn't know how to free it, if necessary.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -647,7 +722,8 @@ and containing structure.
|
||||
<DL>
|
||||
<DT><U>Function:</U> histdata_t <B>free_history_entry</B> <I>(HIST_ENTRY *histent)</I>
|
||||
<DD>Free the history entry <VAR>histent</VAR> and any history library private
|
||||
data associated with it. Returns the application-specific data
|
||||
data associated with it.
|
||||
Returns the application-specific data
|
||||
so the caller can dispose of it.
|
||||
</DL>
|
||||
</P><P>
|
||||
@@ -657,8 +733,8 @@ so the caller can dispose of it.
|
||||
<DT><U>Function:</U> HIST_ENTRY * <B>replace_history_entry</B> <I>(int which, const char *line, histdata_t data)</I>
|
||||
<DD>Make the history entry at offset <VAR>which</VAR> have <VAR>line</VAR> and <VAR>data</VAR>.
|
||||
This returns the old entry so the caller can dispose of any
|
||||
application-specific data. In the case
|
||||
of an invalid <VAR>which</VAR>, a <CODE>NULL</CODE> pointer is returned.
|
||||
application-specific data.
|
||||
In the case of an invalid <VAR>which</VAR>, this returns <CODE>NULL</CODE>.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -680,10 +756,10 @@ The history list will contain only <VAR>max</VAR> entries at a time.
|
||||
<A NAME="IDX12"></A>
|
||||
<DL>
|
||||
<DT><U>Function:</U> int <B>unstifle_history</B> <I>(void)</I>
|
||||
<DD>Stop stifling the history. This returns the previously-set
|
||||
maximum number of history entries (as set by <CODE>stifle_history()</CODE>).
|
||||
The value is positive if the history was
|
||||
stifled, negative if it wasn't.
|
||||
<DD>Stop stifling the history.
|
||||
This returns the previously-set maximum number of history
|
||||
entries (as set by <CODE>stifle_history()</CODE>).
|
||||
The value is positive if the history was stifled, negative if it wasn't.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -720,15 +796,16 @@ individual list entries.
|
||||
<DL>
|
||||
<DT><U>Function:</U> HIST_ENTRY ** <B>history_list</B> <I>(void)</I>
|
||||
<DD>Return a <CODE>NULL</CODE> terminated array of <CODE>HIST_ENTRY *</CODE> which is the
|
||||
current input history. Element 0 of this list is the beginning of time.
|
||||
If there is no history, return <CODE>NULL</CODE>.
|
||||
current input history.
|
||||
Element 0 of this list is the beginning of time.
|
||||
Return <CODE>NULL</CODE> if there is no history.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
<A NAME="IDX15"></A>
|
||||
<DL>
|
||||
<DT><U>Function:</U> int <B>where_history</B> <I>(void)</I>
|
||||
<DD>Returns the offset of the current history element.
|
||||
<DD>Return the offset of the current history entry.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -736,8 +813,8 @@ If there is no history, return <CODE>NULL</CODE>.
|
||||
<DL>
|
||||
<DT><U>Function:</U> HIST_ENTRY * <B>current_history</B> <I>(void)</I>
|
||||
<DD>Return the history entry at the current position, as determined by
|
||||
<CODE>where_history()</CODE>. If there is no entry there, return a <CODE>NULL</CODE>
|
||||
pointer.
|
||||
<CODE>where_history()</CODE>.
|
||||
If there is no entry there, return <CODE>NULL</CODE>.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -749,7 +826,7 @@ The range of valid
|
||||
values of <VAR>offset</VAR> starts at <CODE>history_base</CODE> and ends at
|
||||
<VAR>history_length</VAR> - 1 (see section <A HREF="history.html#SEC17">2.4 History Variables</A>).
|
||||
If there is no entry there, or if <VAR>offset</VAR> is outside the valid
|
||||
range, return a <CODE>NULL</CODE> pointer.
|
||||
range, return <CODE>NULL</CODE>.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -806,8 +883,8 @@ than the number of history entries.
|
||||
<DL>
|
||||
<DT><U>Function:</U> HIST_ENTRY * <B>previous_history</B> <I>(void)</I>
|
||||
<DD>Back up the current history offset to the previous history entry, and
|
||||
return a pointer to that entry. If there is no previous entry, return
|
||||
a <CODE>NULL</CODE> pointer.
|
||||
return a pointer to that entry.
|
||||
If there is no previous entry, return <CODE>NULL</CODE>.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -818,7 +895,7 @@ a <CODE>NULL</CODE> pointer.
|
||||
increment the current history offset.
|
||||
If the possibly-incremented history offset refers to a valid history
|
||||
entry, return a pointer to that entry;
|
||||
otherwise, return a <CODE>BNULL</CODE> pointer.
|
||||
otherwise, return <CODE>NULL</CODE>.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -840,10 +917,12 @@ otherwise, return a <CODE>BNULL</CODE> pointer.
|
||||
<!--docid::SEC14::-->
|
||||
<P>
|
||||
|
||||
These functions allow searching of the history list for entries containing
|
||||
a specific string. Searching may be performed both forward and backward
|
||||
from the current history position. The search may be <EM>anchored</EM>,
|
||||
meaning that the string must match at the beginning of the history entry.
|
||||
These functions search the history list for entries containing
|
||||
a specific string.
|
||||
Searching may be performed both forward and backward
|
||||
from the current history position.
|
||||
The search may be <EM>anchored</EM>,
|
||||
meaning that the string must match at the beginning of a history entry.
|
||||
<A NAME="IDX23"></A>
|
||||
</P><P>
|
||||
|
||||
@@ -853,11 +932,11 @@ meaning that the string must match at the beginning of the history entry.
|
||||
<DD>Search the history for <VAR>string</VAR>, starting at the current history offset.
|
||||
If <VAR>direction</VAR> is less than 0, then the search is through
|
||||
previous entries, otherwise through subsequent entries.
|
||||
If <VAR>string</VAR> is found, then
|
||||
the current history index is set to that history entry, and the value
|
||||
returned is the offset in the line of the entry where
|
||||
<VAR>string</VAR> was found. Otherwise, nothing is changed, and a -1 is
|
||||
returned.
|
||||
If <VAR>string</VAR> is found, then the current history index is set to
|
||||
that history entry, and <CODE>history_search</CODE>
|
||||
returns the offset in the line of the entry where
|
||||
<VAR>string</VAR> was found.
|
||||
Otherwise, nothing is changed, and this returns -1.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -865,12 +944,13 @@ returned.
|
||||
<DL>
|
||||
<DT><U>Function:</U> int <B>history_search_prefix</B> <I>(const char *string, int direction)</I>
|
||||
<DD>Search the history for <VAR>string</VAR>, starting at the current history
|
||||
offset. The search is anchored: matching lines must begin with
|
||||
<VAR>string</VAR>. If <VAR>direction</VAR> is less than 0, then the search is
|
||||
offset.
|
||||
The search is anchored: matching history entries must begin with <VAR>string</VAR>.
|
||||
If <VAR>direction</VAR> is less than 0, then the search is
|
||||
through previous entries, otherwise through subsequent entries.
|
||||
If <VAR>string</VAR> is found, then the
|
||||
current history index is set to that entry, and the return value is 0.
|
||||
Otherwise, nothing is changed, and a -1 is returned.
|
||||
If <VAR>string</VAR> is found, then the current history index is set to
|
||||
that entry, and the return value is 0.
|
||||
Otherwise, nothing is changed, and this returns -1.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -878,9 +958,12 @@ Otherwise, nothing is changed, and a -1 is returned.
|
||||
<DL>
|
||||
<DT><U>Function:</U> int <B>history_search_pos</B> <I>(const char *string, int direction, int pos)</I>
|
||||
<DD>Search for <VAR>string</VAR> in the history list, starting at <VAR>pos</VAR>, an
|
||||
absolute index into the list. If <VAR>direction</VAR> is negative, the search
|
||||
proceeds backward from <VAR>pos</VAR>, otherwise forward. Returns the absolute
|
||||
index of the history element where <VAR>string</VAR> was found, or -1 otherwise.
|
||||
absolute index into the list.
|
||||
If <VAR>direction</VAR> is negative, the search
|
||||
proceeds backward from <VAR>pos</VAR>, otherwise forward.
|
||||
Returns the index in the history list
|
||||
of the history element where <VAR>string</VAR> was
|
||||
found, or -1 otherwise.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -909,8 +992,13 @@ This section documents the functions for managing a history file.
|
||||
<A NAME="IDX27"></A>
|
||||
<DL>
|
||||
<DT><U>Function:</U> int <B>read_history</B> <I>(const char *filename)</I>
|
||||
<DD>Add the contents of <VAR>filename</VAR> to the history list, a line at a time.
|
||||
If <VAR>filename</VAR> is <CODE>NULL</CODE>, then read from <TT>`~/.history'</TT>.
|
||||
<DD>Add the contents of <VAR>filename</VAR> to the history list, one entry
|
||||
at a time.
|
||||
If <VAR>filename</VAR> is <CODE>NULL</CODE>, this reads from <TT>`~/.history'</TT>,
|
||||
if it exists.
|
||||
This attempts to determine whether the history file includes timestamp
|
||||
information, and assigns timestamps to the history entries it reads
|
||||
if so.
|
||||
Returns 0 if successful, or <CODE>errno</CODE> if not.
|
||||
</DL>
|
||||
</P><P>
|
||||
@@ -920,10 +1008,14 @@ Returns 0 if successful, or <CODE>errno</CODE> if not.
|
||||
<DT><U>Function:</U> int <B>read_history_range</B> <I>(const char *filename, int from, int to)</I>
|
||||
<DD>Read a range of lines from <VAR>filename</VAR>, adding them to the history list.
|
||||
Start reading at line <VAR>from</VAR> and end at <VAR>to</VAR>.
|
||||
If <VAR>from</VAR> is zero, start at the beginning. If <VAR>to</VAR> is less than
|
||||
<VAR>from</VAR>, then read until the end of the file. If <VAR>filename</VAR> is
|
||||
<CODE>NULL</CODE>, then read from <TT>`~/.history'</TT>. Returns 0 if successful,
|
||||
or <CODE>errno</CODE> if not.
|
||||
If <VAR>from</VAR> is zero, start at the beginning.
|
||||
If <VAR>to</VAR> is less than <VAR>from</VAR>, this reads until the end of the file.
|
||||
This attempts to determine whether the history file includes timestamp
|
||||
information, and assigns timestamps to the history entries it reads
|
||||
if so.
|
||||
If <VAR>filename</VAR> is <CODE>NULL</CODE>, this reads from <TT>`~/.history'</TT>,
|
||||
if it exists.
|
||||
Returns 0 if successful, or <CODE>errno</CODE> if not.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -932,6 +1024,8 @@ or <CODE>errno</CODE> if not.
|
||||
<DT><U>Function:</U> int <B>write_history</B> <I>(const char *filename)</I>
|
||||
<DD>Write the current history to <VAR>filename</VAR>, overwriting <VAR>filename</VAR>
|
||||
if necessary.
|
||||
This writes timestamp information if the
|
||||
<CODE>history_write_timestamps</CODE> variable is set to a non-zero value.
|
||||
If <VAR>filename</VAR> is <CODE>NULL</CODE>, then write the history list to
|
||||
<TT>`~/.history'</TT>.
|
||||
Returns 0 on success, or <CODE>errno</CODE> on a read or write error.
|
||||
@@ -942,6 +1036,8 @@ Returns 0 on success, or <CODE>errno</CODE> on a read or write error.
|
||||
<DL>
|
||||
<DT><U>Function:</U> int <B>append_history</B> <I>(int nelements, const char *filename)</I>
|
||||
<DD>Append the last <VAR>nelements</VAR> of the history list to <VAR>filename</VAR>.
|
||||
This writes timestamp information if the
|
||||
<CODE>history_write_timestamps</CODE> variable is set to a non-zero value.
|
||||
If <VAR>filename</VAR> is <CODE>NULL</CODE>, then append to <TT>`~/.history'</TT>.
|
||||
Returns 0 on success, or <CODE>errno</CODE> on a read or write error.
|
||||
</DL>
|
||||
@@ -952,7 +1048,7 @@ Returns 0 on success, or <CODE>errno</CODE> on a read or write error.
|
||||
<DT><U>Function:</U> int <B>history_truncate_file</B> <I>(const char *filename, int nlines)</I>
|
||||
<DD>Truncate the history file <VAR>filename</VAR>, leaving only the last
|
||||
<VAR>nlines</VAR> lines.
|
||||
If <VAR>filename</VAR> is <CODE>NULL</CODE>, then <TT>`~/.history'</TT> is truncated.
|
||||
If <VAR>filename</VAR> is <CODE>NULL</CODE>, this truncates <TT>`~/.history'</TT>.
|
||||
Returns 0 on success, or <CODE>errno</CODE> on failure.
|
||||
</DL>
|
||||
</P><P>
|
||||
@@ -980,9 +1076,10 @@ These functions implement history expansion.
|
||||
|
||||
<A NAME="IDX32"></A>
|
||||
<DL>
|
||||
<DT><U>Function:</U> int <B>history_expand</B> <I>(char *string, char **output)</I>
|
||||
<DT><U>Function:</U> int <B>history_expand</B> <I>(const char *string, char **output)</I>
|
||||
<DD>Expand <VAR>string</VAR>, placing the result into <VAR>output</VAR>, a pointer
|
||||
to a string (see section <A HREF="history.html#SEC2">1.1 History Expansion</A>). Returns:
|
||||
to a string (see section <A HREF="history.html#SEC2">1.1 History Expansion</A>).
|
||||
Returns:
|
||||
<DL COMPACT>
|
||||
<DT><CODE>0</CODE>
|
||||
<DD>If no expansions took place (or, if the only change in
|
||||
@@ -998,8 +1095,8 @@ as with the <CODE>:p</CODE> modifier (see section <A HREF="history.html#SEC5">1.
|
||||
</DL>
|
||||
<P>
|
||||
|
||||
If an error occurred in expansion, then <VAR>output</VAR> contains a descriptive
|
||||
error message.
|
||||
If an error occurred during expansion,
|
||||
then <VAR>output</VAR> contains a descriptive error message.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -1007,9 +1104,11 @@ error message.
|
||||
<DL>
|
||||
<DT><U>Function:</U> char * <B>get_history_event</B> <I>(const char *string, int *cindex, int qchar)</I>
|
||||
<DD>Returns the text of the history event beginning at <VAR>string</VAR> +
|
||||
<VAR>*cindex</VAR>. <VAR>*cindex</VAR> is modified to point to after the event
|
||||
specifier. At function entry, <VAR>cindex</VAR> points to the index into
|
||||
<VAR>string</VAR> where the history event specification begins. <VAR>qchar</VAR>
|
||||
<VAR>*cindex</VAR>.
|
||||
Modifies <VAR>*cindex</VAR> to point to after the event specifier.
|
||||
At function entry, <VAR>cindex</VAR> points to the index into <VAR>string</VAR>
|
||||
where the history event specification begins.
|
||||
<VAR>qchar</VAR>
|
||||
is a character that is allowed to end the event specification in addition
|
||||
to the "normal" terminating characters.
|
||||
</DL>
|
||||
@@ -1019,9 +1118,10 @@ to the "normal" terminating characters.
|
||||
<DL>
|
||||
<DT><U>Function:</U> char ** <B>history_tokenize</B> <I>(const char *string)</I>
|
||||
<DD>Return an array of tokens parsed out of <VAR>string</VAR>, much as the
|
||||
shell might. The tokens are split on the characters in the
|
||||
shell might.
|
||||
The tokens are split on the characters in the
|
||||
<VAR>history_word_delimiters</VAR> variable,
|
||||
and shell quoting conventions are obeyed.
|
||||
and shell quoting conventions are obeyed as described below.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -1029,8 +1129,8 @@ and shell quoting conventions are obeyed.
|
||||
<DL>
|
||||
<DT><U>Function:</U> char * <B>history_arg_extract</B> <I>(int first, int last, const char *string)</I>
|
||||
<DD>Extract a string segment consisting of the <VAR>first</VAR> through <VAR>last</VAR>
|
||||
arguments present in <VAR>string</VAR>. Arguments are split using
|
||||
<CODE>history_tokenize</CODE>.
|
||||
arguments present in <VAR>string</VAR>.
|
||||
This splits <VAR>string</VAR> into arguments using <CODE>history_tokenize</CODE>.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -1073,8 +1173,8 @@ the GNU History Library.
|
||||
<A NAME="IDX38"></A>
|
||||
<DL>
|
||||
<DT><U>Variable:</U> int <B>history_max_entries</B>
|
||||
<DD>The maximum number of history entries. This must be changed using
|
||||
<CODE>stifle_history()</CODE>.
|
||||
<DD>The maximum number of history entries.
|
||||
This must be changed using <CODE>stifle_history()</CODE>.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -1082,20 +1182,22 @@ the GNU History Library.
|
||||
<DL>
|
||||
<DT><U>Variable:</U> int <B>history_write_timestamps</B>
|
||||
<DD>If non-zero, timestamps are written to the history file, so they can be
|
||||
preserved between sessions. The default value is 0, meaning that
|
||||
timestamps are not saved.
|
||||
preserved between sessions.
|
||||
The default value is 0, meaning that timestamps are not saved.
|
||||
</P><P>
|
||||
|
||||
The current timestamp format uses the value of <VAR>history_comment_char</VAR>
|
||||
to delimit timestamp entries in the history file. If that variable does
|
||||
not have a value (the default), timestamps will not be written.
|
||||
to delimit timestamp entries in the history file.
|
||||
If that variable does not have a value (the default), this will not
|
||||
write timestamps.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
<A NAME="IDX40"></A>
|
||||
<DL>
|
||||
<DT><U>Variable:</U> char <B>history_expansion_char</B>
|
||||
<DD>The character that introduces a history event. The default is <SAMP>`!'</SAMP>.
|
||||
<DD>The character that introduces a history event.
|
||||
The default is <SAMP>`!'</SAMP>.
|
||||
Setting this to 0 inhibits history expansion.
|
||||
</DL>
|
||||
</P><P>
|
||||
@@ -1104,14 +1206,15 @@ Setting this to 0 inhibits history expansion.
|
||||
<DL>
|
||||
<DT><U>Variable:</U> char <B>history_subst_char</B>
|
||||
<DD>The character that invokes word substitution if found at the start of
|
||||
a line. The default is <SAMP>`^'</SAMP>.
|
||||
a line.
|
||||
The default is <SAMP>`^'</SAMP>.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
<A NAME="IDX42"></A>
|
||||
<DL>
|
||||
<DT><U>Variable:</U> char <B>history_comment_char</B>
|
||||
<DD>During tokenization, if this character is seen as the first character
|
||||
<DD>During tokenization, if this character appears as the first character
|
||||
of a word, then it and all subsequent characters up to a newline are
|
||||
ignored, suppressing history expansion for the remainder of the line.
|
||||
This is disabled by default.
|
||||
@@ -1131,7 +1234,8 @@ The default value is <CODE>" \t\n()<>;&|"</CODE>.
|
||||
<DT><U>Variable:</U> char * <B>history_search_delimiter_chars</B>
|
||||
<DD>The list of additional characters which can delimit a history search
|
||||
string, in addition to space, TAB, <SAMP>`:'</SAMP> and <SAMP>`?'</SAMP> in the case of
|
||||
a substring search. The default is empty.
|
||||
a substring search.
|
||||
The default is empty.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
@@ -1139,21 +1243,44 @@ a substring search. The default is empty.
|
||||
<DL>
|
||||
<DT><U>Variable:</U> char * <B>history_no_expand_chars</B>
|
||||
<DD>The list of characters which inhibit history expansion if found immediately
|
||||
following <VAR>history_expansion_char</VAR>. The default is space, tab, newline,
|
||||
carriage return, and <SAMP>`='</SAMP>.
|
||||
following <VAR>history_expansion_char</VAR>.
|
||||
The default is space, tab, newline, carriage return, and <SAMP>`='</SAMP>.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
<A NAME="IDX46"></A>
|
||||
<DL>
|
||||
<DT><U>Variable:</U> int <B>history_quotes_inhibit_expansion</B>
|
||||
<DD>If non-zero, double-quoted words are not scanned for the history expansion
|
||||
character or the history comment character. The default value is 0.
|
||||
<DD>If non-zero, the history expansion code implements shell-like quoting:
|
||||
single-quoted words are not scanned for the history expansion
|
||||
character or the history comment character, and double-quoted words may
|
||||
have history expansion performed, since single quotes are not special
|
||||
within double quotes.
|
||||
The default value is 0.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
<A NAME="IDX47"></A>
|
||||
<DL>
|
||||
<DT><U>Variable:</U> int <B>history_quoting_state</B>
|
||||
<DD>An application may set this variable to indicate that the current line
|
||||
being expanded is subject to existing quoting.
|
||||
If set to <SAMP>`''</SAMP>, the
|
||||
history expansion function will assume that the line is single-quoted and
|
||||
inhibit expansion until it reads an unquoted closing single quote;
|
||||
if set to <SAMP>`"'</SAMP>, history expansion will assume the line is
|
||||
double quoted until it reads an unquoted closing double quote.
|
||||
If set to 0, the default,
|
||||
the history expansion function will assume the line is not quoted and
|
||||
treat quote characters within the line as described above.
|
||||
This is only effective if <VAR>history_quotes_inhibit_expansion</VAR> is set.
|
||||
This is intended for use by applications like Bash which allow
|
||||
quoted strings to span multiple lines.
|
||||
</DL>
|
||||
</P><P>
|
||||
|
||||
<A NAME="IDX48"></A>
|
||||
<DL>
|
||||
<DT><U>Variable:</U> rl_linebuf_func_t * <B>history_inhibit_expansion_function</B>
|
||||
<DD>This should be set to the address of a function that takes two arguments:
|
||||
a <CODE>char *</CODE> (<VAR>string</VAR>)
|
||||
@@ -1191,9 +1318,8 @@ The following program demonstrates simple use of the GNU History Library.
|
||||
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>#include <stdio.h>
|
||||
#include <readline/history.h>
|
||||
|
||||
main (argc, argv)
|
||||
int argc;
|
||||
char **argv;
|
||||
int
|
||||
main (int argc, char **argv)
|
||||
{
|
||||
char line[1024], *t;
|
||||
int len, done = 0;
|
||||
@@ -1977,13 +2103,14 @@ to permit their use in free software.
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX17"><CODE>history_get</CODE></A></TD><TD valign=top><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX3"><CODE>history_get_history_state</CODE></A></TD><TD valign=top><A HREF="history.html#SEC10">2.3.1 Initializing History and State Management</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX18"><CODE>history_get_time</CODE></A></TD><TD valign=top><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX47"><CODE>history_inhibit_expansion_function</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX48"><CODE>history_inhibit_expansion_function</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX13"><CODE>history_is_stifled</CODE></A></TD><TD valign=top><A HREF="history.html#SEC11">2.3.2 History List Management</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX37"><CODE>history_length</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX14"><CODE>history_list</CODE></A></TD><TD valign=top><A HREF="history.html#SEC12">2.3.3 Information About the History List</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX38"><CODE>history_max_entries</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX45"><CODE>history_no_expand_chars</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX46"><CODE>history_quotes_inhibit_expansion</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX47"><CODE>history_quoting_state</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX24"><CODE>history_search</CODE></A></TD><TD valign=top><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX44"><CODE>history_search_delimiter_chars</CODE></A></TD><TD valign=top><A HREF="history.html#SEC17">2.4 History Variables</A></TD></TR>
|
||||
<TR><TD></TD><TD valign=top><A HREF="history.html#IDX26"><CODE>history_search_pos</CODE></A></TD><TD valign=top><A HREF="history.html#SEC14">2.3.5 Searching the History List</A></TD></TR>
|
||||
@@ -2136,7 +2263,7 @@ to permit their use in free software.
|
||||
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="history.html#SEC_About"> ? </A>]</TD>
|
||||
</TR></TABLE>
|
||||
<H1>About this document</H1>
|
||||
This document was generated by <I>Chet Ramey</I> on <I>January, 2 2018</I>
|
||||
This document was generated by <I>Chet Ramey</I> on <I>October, 12 2024</I>
|
||||
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
|
||||
"><I>texi2html</I></A>
|
||||
<P></P>
|
||||
@@ -2298,7 +2425,7 @@ the following structure:
|
||||
<BR>
|
||||
<FONT SIZE="-1">
|
||||
This document was generated
|
||||
by <I>Chet Ramey</I> on <I>January, 2 2018</I>
|
||||
by <I>Chet Ramey</I> on <I>October, 12 2024</I>
|
||||
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
|
||||
"><I>texi2html</I></A>
|
||||
|
||||
|
||||
+305
-232
@@ -1,11 +1,11 @@
|
||||
This is history.info, produced by makeinfo version 6.5 from
|
||||
This is history.info, produced by makeinfo version 7.1 from
|
||||
history.texi.
|
||||
|
||||
This document describes the GNU History library (version 7.0, 28
|
||||
December 2017), a programming tool that provides a consistent user
|
||||
interface for recalling lines of previously typed input.
|
||||
This document describes the GNU History library (version 8.3, 10 October
|
||||
2024), a programming tool that provides a consistent user interface for
|
||||
recalling lines of previously typed input.
|
||||
|
||||
Copyright (C) 1988-2016 Free Software Foundation, Inc.
|
||||
Copyright © 1988-2024 Free Software Foundation, Inc.
|
||||
|
||||
Permission is granted to copy, distribute and/or modify this
|
||||
document under the terms of the GNU Free Documentation License,
|
||||
@@ -60,8 +60,9 @@ File: history.info, Node: History Interaction, Up: Using History Interactively
|
||||
=====================
|
||||
|
||||
The History library provides a history expansion feature that is similar
|
||||
to the history expansion provided by 'csh'. This section describes the
|
||||
syntax used to manipulate the history information.
|
||||
to the history expansion provided by ‘csh’ (also referred to as history
|
||||
substitution where appropriate). This section describes the syntax used
|
||||
to manipulate the history information.
|
||||
|
||||
History expansions introduce words from the history list into the
|
||||
input stream, making it easy to repeat commands, insert the arguments to
|
||||
@@ -69,15 +70,38 @@ a previous command into the current input line, or fix errors in
|
||||
previous commands quickly.
|
||||
|
||||
History expansion takes place in two parts. The first is to
|
||||
determine which line from the history list should be used during
|
||||
substitution. The second is to select portions of that line for
|
||||
inclusion into the current one. The line selected from the history is
|
||||
called the "event", and the portions of that line that are acted upon
|
||||
are called "words". Various "modifiers" are available to manipulate the
|
||||
selected words. The line is broken into words in the same fashion that
|
||||
Bash does, so that several words surrounded by quotes are considered one
|
||||
word. History expansions are introduced by the appearance of the
|
||||
history expansion character, which is '!' by default.
|
||||
determine which entry from the history list should be used during
|
||||
substitution. The second is to select portions of that entry to include
|
||||
into the current one.
|
||||
|
||||
The entry selected from the history is called the “event”, and the
|
||||
portions of that entry that are acted upon are “words”. Various
|
||||
“modifiers” are available to manipulate the selected words. The entry
|
||||
is split into words in the same fashion that Bash does when reading
|
||||
input, so that several words surrounded by quotes are considered one
|
||||
word. The “event designator” selects the event, the optional “word
|
||||
designator” selects words from the event, and various optional
|
||||
“modifiers” are available to manipulate the selected words.
|
||||
|
||||
History expansions are introduced by the appearance of the history
|
||||
expansion character, which is ‘!’ by default. History expansions may
|
||||
appear anywhere in the input, but do not nest.
|
||||
|
||||
History expansion implements shell-like quoting conventions: a
|
||||
backslash can be used to remove the special handling for the next
|
||||
character; single quotes enclose verbatim sequences of characters, and
|
||||
can be used to inhibit history expansion; and characters enclosed within
|
||||
double quotes may be subject to history expansion, since backslash can
|
||||
escape the history expansion character, but single quotes may not, since
|
||||
they are not treated specially within double quotes.
|
||||
|
||||
There is a special abbreviation for substitution, active when the
|
||||
QUICK SUBSTITUTION character (default ‘^’) is the first character on the
|
||||
line. It selects the previous history list entry, using an event
|
||||
designator equivalent to ‘!!’, and substitutes one string for another in
|
||||
that entry. It is described below (*note Event Designators::). This is
|
||||
the only history expansion that does not begin with the history
|
||||
expansion character.
|
||||
|
||||
* Menu:
|
||||
|
||||
@@ -91,37 +115,41 @@ File: history.info, Node: Event Designators, Next: Word Designators, Up: Hist
|
||||
1.1.1 Event Designators
|
||||
-----------------------
|
||||
|
||||
An event designator is a reference to a command line entry in the
|
||||
history list. Unless the reference is absolute, events are relative to
|
||||
the current position in the history list.
|
||||
An event designator is a reference to an entry in the history list. The
|
||||
event designator consists of the portion of the word beginning with the
|
||||
history expansion character, and ending with the word designator if one
|
||||
is present, or the end of the word. Unless the reference is absolute,
|
||||
events are relative to the current position in the history list.
|
||||
|
||||
'!'
|
||||
‘!’
|
||||
Start a history substitution, except when followed by a space, tab,
|
||||
the end of the line, or '='.
|
||||
the end of the line, or ‘=’.
|
||||
|
||||
'!N'
|
||||
Refer to command line N.
|
||||
‘!N’
|
||||
Refer to history list entry N.
|
||||
|
||||
'!-N'
|
||||
Refer to the command N lines back.
|
||||
‘!-N’
|
||||
Refer to the history entry minus N.
|
||||
|
||||
'!!'
|
||||
Refer to the previous command. This is a synonym for '!-1'.
|
||||
‘!!’
|
||||
Refer to the previous entry. This is a synonym for ‘!-1’.
|
||||
|
||||
'!STRING'
|
||||
‘!STRING’
|
||||
Refer to the most recent command preceding the current position in
|
||||
the history list starting with STRING.
|
||||
|
||||
'!?STRING[?]'
|
||||
‘!?STRING[?]’
|
||||
Refer to the most recent command preceding the current position in
|
||||
the history list containing STRING. The trailing '?' may be
|
||||
omitted if the STRING is followed immediately by a newline.
|
||||
the history list containing STRING. The trailing ‘?’ may be
|
||||
omitted if the STRING is followed immediately by a newline. If
|
||||
STRING is missing, this uses the string from the most recent
|
||||
search; it is an error if there is no previous search string.
|
||||
|
||||
'^STRING1^STRING2^'
|
||||
‘^STRING1^STRING2^’
|
||||
Quick Substitution. Repeat the last command, replacing STRING1
|
||||
with STRING2. Equivalent to '!!:s/STRING1/STRING2/'.
|
||||
with STRING2. Equivalent to ‘!!:s^STRING1^STRING2^’.
|
||||
|
||||
'!#'
|
||||
‘!#’
|
||||
The entire command line typed so far.
|
||||
|
||||
|
||||
@@ -130,60 +158,69 @@ File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Desi
|
||||
1.1.2 Word Designators
|
||||
----------------------
|
||||
|
||||
Word designators are used to select desired words from the event. A ':'
|
||||
separates the event specification from the word designator. It may be
|
||||
omitted if the word designator begins with a '^', '$', '*', '-', or '%'.
|
||||
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.
|
||||
Word designators are used to select desired words from the event. They
|
||||
are optional; if the word designator isn't supplied, the history
|
||||
expansion uses the entire event. A ‘:’ separates the event
|
||||
specification from the word designator. It may be omitted if the word
|
||||
designator begins with a ‘^’, ‘$’, ‘*’, ‘-’, or ‘%’. 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.
|
||||
|
||||
For example,
|
||||
|
||||
'!!'
|
||||
‘!!’
|
||||
designates the preceding command. When you type this, the
|
||||
preceding command is repeated in toto.
|
||||
|
||||
'!!:$'
|
||||
‘!!:$’
|
||||
designates the last argument of the preceding command. This may be
|
||||
shortened to '!$'.
|
||||
shortened to ‘!$’.
|
||||
|
||||
'!fi:2'
|
||||
‘!fi:2’
|
||||
designates the second argument of the most recent command starting
|
||||
with the letters 'fi'.
|
||||
with the letters ‘fi’.
|
||||
|
||||
Here are the word designators:
|
||||
|
||||
'0 (zero)'
|
||||
The '0'th word. For many applications, this is the command word.
|
||||
‘0 (zero)’
|
||||
The ‘0’th word. For the shell, and many other, applications, this
|
||||
is the command word.
|
||||
|
||||
'N'
|
||||
‘N’
|
||||
The Nth word.
|
||||
|
||||
'^'
|
||||
The first argument; that is, word 1.
|
||||
‘^’
|
||||
The first argument: word 1.
|
||||
|
||||
'$'
|
||||
The last argument.
|
||||
‘$’
|
||||
The last word. This is usually the last argument, but will expand
|
||||
to the zeroth word if there is only one word in the line.
|
||||
|
||||
'%'
|
||||
The word matched by the most recent '?STRING?' search.
|
||||
‘%’
|
||||
The first word matched by the most recent ‘?STRING?’ search, if the
|
||||
search string begins with a character that is part of a word. By
|
||||
default, searches begin at the end of each line and proceed to the
|
||||
beginning, so the first word matched is the one closest to the end
|
||||
of the line.
|
||||
|
||||
'X-Y'
|
||||
A range of words; '-Y' abbreviates '0-Y'.
|
||||
‘X-Y’
|
||||
A range of words; ‘-Y’ abbreviates ‘0-Y’.
|
||||
|
||||
'*'
|
||||
All of the words, except the '0'th. This is a synonym for '1-$'.
|
||||
It is not an error to use '*' if there is just one word in the
|
||||
event; the empty string is returned in that case.
|
||||
‘*’
|
||||
All of the words, except the ‘0’th. This is a synonym for ‘1-$’.
|
||||
It is not an error to use ‘*’ if there is just one word in the
|
||||
event; it expands to the empty string in that case.
|
||||
|
||||
'X*'
|
||||
Abbreviates 'X-$'
|
||||
‘X*’
|
||||
Abbreviates ‘X-$’.
|
||||
|
||||
'X-'
|
||||
Abbreviates 'X-$' like 'X*', but omits the last word.
|
||||
‘X-’
|
||||
Abbreviates ‘X-$’ like ‘X*’, but omits the last word. If ‘x’ is
|
||||
missing, it defaults to 0.
|
||||
|
||||
If a word designator is supplied without an event specification, the
|
||||
previous command is used as the event.
|
||||
previous command is used as the event, equivalent to ‘!!’.
|
||||
|
||||
|
||||
File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
|
||||
@@ -192,42 +229,47 @@ File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Inte
|
||||
---------------
|
||||
|
||||
After the optional word designator, you can add a sequence of one or
|
||||
more of the following modifiers, each preceded by a ':'.
|
||||
more of the following modifiers, each preceded by a ‘:’. These modify,
|
||||
or edit, the word or words selected from the history event.
|
||||
|
||||
'h'
|
||||
Remove a trailing pathname component, leaving only the head.
|
||||
‘h’
|
||||
Remove a trailing filename component, leaving only the head.
|
||||
|
||||
't'
|
||||
Remove all leading pathname components, leaving the tail.
|
||||
‘t’
|
||||
Remove all leading filename components, leaving the tail.
|
||||
|
||||
'r'
|
||||
Remove a trailing suffix of the form '.SUFFIX', leaving the
|
||||
‘r’
|
||||
Remove a trailing suffix of the form ‘.SUFFIX’, leaving the
|
||||
basename.
|
||||
|
||||
'e'
|
||||
‘e’
|
||||
Remove all but the trailing suffix.
|
||||
|
||||
'p'
|
||||
‘p’
|
||||
Print the new command but do not execute it.
|
||||
|
||||
's/OLD/NEW/'
|
||||
‘s/OLD/NEW/’
|
||||
Substitute NEW for the first occurrence of OLD in the event line.
|
||||
Any delimiter may be used in place of '/'. The delimiter may be
|
||||
quoted in OLD and NEW with a single backslash. If '&' appears in
|
||||
NEW, it is replaced by OLD. A single backslash will quote the '&'.
|
||||
The final delimiter is optional if it is the last character on the
|
||||
input line.
|
||||
Any character may be used as the delimiter in place of ‘/’. The
|
||||
delimiter may be quoted in OLD and NEW with a single backslash. If
|
||||
‘&’ appears in NEW, it is replaced with OLD. A single backslash
|
||||
will quote the ‘&’ in OLD and NEW. If OLD is null, it is set to
|
||||
the last OLD substituted, or, if no previous history substitutions
|
||||
took place, the last STRING in a !?STRING‘[?]’ search. If NEW is
|
||||
null, each matching OLD is deleted. The final delimiter is
|
||||
optional if it is the last character on the input line.
|
||||
|
||||
'&'
|
||||
‘&’
|
||||
Repeat the previous substitution.
|
||||
|
||||
'g'
|
||||
'a'
|
||||
Cause changes to be applied over the entire event line. Used in
|
||||
conjunction with 's', as in 'gs/OLD/NEW/', or with '&'.
|
||||
‘g’
|
||||
‘a’
|
||||
Cause changes to be applied over the entire event line. This is
|
||||
used in conjunction with ‘s’, as in ‘gs/OLD/NEW/’, or with ‘&’.
|
||||
|
||||
'G'
|
||||
Apply the following 's' modifier once to each word in the event.
|
||||
‘G’
|
||||
Apply the following ‘s’ or ‘&’ modifier once to each word in the
|
||||
event.
|
||||
|
||||
|
||||
File: history.info, Node: Programming with GNU History, Next: GNU Free Documentation License, Prev: Using History Interactively, Up: Top
|
||||
@@ -257,32 +299,31 @@ File: history.info, Node: Introduction to History, Next: History Storage, Up:
|
||||
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.
|
||||
lines when composing new ones.
|
||||
|
||||
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 "expansion" function is
|
||||
available which provides for a consistent user interface across
|
||||
different programs.
|
||||
A programmer using the History library can use functions to save
|
||||
commands on a history list, associate arbitrary data with history list
|
||||
entries, remove entries from the list, search through the list for a
|
||||
line containing an arbitrary text string, reference any entry in the
|
||||
list directly, and read and write the history list from and to a file.
|
||||
In addition, a history “expansion” function is available which provides
|
||||
for a consistent user interface across different programs.
|
||||
|
||||
The user using programs written with the History library has the
|
||||
Someone 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 'csh'.
|
||||
history substitution provided by ‘csh’.
|
||||
|
||||
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.
|
||||
The programmer can also use the Readline library, which includes some
|
||||
history manipulation by default, and has the added advantage of command
|
||||
line editing.
|
||||
|
||||
Before declaring any functions using any functionality the History
|
||||
library provides in other code, an application writer should include the
|
||||
file '<readline/history.h>' 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.
|
||||
file ‘<readline/history.h>’ in any file that uses the History library's
|
||||
features. It supplies declarations for all of the library's public
|
||||
functions and variables, and declares all of the public data structures.
|
||||
|
||||
|
||||
File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History
|
||||
@@ -319,8 +360,8 @@ structure:
|
||||
int flags;
|
||||
} HISTORY_STATE;
|
||||
|
||||
If the flags member includes 'HS_STIFLED', the history has been
|
||||
stifled.
|
||||
If the flags member includes ‘HS_STIFLED’, the history has been
|
||||
stifled (limited to a maximum number of entries).
|
||||
|
||||
|
||||
File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History
|
||||
@@ -360,7 +401,7 @@ of the History library when you want to use the history functions in
|
||||
your program.
|
||||
|
||||
-- Function: void using_history (void)
|
||||
Begin a session in which the history functions might be used. This
|
||||
Begin a session that will use the history functions. This
|
||||
initializes the interactive variables.
|
||||
|
||||
-- Function: HISTORY_STATE * history_get_history_state (void)
|
||||
@@ -380,20 +421,22 @@ These functions manage individual entries on the history list, or set
|
||||
parameters managing the list itself.
|
||||
|
||||
-- Function: void add_history (const char *string)
|
||||
Place STRING at the end of the history list. The associated data
|
||||
field (if any) is set to 'NULL'. If the maximum number of history
|
||||
entries has been set using 'stifle_history()', and the new number
|
||||
of history entries would exceed that maximum, the oldest history
|
||||
entry is removed.
|
||||
Add STRING to the end of the history list, and set the associated
|
||||
data field (if any) to ‘NULL’. If the maximum number of history
|
||||
entries has been set using ‘stifle_history()’, and the new number
|
||||
of history entries would exceed that maximum, this removes the
|
||||
oldest history entry.
|
||||
|
||||
-- Function: void add_history_time (const char *string)
|
||||
Change the time stamp associated with the most recent history entry
|
||||
to STRING.
|
||||
|
||||
-- Function: HIST_ENTRY * remove_history (int which)
|
||||
Remove history entry at offset WHICH from the history. The removed
|
||||
element is returned so you can free the line, data, and containing
|
||||
structure.
|
||||
Remove the history entry at offset WHICH from the history list.
|
||||
This returns the removed element so you can free the line, data,
|
||||
and containing structure. Since the data is private to your
|
||||
application, the History library doesn't know how to free it, if
|
||||
necessary.
|
||||
|
||||
-- Function: histdata_t free_history_entry (HIST_ENTRY *histent)
|
||||
Free the history entry HISTENT and any history library private data
|
||||
@@ -404,8 +447,8 @@ parameters managing the list itself.
|
||||
*line, histdata_t data)
|
||||
Make the history entry at offset WHICH have LINE and DATA. This
|
||||
returns the old entry so the caller can dispose of any
|
||||
application-specific data. In the case of an invalid WHICH, a
|
||||
'NULL' pointer is returned.
|
||||
application-specific data. In the case of an invalid WHICH, this
|
||||
returns ‘NULL’.
|
||||
|
||||
-- Function: void clear_history (void)
|
||||
Clear the history list by deleting all the entries.
|
||||
@@ -416,7 +459,7 @@ parameters managing the list itself.
|
||||
|
||||
-- Function: int unstifle_history (void)
|
||||
Stop stifling the history. This returns the previously-set maximum
|
||||
number of history entries (as set by 'stifle_history()'). The
|
||||
number of history entries (as set by ‘stifle_history()’). The
|
||||
value is positive if the history was stifled, negative if it
|
||||
wasn't.
|
||||
|
||||
@@ -433,24 +476,23 @@ These functions return information about the entire history list or
|
||||
individual list entries.
|
||||
|
||||
-- Function: HIST_ENTRY ** history_list (void)
|
||||
Return a 'NULL' terminated array of 'HIST_ENTRY *' which is the
|
||||
Return a ‘NULL’ terminated array of ‘HIST_ENTRY *’ which is the
|
||||
current input history. Element 0 of this list is the beginning of
|
||||
time. If there is no history, return 'NULL'.
|
||||
time. Return ‘NULL’ if there is no history.
|
||||
|
||||
-- Function: int where_history (void)
|
||||
Returns the offset of the current history element.
|
||||
Return the offset of the current history entry.
|
||||
|
||||
-- Function: HIST_ENTRY * current_history (void)
|
||||
Return the history entry at the current position, as determined by
|
||||
'where_history()'. If there is no entry there, return a 'NULL'
|
||||
pointer.
|
||||
‘where_history()’. If there is no entry there, return ‘NULL’.
|
||||
|
||||
-- Function: HIST_ENTRY * history_get (int offset)
|
||||
Return the history entry at position OFFSET. The range of valid
|
||||
values of OFFSET starts at 'history_base' and ends at
|
||||
values of OFFSET starts at ‘history_base’ and ends at
|
||||
HISTORY_LENGTH - 1 (*note History Variables::). If there is no
|
||||
entry there, or if OFFSET is outside the valid range, return a
|
||||
'NULL' pointer.
|
||||
entry there, or if OFFSET is outside the valid range, return
|
||||
‘NULL’.
|
||||
|
||||
-- Function: time_t history_get_time (HIST_ENTRY *entry)
|
||||
Return the time stamp associated with the history entry ENTRY. If
|
||||
@@ -478,13 +520,13 @@ or changed.
|
||||
-- Function: HIST_ENTRY * previous_history (void)
|
||||
Back up the current history offset to the previous history entry,
|
||||
and return a pointer to that entry. If there is no previous entry,
|
||||
return a 'NULL' pointer.
|
||||
return ‘NULL’.
|
||||
|
||||
-- Function: HIST_ENTRY * next_history (void)
|
||||
If the current history offset refers to a valid history entry,
|
||||
increment the current history offset. If the possibly-incremented
|
||||
history offset refers to a valid history entry, return a pointer to
|
||||
that entry; otherwise, return a 'BNULL' pointer.
|
||||
that entry; otherwise, return ‘NULL’.
|
||||
|
||||
|
||||
File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions
|
||||
@@ -492,37 +534,37 @@ File: history.info, Node: Searching the History List, Next: Managing the Histo
|
||||
2.3.5 Searching the History List
|
||||
--------------------------------
|
||||
|
||||
These functions allow searching of the history list for entries
|
||||
containing a specific string. Searching may be performed both forward
|
||||
and backward from the current history position. The search may be
|
||||
"anchored", meaning that the string must match at the beginning of the
|
||||
history entry.
|
||||
These functions search the history list for entries containing a
|
||||
specific string. Searching may be performed both forward and backward
|
||||
from the current history position. The search may be “anchored”,
|
||||
meaning that the string must match at the beginning of a history entry.
|
||||
|
||||
-- Function: int history_search (const char *string, int direction)
|
||||
Search the history for STRING, starting at the current history
|
||||
offset. If DIRECTION is less than 0, then the search is through
|
||||
previous entries, otherwise through subsequent entries. If STRING
|
||||
is found, then the current history index is set to that history
|
||||
entry, and the value returned is the offset in the line of the
|
||||
entry where STRING was found. Otherwise, nothing is changed, and a
|
||||
-1 is returned.
|
||||
entry, and ‘history_search’ returns the offset in the line of the
|
||||
entry where STRING was found. Otherwise, nothing is changed, and
|
||||
this returns -1.
|
||||
|
||||
-- Function: int history_search_prefix (const char *string, int
|
||||
direction)
|
||||
Search the history for STRING, starting at the current history
|
||||
offset. The search is anchored: matching lines must begin with
|
||||
STRING. If DIRECTION is less than 0, then the search is through
|
||||
previous entries, otherwise through subsequent entries. If STRING
|
||||
is found, then the current history index is set to that entry, and
|
||||
the return value is 0. Otherwise, nothing is changed, and a -1 is
|
||||
returned.
|
||||
offset. The search is anchored: matching history entries must
|
||||
begin with STRING. If DIRECTION is less than 0, then the search is
|
||||
through previous entries, otherwise through subsequent entries. If
|
||||
STRING is found, then the current history index is set to that
|
||||
entry, and the return value is 0. Otherwise, nothing is changed,
|
||||
and this returns -1.
|
||||
|
||||
-- Function: int history_search_pos (const char *string, int direction,
|
||||
int pos)
|
||||
Search for STRING in the history list, starting at POS, an absolute
|
||||
index into the list. If DIRECTION is negative, the search proceeds
|
||||
backward from POS, otherwise forward. Returns the absolute index
|
||||
of the history element where STRING was found, or -1 otherwise.
|
||||
backward from POS, otherwise forward. Returns the index in the
|
||||
history list of the history element where STRING was found, or -1
|
||||
otherwise.
|
||||
|
||||
|
||||
File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions
|
||||
@@ -534,34 +576,43 @@ The History library can read the history from and write it to a file.
|
||||
This section documents the functions for managing a history file.
|
||||
|
||||
-- Function: int read_history (const char *filename)
|
||||
Add the contents of FILENAME to the history list, a line at a time.
|
||||
If FILENAME is 'NULL', then read from '~/.history'. Returns 0 if
|
||||
successful, or 'errno' if not.
|
||||
Add the contents of FILENAME to the history list, one entry at a
|
||||
time. If FILENAME is ‘NULL’, this reads from ‘~/.history’, if it
|
||||
exists. This attempts to determine whether the history file
|
||||
includes timestamp information, and assigns timestamps to the
|
||||
history entries it reads if so. Returns 0 if successful, or
|
||||
‘errno’ if not.
|
||||
|
||||
-- Function: int read_history_range (const char *filename, int from,
|
||||
int to)
|
||||
Read a range of lines from FILENAME, adding them to the history
|
||||
list. Start reading at line FROM and end at TO. If FROM is zero,
|
||||
start at the beginning. If TO is less than FROM, then read until
|
||||
the end of the file. If FILENAME is 'NULL', then read from
|
||||
'~/.history'. Returns 0 if successful, or 'errno' if not.
|
||||
start at the beginning. If TO is less than FROM, this reads until
|
||||
the end of the file. This attempts to determine whether the
|
||||
history file includes timestamp information, and assigns timestamps
|
||||
to the history entries it reads if so. If FILENAME is ‘NULL’, this
|
||||
reads from ‘~/.history’, if it exists. Returns 0 if successful, or
|
||||
‘errno’ if not.
|
||||
|
||||
-- Function: int write_history (const char *filename)
|
||||
Write the current history to FILENAME, overwriting FILENAME if
|
||||
necessary. If FILENAME is 'NULL', then write the history list to
|
||||
'~/.history'. Returns 0 on success, or 'errno' on a read or write
|
||||
error.
|
||||
necessary. This writes timestamp information if the
|
||||
‘history_write_timestamps’ variable is set to a non-zero value. If
|
||||
FILENAME is ‘NULL’, then write the history list to ‘~/.history’.
|
||||
Returns 0 on success, or ‘errno’ on a read or write error.
|
||||
|
||||
-- Function: int append_history (int nelements, const char *filename)
|
||||
Append the last NELEMENTS of the history list to FILENAME. If
|
||||
FILENAME is 'NULL', then append to '~/.history'. Returns 0 on
|
||||
success, or 'errno' on a read or write error.
|
||||
Append the last NELEMENTS of the history list to FILENAME. This
|
||||
writes timestamp information if the ‘history_write_timestamps’
|
||||
variable is set to a non-zero value. If FILENAME is ‘NULL’, then
|
||||
append to ‘~/.history’. Returns 0 on success, or ‘errno’ on a read
|
||||
or write error.
|
||||
|
||||
-- Function: int history_truncate_file (const char *filename, int
|
||||
nlines)
|
||||
Truncate the history file FILENAME, leaving only the last NLINES
|
||||
lines. If FILENAME is 'NULL', then '~/.history' is truncated.
|
||||
Returns 0 on success, or 'errno' on failure.
|
||||
lines. If FILENAME is ‘NULL’, this truncates ‘~/.history’.
|
||||
Returns 0 on success, or ‘errno’ on failure.
|
||||
|
||||
|
||||
File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions
|
||||
@@ -571,44 +622,44 @@ File: history.info, Node: History Expansion, Prev: Managing the History File,
|
||||
|
||||
These functions implement history expansion.
|
||||
|
||||
-- Function: int history_expand (char *string, char **output)
|
||||
-- Function: int history_expand (const char *string, char **output)
|
||||
Expand STRING, placing the result into OUTPUT, a pointer to a
|
||||
string (*note History Interaction::). Returns:
|
||||
'0'
|
||||
‘0’
|
||||
If no expansions took place (or, if the only change in the
|
||||
text was the removal of escape characters preceding the
|
||||
history expansion character);
|
||||
'1'
|
||||
‘1’
|
||||
if expansions did take place;
|
||||
'-1'
|
||||
‘-1’
|
||||
if there was an error in expansion;
|
||||
'2'
|
||||
‘2’
|
||||
if the returned line should be displayed, but not executed, as
|
||||
with the ':p' modifier (*note Modifiers::).
|
||||
with the ‘:p’ modifier (*note Modifiers::).
|
||||
|
||||
If an error occurred in expansion, then OUTPUT contains a
|
||||
If an error occurred during expansion, then OUTPUT contains a
|
||||
descriptive error message.
|
||||
|
||||
-- Function: char * get_history_event (const char *string, int *cindex,
|
||||
int qchar)
|
||||
Returns the text of the history event beginning at STRING +
|
||||
*CINDEX. *CINDEX is modified to point to after the event
|
||||
specifier. At function entry, CINDEX points to the index into
|
||||
STRING where the history event specification begins. QCHAR is a
|
||||
character that is allowed to end the event specification in
|
||||
addition to the "normal" terminating characters.
|
||||
*CINDEX. Modifies *CINDEX to point to after the event specifier.
|
||||
At function entry, CINDEX points to the index into STRING where the
|
||||
history event specification begins. QCHAR is a character that is
|
||||
allowed to end the event specification in addition to the "normal"
|
||||
terminating characters.
|
||||
|
||||
-- Function: char ** history_tokenize (const char *string)
|
||||
Return an array of tokens parsed out of STRING, much as the shell
|
||||
might. The tokens are split on the characters in the
|
||||
HISTORY_WORD_DELIMITERS variable, and shell quoting conventions are
|
||||
obeyed.
|
||||
obeyed as described below.
|
||||
|
||||
-- Function: char * history_arg_extract (int first, int last, const
|
||||
char *string)
|
||||
Extract a string segment consisting of the FIRST through LAST
|
||||
arguments present in STRING. Arguments are split using
|
||||
'history_tokenize'.
|
||||
arguments present in STRING. This splits STRING into arguments
|
||||
using ‘history_tokenize’.
|
||||
|
||||
|
||||
File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History
|
||||
@@ -627,7 +678,7 @@ GNU History Library.
|
||||
|
||||
-- Variable: int history_max_entries
|
||||
The maximum number of history entries. This must be changed using
|
||||
'stifle_history()'.
|
||||
‘stifle_history()’.
|
||||
|
||||
-- Variable: int history_write_timestamps
|
||||
If non-zero, timestamps are written to the history file, so they
|
||||
@@ -636,50 +687,67 @@ GNU History Library.
|
||||
|
||||
The current timestamp format uses the value of HISTORY_COMMENT_CHAR
|
||||
to delimit timestamp entries in the history file. If that variable
|
||||
does not have a value (the default), timestamps will not be
|
||||
written.
|
||||
does not have a value (the default), this will not write
|
||||
timestamps.
|
||||
|
||||
-- Variable: char history_expansion_char
|
||||
The character that introduces a history event. The default is '!'.
|
||||
The character that introduces a history event. The default is ‘!’.
|
||||
Setting this to 0 inhibits history expansion.
|
||||
|
||||
-- Variable: char history_subst_char
|
||||
The character that invokes word substitution if found at the start
|
||||
of a line. The default is '^'.
|
||||
of a line. The default is ‘^’.
|
||||
|
||||
-- Variable: char history_comment_char
|
||||
During tokenization, if this character is seen as the first
|
||||
During tokenization, if this character appears as the first
|
||||
character of a word, then it and all subsequent characters up to a
|
||||
newline are ignored, suppressing history expansion for the
|
||||
remainder of the line. This is disabled by default.
|
||||
|
||||
-- Variable: char * history_word_delimiters
|
||||
The characters that separate tokens for 'history_tokenize()'. The
|
||||
default value is '" \t\n()<>;&|"'.
|
||||
The characters that separate tokens for ‘history_tokenize()’. The
|
||||
default value is ‘" \t\n()<>;&|"’.
|
||||
|
||||
-- Variable: char * history_search_delimiter_chars
|
||||
The list of additional characters which can delimit a history
|
||||
search string, in addition to space, TAB, ':' and '?' in the case
|
||||
search string, in addition to space, TAB, ‘:’ and ‘?’ in the case
|
||||
of a substring search. The default is empty.
|
||||
|
||||
-- Variable: char * history_no_expand_chars
|
||||
The list of characters which inhibit history expansion if found
|
||||
immediately following HISTORY_EXPANSION_CHAR. The default is
|
||||
space, tab, newline, carriage return, and '='.
|
||||
space, tab, newline, carriage return, and ‘=’.
|
||||
|
||||
-- Variable: int history_quotes_inhibit_expansion
|
||||
If non-zero, double-quoted words are not scanned for the history
|
||||
expansion character or the history comment character. The default
|
||||
If non-zero, the history expansion code implements shell-like
|
||||
quoting: single-quoted words are not scanned for the history
|
||||
expansion character or the history comment character, and
|
||||
double-quoted words may have history expansion performed, since
|
||||
single quotes are not special within double quotes. The default
|
||||
value is 0.
|
||||
|
||||
-- Variable: int history_quoting_state
|
||||
An application may set this variable to indicate that the current
|
||||
line being expanded is subject to existing quoting. If set to ‘'’,
|
||||
the history expansion function will assume that the line is
|
||||
single-quoted and inhibit expansion until it reads an unquoted
|
||||
closing single quote; if set to ‘"’, history expansion will assume
|
||||
the line is double quoted until it reads an unquoted closing double
|
||||
quote. If set to 0, the default, the history expansion function
|
||||
will assume the line is not quoted and treat quote characters
|
||||
within the line as described above. This is only effective if
|
||||
HISTORY_QUOTES_INHIBIT_EXPANSION is set. This is intended for use
|
||||
by applications like Bash which allow quoted strings to span
|
||||
multiple lines.
|
||||
|
||||
-- Variable: rl_linebuf_func_t * history_inhibit_expansion_function
|
||||
This should be set to the address of a function that takes two
|
||||
arguments: a 'char *' (STRING) and an 'int' index into that string
|
||||
arguments: a ‘char *’ (STRING) and an ‘int’ index into that string
|
||||
(I). It should return a non-zero value if the history expansion
|
||||
starting at STRING[I] should not be performed; zero if the
|
||||
expansion should be done. It is intended for use by applications
|
||||
like Bash that use the history expansion character for additional
|
||||
purposes. By default, this variable is set to 'NULL'.
|
||||
purposes. By default, this variable is set to ‘NULL’.
|
||||
|
||||
|
||||
File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History
|
||||
@@ -693,9 +761,8 @@ Library.
|
||||
#include <stdio.h>
|
||||
#include <readline/history.h>
|
||||
|
||||
main (argc, argv)
|
||||
int argc;
|
||||
char **argv;
|
||||
int
|
||||
main (int argc, char **argv)
|
||||
{
|
||||
char line[1024], *t;
|
||||
int len, done = 0;
|
||||
@@ -784,7 +851,7 @@ Appendix A GNU Free Documentation License
|
||||
|
||||
Version 1.3, 3 November 2008
|
||||
|
||||
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
|
||||
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
|
||||
<http://fsf.org/>
|
||||
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
@@ -793,7 +860,7 @@ Appendix A GNU Free Documentation License
|
||||
0. PREAMBLE
|
||||
|
||||
The purpose of this License is to make a manual, textbook, or other
|
||||
functional and useful document "free" in the sense of freedom: to
|
||||
functional and useful document “free” in the sense of freedom: to
|
||||
assure everyone the effective freedom to copy and redistribute it,
|
||||
with or without modifying it, either commercially or
|
||||
noncommercially. Secondarily, this License preserves for the
|
||||
@@ -1270,7 +1337,7 @@ Appendix B Concept Index
|
||||
* anchored search: Searching the History List.
|
||||
(line 10)
|
||||
* event designators: Event Designators. (line 6)
|
||||
* history events: Event Designators. (line 8)
|
||||
* history events: Event Designators. (line 10)
|
||||
* history expansion: History Interaction. (line 6)
|
||||
* History Searching: Searching the History List.
|
||||
(line 6)
|
||||
@@ -1289,13 +1356,13 @@ Appendix C Function and Variable Index
|
||||
* add_history_time: History List Management.
|
||||
(line 16)
|
||||
* append_history: Managing the History File.
|
||||
(line 28)
|
||||
(line 35)
|
||||
* clear_history: History List Management.
|
||||
(line 37)
|
||||
(line 39)
|
||||
* current_history: Information About the History List.
|
||||
(line 17)
|
||||
* free_history_entry: History List Management.
|
||||
(line 25)
|
||||
(line 27)
|
||||
* get_history_event: History Expansion. (line 26)
|
||||
* history_arg_extract: History Expansion. (line 41)
|
||||
* history_base: History Variables. (line 9)
|
||||
@@ -1303,27 +1370,28 @@ Appendix C Function and Variable Index
|
||||
* history_expand: History Expansion. (line 8)
|
||||
* history_expansion_char: History Variables. (line 29)
|
||||
* history_get: Information About the History List.
|
||||
(line 22)
|
||||
(line 21)
|
||||
* history_get_history_state: Initializing History and State Management.
|
||||
(line 14)
|
||||
* history_get_time: Information About the History List.
|
||||
(line 29)
|
||||
* history_inhibit_expansion_function: History Variables. (line 62)
|
||||
(line 28)
|
||||
* history_inhibit_expansion_function: History Variables. (line 79)
|
||||
* history_is_stifled: History List Management.
|
||||
(line 50)
|
||||
(line 52)
|
||||
* history_length: History Variables. (line 12)
|
||||
* history_list: Information About the History List.
|
||||
(line 9)
|
||||
* history_max_entries: History Variables. (line 15)
|
||||
* history_no_expand_chars: History Variables. (line 52)
|
||||
* history_quotes_inhibit_expansion: History Variables. (line 57)
|
||||
* history_quoting_state: History Variables. (line 65)
|
||||
* history_search: Searching the History List.
|
||||
(line 12)
|
||||
(line 11)
|
||||
* history_search_delimiter_chars: History Variables. (line 47)
|
||||
* history_search_pos: Searching the History List.
|
||||
(line 31)
|
||||
(line 30)
|
||||
* history_search_prefix: Searching the History List.
|
||||
(line 21)
|
||||
(line 20)
|
||||
* history_set_history_state: Initializing History and State Management.
|
||||
(line 18)
|
||||
* history_set_pos: Moving Around the History List.
|
||||
@@ -1331,9 +1399,9 @@ Appendix C Function and Variable Index
|
||||
* history_subst_char: History Variables. (line 33)
|
||||
* history_tokenize: History Expansion. (line 35)
|
||||
* history_total_bytes: Information About the History List.
|
||||
(line 33)
|
||||
(line 32)
|
||||
* history_truncate_file: Managing the History File.
|
||||
(line 33)
|
||||
(line 42)
|
||||
* history_word_delimiters: History Variables. (line 43)
|
||||
* history_write_timestamps: History Variables. (line 19)
|
||||
* next_history: Moving Around the History List.
|
||||
@@ -1343,46 +1411,51 @@ Appendix C Function and Variable Index
|
||||
* read_history: Managing the History File.
|
||||
(line 9)
|
||||
* read_history_range: Managing the History File.
|
||||
(line 14)
|
||||
(line 17)
|
||||
* remove_history: History List Management.
|
||||
(line 20)
|
||||
* replace_history_entry: History List Management.
|
||||
(line 30)
|
||||
(line 32)
|
||||
* stifle_history: History List Management.
|
||||
(line 40)
|
||||
(line 42)
|
||||
* unstifle_history: History List Management.
|
||||
(line 44)
|
||||
(line 46)
|
||||
* using_history: Initializing History and State Management.
|
||||
(line 10)
|
||||
* where_history: Information About the History List.
|
||||
(line 14)
|
||||
* write_history: Managing the History File.
|
||||
(line 22)
|
||||
(line 28)
|
||||
|
||||
|
||||
|
||||
Tag Table:
|
||||
Node: Top849
|
||||
Node: Using History Interactively1494
|
||||
Node: History Interaction2002
|
||||
Node: Event Designators3426
|
||||
Node: Word Designators4565
|
||||
Node: Modifiers6202
|
||||
Node: Programming with GNU History7425
|
||||
Node: Introduction to History8169
|
||||
Node: History Storage9859
|
||||
Node: History Functions10994
|
||||
Node: Initializing History and State Management11983
|
||||
Node: History List Management12795
|
||||
Node: Information About the History List15089
|
||||
Node: Moving Around the History List16703
|
||||
Node: Searching the History List17796
|
||||
Node: Managing the History File19721
|
||||
Node: History Expansion21541
|
||||
Node: History Variables23451
|
||||
Node: History Programming Example26521
|
||||
Node: GNU Free Documentation License29198
|
||||
Node: Concept Index54370
|
||||
Node: Function and Variable Index55075
|
||||
Node: Top847
|
||||
Node: Using History Interactively1492
|
||||
Node: History Interaction2000
|
||||
Node: Event Designators4714
|
||||
Node: Word Designators6216
|
||||
Node: Modifiers8527
|
||||
Node: Programming with GNU History10178
|
||||
Node: Introduction to History10922
|
||||
Node: History Storage12654
|
||||
Node: History Functions13834
|
||||
Node: Initializing History and State Management14823
|
||||
Node: History List Management15626
|
||||
Node: Information About the History List18057
|
||||
Node: Moving Around the History List19670
|
||||
Node: Searching the History List20750
|
||||
Node: Managing the History File22696
|
||||
Node: History Expansion25166
|
||||
Node: History Variables27139
|
||||
Node: History Programming Example31281
|
||||
Node: GNU Free Documentation License33935
|
||||
Node: Concept Index59110
|
||||
Node: Function and Variable Index59815
|
||||
|
||||
End Tag Table
|
||||
|
||||
|
||||
Local Variables:
|
||||
coding: utf-8
|
||||
End:
|
||||
|
||||
@@ -1,11 +1,12 @@
|
||||
This is pdfTeX, Version 3.14159265-2.6-1.40.18 (TeX Live 2017/MacPorts 2017_2) (preloaded format=etex 2017.7.5) 2 JAN 2018 10:55
|
||||
This is pdfTeX, Version 3.141592653-2.6-1.40.26 (TeX Live 2024/MacPorts 2024.70613_0) (preloaded format=etex 2024.4.9) 12 OCT 2024 13:36
|
||||
entering extended mode
|
||||
restricted \write18 enabled.
|
||||
file:line:error style messages enabled.
|
||||
%&-line parsing enabled.
|
||||
**\catcode126=12 \def\normaltilde{~}\catcode126=13 \let~\normaltilde \input ./
|
||||
./history.texi
|
||||
(././history.texi (./texinfo.tex Loading texinfo [version 2015-11-22.14]:
|
||||
**\nonstopmode \input ././history.texi
|
||||
(././history.texi
|
||||
(/usr/local/src/bash/bash-20241011/lib/readline/doc/texinfo.tex
|
||||
Loading texinfo [version 2015-11-22.14]:
|
||||
\outerhsize=\dimen16
|
||||
\outervsize=\dimen17
|
||||
\cornerlong=\dimen18
|
||||
@@ -39,15 +40,15 @@ entering extended mode
|
||||
\boxB=\box20
|
||||
\countA=\count32
|
||||
\nopdfimagehelp=\toks20
|
||||
|
||||
fonts,
|
||||
fonts,
|
||||
\sffam=\fam8
|
||||
\textleading=\dimen26
|
||||
markup,
|
||||
\fontdepth=\count33
|
||||
glyphs,
|
||||
\errorbox=\box21
|
||||
page headings,
|
||||
|
||||
page headings,
|
||||
\titlepagetopglue=\skip20
|
||||
\titlepagebottomglue=\skip21
|
||||
\evenheadline=\toks21
|
||||
@@ -81,8 +82,7 @@ fonts,
|
||||
\doublecolumntopgap=\dimen34
|
||||
\savedtopmark=\toks26
|
||||
\savedfirstmark=\toks27
|
||||
|
||||
sectioning,
|
||||
sectioning,
|
||||
\unnumberedno=\count38
|
||||
\chapno=\count39
|
||||
\secno=\count40
|
||||
@@ -114,7 +114,8 @@ sectioning,
|
||||
\nonfillparindent=\dimen39
|
||||
\tabw=\dimen40
|
||||
\verbbox=\box25
|
||||
defuns,
|
||||
|
||||
defuns,
|
||||
\defbodyindent=\skip39
|
||||
\defargsindent=\skip40
|
||||
\deflastargmargin=\skip41
|
||||
@@ -160,14 +161,16 @@ This is `epsf.tex' v2.7.4 <14 February 2011>
|
||||
texinfo.tex: doing @include of version.texi
|
||||
|
||||
|
||||
(./version.texi) [1] [2] (./history.toc) [-1]
|
||||
(/usr/local/src/bash/bash-20241011/lib/readline/doc/version.texi) [1] [2]
|
||||
(/usr/local/src/bash/bash-20241011/lib/readline/doc/history.toc) [-1]
|
||||
texinfo.tex: doing @include of hsuser.texi
|
||||
|
||||
(./hsuser.texi Chapter 1
|
||||
|
||||
(/usr/local/src/bash/bash-20241011/lib/readline/doc/hsuser.texi Chapter 1
|
||||
\openout0 = `history.toc'.
|
||||
|
||||
|
||||
(./history.aux)
|
||||
(/usr/local/src/bash/bash-20241011/lib/readline/doc/history.aux)
|
||||
\openout1 = `history.aux'.
|
||||
|
||||
@cpindfile=@write2
|
||||
@@ -179,11 +182,13 @@ texinfo.tex: doing @include of hsuser.texi
|
||||
@numsubsecentry{Event Designators}{1.1.1}{Event Designators}{1}
|
||||
] [2
|
||||
@numsubsecentry{Word Designators}{1.1.2}{Word Designators}{2}
|
||||
@numsubsecentry{Modifiers}{1.1.3}{Modifiers}{2}
|
||||
])
|
||||
texinfo.tex: doing @include of hstech.texi
|
||||
|
||||
(./hstech.texi Chapter 2 [3] [4
|
||||
(/usr/local/src/bash/bash-20241011/lib/readline/doc/hstech.texi Chapter 2
|
||||
[3
|
||||
@numsubsecentry{Modifiers}{1.1.3}{Modifiers}{3}
|
||||
] [4
|
||||
@numchapentry{Programming with GNU History}{2}{Programming with GNU History}{4}
|
||||
|
||||
@numsecentry{Introduction to History}{2.1}{Introduction to History}{4}
|
||||
@@ -218,24 +223,25 @@ y List}{7}
|
||||
] [10
|
||||
@numsecentry{History Programming Example}{2.5}{History Programming Example}{10}
|
||||
|
||||
]) Appendix A [11]
|
||||
] [11]) Appendix A [12]
|
||||
texinfo.tex: doing @include of fdl.texi
|
||||
|
||||
(./fdl.texi [12
|
||||
@appentry{GNU Free Documentation License}{A}{GNU Free Documentation License}{12
|
||||
|
||||
(/usr/local/src/bash/bash-20241011/lib/readline/doc/fdl.texi [13
|
||||
@appentry{GNU Free Documentation License}{A}{GNU Free Documentation License}{13
|
||||
}
|
||||
] [13] [14] [15] [16] [17] [18]) Appendix B [19] Appendix C [20
|
||||
@appentry{Concept Index}{B}{Concept Index}{20}
|
||||
] [21
|
||||
@appentry{Function and Variable Index}{C}{Function and Variable Index}{21}
|
||||
] [14] [15] [16] [17] [18] [19]) Appendix B [20] Appendix C [21
|
||||
@appentry{Concept Index}{B}{Concept Index}{21}
|
||||
] [22
|
||||
@appentry{Function and Variable Index}{C}{Function and Variable Index}{22}
|
||||
] )
|
||||
Here is how much of TeX's memory you used:
|
||||
3182 strings out of 497114
|
||||
31680 string characters out of 6207173
|
||||
79568 words of memory out of 5000000
|
||||
4354 multiletter control sequences out of 15000+600000
|
||||
3183 strings out of 495850
|
||||
32438 string characters out of 6172145
|
||||
89088 words of memory out of 5000000
|
||||
4539 multiletter control sequences out of 15000+600000
|
||||
32778 words of font info for 114 fonts, out of 8000000 for 9000
|
||||
51 hyphenation exceptions out of 8191
|
||||
19i,6n,17p,362b,772s stack positions out of 5000i,500n,10000p,200000b,80000s
|
||||
701 hyphenation exceptions out of 8191
|
||||
19i,6n,17p,307b,772s stack positions out of 10000i,1000n,20000p,200000b,200000s
|
||||
|
||||
Output written on history.dvi (24 pages, 69556 bytes).
|
||||
Output written on history.dvi (25 pages, 75220 bytes).
|
||||
|
||||
Binary file not shown.
+1886
-1751
File diff suppressed because it is too large
Load Diff
@@ -12,7 +12,7 @@ This document describes the GNU History library
|
||||
a programming tool that provides a consistent user interface for
|
||||
recalling lines of previously typed input.
|
||||
|
||||
Copyright @copyright{} 1988--2023 Free Software Foundation, Inc.
|
||||
Copyright @copyright{} 1988--2024 Free Software Foundation, Inc.
|
||||
|
||||
@quotation
|
||||
Permission is granted to copy, distribute and/or modify this document
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
\entry{history_comment_char}{9}{\code {history_comment_char}}
|
||||
\entry{history_word_delimiters}{9}{\code {history_word_delimiters}}
|
||||
\entry{history_search_delimiter_chars}{9}{\code {history_search_delimiter_chars}}
|
||||
\entry{history_no_expand_chars}{9}{\code {history_no_expand_chars}}
|
||||
\entry{history_quotes_inhibit_expansion}{9}{\code {history_quotes_inhibit_expansion}}
|
||||
\entry{history_no_expand_chars}{10}{\code {history_no_expand_chars}}
|
||||
\entry{history_quotes_inhibit_expansion}{10}{\code {history_quotes_inhibit_expansion}}
|
||||
\entry{history_quoting_state}{10}{\code {history_quoting_state}}
|
||||
\entry{history_inhibit_expansion_function}{10}{\code {history_inhibit_expansion_function}}
|
||||
|
||||
@@ -1,12 +1,13 @@
|
||||
\entry {\code {history_base}}{9}
|
||||
\entry {\code {history_comment_char}}{9}
|
||||
\entry {\code {history_expansion_char}}{9}
|
||||
\entry {\code {history_inhibit_expansion_function}}{10}
|
||||
\entry {\code {history_length}}{9}
|
||||
\entry {\code {history_max_entries}}{9}
|
||||
\entry {\code {history_no_expand_chars}}{9}
|
||||
\entry {\code {history_quotes_inhibit_expansion}}{9}
|
||||
\entry {\code {history_search_delimiter_chars}}{9}
|
||||
\entry {\code {history_subst_char}}{9}
|
||||
\entry {\code {history_word_delimiters}}{9}
|
||||
\entry {\code {history_write_timestamps}}{9}
|
||||
\entry{\code {history_base}}{9}
|
||||
\entry{\code {history_comment_char}}{9}
|
||||
\entry{\code {history_expansion_char}}{9}
|
||||
\entry{\code {history_inhibit_expansion_function}}{10}
|
||||
\entry{\code {history_length}}{9}
|
||||
\entry{\code {history_max_entries}}{9}
|
||||
\entry{\code {history_no_expand_chars}}{10}
|
||||
\entry{\code {history_quotes_inhibit_expansion}}{10}
|
||||
\entry{\code {history_quoting_state}}{10}
|
||||
\entry{\code {history_search_delimiter_chars}}{9}
|
||||
\entry{\code {history_subst_char}}{9}
|
||||
\entry{\code {history_word_delimiters}}{9}
|
||||
\entry{\code {history_write_timestamps}}{9}
|
||||
|
||||
Binary file not shown.
+133
-93
@@ -1,7 +1,7 @@
|
||||
@ignore
|
||||
This file documents the user interface to the GNU History library.
|
||||
|
||||
Copyright (C) 1988-2023 Free Software Foundation, Inc.
|
||||
Copyright (C) 1988-2024 Free Software Foundation, Inc.
|
||||
Authored by Brian Fox and Chet Ramey.
|
||||
|
||||
Permission is granted to make and distribute verbatim copies of this manual
|
||||
@@ -29,8 +29,8 @@ into another language, under the above conditions for modified versions.
|
||||
This chapter describes how to interface programs that you write
|
||||
with the @sc{gnu} History Library.
|
||||
It should be considered a technical guide.
|
||||
For information on the interactive use of @sc{gnu} History, @pxref{Using
|
||||
History Interactively}.
|
||||
For information on the interactive use of @sc{gnu} History,
|
||||
@pxref{Using History Interactively}.
|
||||
|
||||
@menu
|
||||
* Introduction to History:: What is the GNU History library for?
|
||||
@@ -43,23 +43,27 @@ History Interactively}.
|
||||
@node Introduction to History
|
||||
@section Introduction to History
|
||||
|
||||
Many programs read input from the user a line at a time. The @sc{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.
|
||||
Many programs read input from the user a line at a time.
|
||||
The @sc{gnu} History library is able to keep track of those lines,
|
||||
associate arbitrary data with each line, and utilize information from
|
||||
previous lines when composing new ones.
|
||||
|
||||
A 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 @dfn{expansion} function
|
||||
A programmer using the History library can use functions
|
||||
to save commands on a history list,
|
||||
associate arbitrary data with history list entries,
|
||||
remove entries from the list,
|
||||
search through the list for a line containing an arbitrary text string,
|
||||
reference any entry in the list directly,
|
||||
and read and write the history list from and to a file.
|
||||
In addition, a history @dfn{expansion} function
|
||||
is available which provides for a consistent user interface across
|
||||
different programs.
|
||||
|
||||
The user using programs written with the History library has the
|
||||
Someone 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
|
||||
in new commands.
|
||||
The basic history manipulation commands are similar to
|
||||
the history substitution provided by @code{csh}.
|
||||
|
||||
The programmer can also use the Readline library, which
|
||||
@@ -69,15 +73,16 @@ advantage of command line editing.
|
||||
Before declaring any functions using any functionality the History
|
||||
library provides in other code, an application writer should include
|
||||
the file @code{<readline/history.h>} 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.
|
||||
History library's features.
|
||||
It supplies declarations for all of the library's
|
||||
public functions and variables,
|
||||
and declares all of the public data structures.
|
||||
|
||||
@node History Storage
|
||||
@section History Storage
|
||||
|
||||
The history list is an array of history entries. A history entry is
|
||||
declared as follows:
|
||||
The history list is an array of history entries.
|
||||
A history entry is declared as follows:
|
||||
|
||||
@example
|
||||
typedef void *histdata_t;
|
||||
@@ -111,7 +116,7 @@ typedef struct _hist_state @{
|
||||
@end example
|
||||
|
||||
If the flags member includes @code{HS_STIFLED}, the history has been
|
||||
stifled.
|
||||
stifled (limited to a maximum number of entries).
|
||||
|
||||
@node History Functions
|
||||
@section History Functions
|
||||
@@ -145,8 +150,8 @@ the state of the History library when you want to use the history
|
||||
functions in your program.
|
||||
|
||||
@deftypefun void using_history (void)
|
||||
Begin a session in which the history functions might be used. This
|
||||
initializes the interactive variables.
|
||||
Begin a session that will use the history functions.
|
||||
This initializes the interactive variables.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HISTORY_STATE *} history_get_history_state (void)
|
||||
@@ -164,11 +169,11 @@ These functions manage individual entries on the history list, or set
|
||||
parameters managing the list itself.
|
||||
|
||||
@deftypefun void add_history (const char *string)
|
||||
Place @var{string} at the end of the history list. The associated data
|
||||
field (if any) is set to @code{NULL}.
|
||||
Add @var{string} to the end of the history list, and
|
||||
set the associated data field (if any) to @code{NULL}.
|
||||
If the maximum number of history entries has been set using
|
||||
@code{stifle_history()}, and the new number of history entries would exceed
|
||||
that maximum, the oldest history entry is removed.
|
||||
@code{stifle_history()}, and the new number of history entries
|
||||
would exceed that maximum, this removes the oldest history entry.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun void add_history_time (const char *string)
|
||||
@@ -177,22 +182,25 @@ Change the time stamp associated with the most recent history entry to
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} remove_history (int which)
|
||||
Remove history entry at offset @var{which} from the history. The
|
||||
removed element is returned so you can free the line, data,
|
||||
Remove the history entry at offset @var{which} from the history list.
|
||||
This returns the removed element so you can free the line, data,
|
||||
and containing structure.
|
||||
Since the data is private to your application, the History library
|
||||
doesn't know how to free it, if necessary.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {histdata_t} free_history_entry (HIST_ENTRY *histent)
|
||||
Free the history entry @var{histent} and any history library private
|
||||
data associated with it. Returns the application-specific data
|
||||
data associated with it.
|
||||
Returns the application-specific data
|
||||
so the caller can dispose of it.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} replace_history_entry (int which, const char *line, histdata_t data)
|
||||
Make the history entry at offset @var{which} have @var{line} and @var{data}.
|
||||
This returns the old entry so the caller can dispose of any
|
||||
application-specific data. In the case
|
||||
of an invalid @var{which}, a @code{NULL} pointer is returned.
|
||||
application-specific data.
|
||||
In the case of an invalid @var{which}, this returns @code{NULL}.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun void clear_history (void)
|
||||
@@ -205,10 +213,10 @@ The history list will contain only @var{max} entries at a time.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int unstifle_history (void)
|
||||
Stop stifling the history. This returns the previously-set
|
||||
maximum number of history entries (as set by @code{stifle_history()}).
|
||||
The value is positive if the history was
|
||||
stifled, negative if it wasn't.
|
||||
Stop stifling the history.
|
||||
This returns the previously-set maximum number of history
|
||||
entries (as set by @code{stifle_history()}).
|
||||
The value is positive if the history was stifled, negative if it wasn't.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int history_is_stifled (void)
|
||||
@@ -223,18 +231,19 @@ individual list entries.
|
||||
|
||||
@deftypefun {HIST_ENTRY **} history_list (void)
|
||||
Return a @code{NULL} terminated array of @code{HIST_ENTRY *} which is the
|
||||
current input history. Element 0 of this list is the beginning of time.
|
||||
If there is no history, return @code{NULL}.
|
||||
current input history.
|
||||
Element 0 of this list is the beginning of time.
|
||||
Return @code{NULL} if there is no history.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int where_history (void)
|
||||
Returns the offset of the current history element.
|
||||
Return the offset of the current history entry.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} current_history (void)
|
||||
Return the history entry at the current position, as determined by
|
||||
@code{where_history()}. If there is no entry there, return a @code{NULL}
|
||||
pointer.
|
||||
@code{where_history()}.
|
||||
If there is no entry there, return @code{NULL}.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} history_get (int offset)
|
||||
@@ -243,7 +252,7 @@ The range of valid
|
||||
values of @var{offset} starts at @code{history_base} and ends at
|
||||
@var{history_length} - 1 (@pxref{History Variables}).
|
||||
If there is no entry there, or if @var{offset} is outside the valid
|
||||
range, return a @code{NULL} pointer.
|
||||
range, return @code{NULL}.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun time_t history_get_time (HIST_ENTRY *entry)
|
||||
@@ -272,8 +281,8 @@ than the number of history entries.
|
||||
|
||||
@deftypefun {HIST_ENTRY *} previous_history (void)
|
||||
Back up the current history offset to the previous history entry, and
|
||||
return a pointer to that entry. If there is no previous entry, return
|
||||
a @code{NULL} pointer.
|
||||
return a pointer to that entry.
|
||||
If there is no previous entry, return @code{NULL}.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {HIST_ENTRY *} next_history (void)
|
||||
@@ -281,45 +290,51 @@ If the current history offset refers to a valid history entry,
|
||||
increment the current history offset.
|
||||
If the possibly-incremented history offset refers to a valid history
|
||||
entry, return a pointer to that entry;
|
||||
otherwise, return a @code{BNULL} pointer.
|
||||
otherwise, return @code{NULL}.
|
||||
@end deftypefun
|
||||
|
||||
@node Searching the History List
|
||||
@subsection Searching the History List
|
||||
@cindex History Searching
|
||||
|
||||
These functions allow searching of the history list for entries containing
|
||||
a specific string. Searching may be performed both forward and backward
|
||||
from the current history position. The search may be @dfn{anchored},
|
||||
meaning that the string must match at the beginning of the history entry.
|
||||
These functions search the history list for entries containing
|
||||
a specific string.
|
||||
Searching may be performed both forward and backward
|
||||
from the current history position.
|
||||
The search may be @dfn{anchored},
|
||||
meaning that the string must match at the beginning of a history entry.
|
||||
@cindex anchored search
|
||||
|
||||
@deftypefun int history_search (const char *string, int direction)
|
||||
Search the history for @var{string}, starting at the current history offset.
|
||||
If @var{direction} is less than 0, then the search is through
|
||||
previous entries, otherwise through subsequent entries.
|
||||
If @var{string} is found, then
|
||||
the current history index is set to that history entry, and the value
|
||||
returned is the offset in the line of the entry where
|
||||
@var{string} was found. Otherwise, nothing is changed, and a -1 is
|
||||
returned.
|
||||
If @var{string} is found, then the current history index is set to
|
||||
that history entry, and @code{history_search}
|
||||
returns the offset in the line of the entry where
|
||||
@var{string} was found.
|
||||
Otherwise, nothing is changed, and this returns -1.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int history_search_prefix (const char *string, int direction)
|
||||
Search the history for @var{string}, starting at the current history
|
||||
offset. The search is anchored: matching lines must begin with
|
||||
@var{string}. If @var{direction} is less than 0, then the search is
|
||||
offset.
|
||||
The search is anchored: matching history entries must begin with @var{string}.
|
||||
If @var{direction} is less than 0, then the search is
|
||||
through previous entries, otherwise through subsequent entries.
|
||||
If @var{string} is found, then the
|
||||
current history index is set to that entry, and the return value is 0.
|
||||
Otherwise, nothing is changed, and a -1 is returned.
|
||||
If @var{string} is found, then the current history index is set to
|
||||
that entry, and the return value is 0.
|
||||
Otherwise, nothing is changed, and this returns -1.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int history_search_pos (const char *string, int direction, int pos)
|
||||
Search for @var{string} in the history list, starting at @var{pos}, an
|
||||
absolute index into the list. If @var{direction} is negative, the search
|
||||
proceeds backward from @var{pos}, otherwise forward. Returns the absolute
|
||||
index of the history element where @var{string} was found, or -1 otherwise.
|
||||
absolute index into the list.
|
||||
If @var{direction} is negative, the search
|
||||
proceeds backward from @var{pos}, otherwise forward.
|
||||
Returns the index in the history list
|
||||
of the history element where @var{string} was
|
||||
found, or -1 otherwise.
|
||||
@end deftypefun
|
||||
|
||||
@node Managing the History File
|
||||
@@ -329,23 +344,34 @@ The History library can read the history from and write it to a file.
|
||||
This section documents the functions for managing a history file.
|
||||
|
||||
@deftypefun int read_history (const char *filename)
|
||||
Add the contents of @var{filename} to the history list, a line at a time.
|
||||
If @var{filename} is @code{NULL}, then read from @file{~/.history}.
|
||||
Add the contents of @var{filename} to the history list, one entry
|
||||
at a time.
|
||||
If @var{filename} is @code{NULL}, this reads from @file{~/.history},
|
||||
if it exists.
|
||||
This attempts to determine whether the history file includes timestamp
|
||||
information, and assigns timestamps to the history entries it reads
|
||||
if so.
|
||||
Returns 0 if successful, or @code{errno} if not.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int read_history_range (const char *filename, int from, int to)
|
||||
Read a range of lines from @var{filename}, adding them to the history list.
|
||||
Start reading at line @var{from} and end at @var{to}.
|
||||
If @var{from} is zero, start at the beginning. If @var{to} is less than
|
||||
@var{from}, then read until the end of the file. If @var{filename} is
|
||||
@code{NULL}, then read from @file{~/.history}. Returns 0 if successful,
|
||||
or @code{errno} if not.
|
||||
If @var{from} is zero, start at the beginning.
|
||||
If @var{to} is less than @var{from}, this reads until the end of the file.
|
||||
This attempts to determine whether the history file includes timestamp
|
||||
information, and assigns timestamps to the history entries it reads
|
||||
if so.
|
||||
If @var{filename} is @code{NULL}, this reads from @file{~/.history},
|
||||
if it exists.
|
||||
Returns 0 if successful, or @code{errno} if not.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun int write_history (const char *filename)
|
||||
Write the current history to @var{filename}, overwriting @var{filename}
|
||||
if necessary.
|
||||
This writes timestamp information if the
|
||||
@code{history_write_timestamps} variable is set to a non-zero value.
|
||||
If @var{filename} is @code{NULL}, then write the history list to
|
||||
@file{~/.history}.
|
||||
Returns 0 on success, or @code{errno} on a read or write error.
|
||||
@@ -353,6 +379,8 @@ Returns 0 on success, or @code{errno} on a read or write error.
|
||||
|
||||
@deftypefun int append_history (int nelements, const char *filename)
|
||||
Append the last @var{nelements} of the history list to @var{filename}.
|
||||
This writes timestamp information if the
|
||||
@code{history_write_timestamps} variable is set to a non-zero value.
|
||||
If @var{filename} is @code{NULL}, then append to @file{~/.history}.
|
||||
Returns 0 on success, or @code{errno} on a read or write error.
|
||||
@end deftypefun
|
||||
@@ -360,7 +388,7 @@ Returns 0 on success, or @code{errno} on a read or write error.
|
||||
@deftypefun int history_truncate_file (const char *filename, int nlines)
|
||||
Truncate the history file @var{filename}, leaving only the last
|
||||
@var{nlines} lines.
|
||||
If @var{filename} is @code{NULL}, then @file{~/.history} is truncated.
|
||||
If @var{filename} is @code{NULL}, this truncates @file{~/.history}.
|
||||
Returns 0 on success, or @code{errno} on failure.
|
||||
@end deftypefun
|
||||
|
||||
@@ -371,7 +399,8 @@ These functions implement history expansion.
|
||||
|
||||
@deftypefun int history_expand (const char *string, char **output)
|
||||
Expand @var{string}, placing the result into @var{output}, a pointer
|
||||
to a string (@pxref{History Interaction}). Returns:
|
||||
to a string (@pxref{History Interaction}).
|
||||
Returns:
|
||||
@table @code
|
||||
@item 0
|
||||
If no expansions took place (or, if the only change in
|
||||
@@ -386,30 +415,33 @@ if the returned line should be displayed, but not executed,
|
||||
as with the @code{:p} modifier (@pxref{Modifiers}).
|
||||
@end table
|
||||
|
||||
If an error occurred in expansion, then @var{output} contains a descriptive
|
||||
error message.
|
||||
If an error occurred during expansion,
|
||||
then @var{output} contains a descriptive error message.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {char *} get_history_event (const char *string, int *cindex, int qchar)
|
||||
Returns the text of the history event beginning at @var{string} +
|
||||
@var{*cindex}. @var{*cindex} is modified to point to after the event
|
||||
specifier. At function entry, @var{cindex} points to the index into
|
||||
@var{string} where the history event specification begins. @var{qchar}
|
||||
@var{*cindex}.
|
||||
Modifies @var{*cindex} to point to after the event specifier.
|
||||
At function entry, @var{cindex} points to the index into @var{string}
|
||||
where the history event specification begins.
|
||||
@var{qchar}
|
||||
is a character that is allowed to end the event specification in addition
|
||||
to the ``normal'' terminating characters.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {char **} history_tokenize (const char *string)
|
||||
Return an array of tokens parsed out of @var{string}, much as the
|
||||
shell might. The tokens are split on the characters in the
|
||||
shell might.
|
||||
The tokens are split on the characters in the
|
||||
@var{history_word_delimiters} variable,
|
||||
and shell quoting conventions are obeyed as described below.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun {char *} history_arg_extract (int first, int last, const char *string)
|
||||
Extract a string segment consisting of the @var{first} through @var{last}
|
||||
arguments present in @var{string}. Arguments are split using
|
||||
@code{history_tokenize}.
|
||||
arguments present in @var{string}.
|
||||
This splits @var{string} into arguments using @code{history_tokenize}.
|
||||
@end deftypefun
|
||||
|
||||
@node History Variables
|
||||
@@ -427,32 +459,35 @@ The number of entries currently stored in the history list.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar int history_max_entries
|
||||
The maximum number of history entries. This must be changed using
|
||||
@code{stifle_history()}.
|
||||
The maximum number of history entries.
|
||||
This must be changed using @code{stifle_history()}.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar int history_write_timestamps
|
||||
If non-zero, timestamps are written to the history file, so they can be
|
||||
preserved between sessions. The default value is 0, meaning that
|
||||
timestamps are not saved.
|
||||
preserved between sessions.
|
||||
The default value is 0, meaning that timestamps are not saved.
|
||||
|
||||
The current timestamp format uses the value of @var{history_comment_char}
|
||||
to delimit timestamp entries in the history file. If that variable does
|
||||
not have a value (the default), timestamps will not be written.
|
||||
to delimit timestamp entries in the history file.
|
||||
If that variable does not have a value (the default), this will not
|
||||
write timestamps.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar char history_expansion_char
|
||||
The character that introduces a history event. The default is @samp{!}.
|
||||
The character that introduces a history event.
|
||||
The default is @samp{!}.
|
||||
Setting this to 0 inhibits history expansion.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar char history_subst_char
|
||||
The character that invokes word substitution if found at the start of
|
||||
a line. The default is @samp{^}.
|
||||
a line.
|
||||
The default is @samp{^}.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar char history_comment_char
|
||||
During tokenization, if this character is seen as the first character
|
||||
During tokenization, if this character appears as the first character
|
||||
of a word, then it and all subsequent characters up to a newline are
|
||||
ignored, suppressing history expansion for the remainder of the line.
|
||||
This is disabled by default.
|
||||
@@ -466,13 +501,14 @@ The default value is @code{" \t\n()<>;&|"}.
|
||||
@deftypevar {char *} history_search_delimiter_chars
|
||||
The list of additional characters which can delimit a history search
|
||||
string, in addition to space, TAB, @samp{:} and @samp{?} in the case of
|
||||
a substring search. The default is empty.
|
||||
a substring search.
|
||||
The default is empty.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar {char *} history_no_expand_chars
|
||||
The list of characters which inhibit history expansion if found immediately
|
||||
following @var{history_expansion_char}. The default is space, tab, newline,
|
||||
carriage return, and @samp{=}.
|
||||
following @var{history_expansion_char}.
|
||||
The default is space, tab, newline, carriage return, and @samp{=}.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar int history_quotes_inhibit_expansion
|
||||
@@ -486,14 +522,18 @@ The default value is 0.
|
||||
|
||||
@deftypevar int history_quoting_state
|
||||
An application may set this variable to indicate that the current line
|
||||
being expanded is subject to existing quoting. If set to @samp{'}, the
|
||||
being expanded is subject to existing quoting.
|
||||
If set to @samp{'}, the
|
||||
history expansion function will assume that the line is single-quoted and
|
||||
inhibit expansion until it reads an unquoted closing single quote; if set
|
||||
to @samp{"}, history expansion will assume the line is double quoted until
|
||||
it reads an unquoted closing double quote. If set to zero, the default,
|
||||
inhibit expansion until it reads an unquoted closing single quote;
|
||||
if set to @samp{"}, history expansion will assume the line is
|
||||
double quoted until it reads an unquoted closing double quote.
|
||||
If set to 0, the default,
|
||||
the history expansion function will assume the line is not quoted and
|
||||
treat quote characters within the line as described above.
|
||||
This is only effective if @var{history_quotes_inhibit_expansion} is set.
|
||||
This is intended for use by applications like Bash which allow
|
||||
quoted strings to span multiple lines.
|
||||
@end deftypevar
|
||||
|
||||
@deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Binary file not shown.
+2352
-1692
File diff suppressed because it is too large
Load Diff
+1819
-1440
File diff suppressed because it is too large
Load Diff
Binary file not shown.
+5689
-5123
File diff suppressed because it is too large
Load Diff
Binary file not shown.
File diff suppressed because it is too large
Load Diff
@@ -13,7 +13,7 @@ This manual describes the GNU Readline Library
|
||||
consistency of user interface across discrete programs which provide
|
||||
a command line interface.
|
||||
|
||||
Copyright @copyright{} 1988--2022 Free Software Foundation, Inc.
|
||||
Copyright @copyright{} 1988--2024 Free Software Foundation, Inc.
|
||||
|
||||
@quotation
|
||||
Permission is granted to copy, distribute and/or modify this document
|
||||
|
||||
+617
-451
File diff suppressed because it is too large
Load Diff
Binary file not shown.
+825
-578
File diff suppressed because it is too large
Load Diff
+715
-564
File diff suppressed because it is too large
Load Diff
Binary file not shown.
+3387
-3097
File diff suppressed because it is too large
Load Diff
@@ -2,8 +2,8 @@
|
||||
@comment %**start of header (This is for running Texinfo on a region.)
|
||||
@setfilename rluserman.info
|
||||
@settitle GNU Readline Library
|
||||
@include version.texi
|
||||
|
||||
@include version.texi
|
||||
@comment %**end of header (This is for running Texinfo on a region.)
|
||||
|
||||
@copying
|
||||
@@ -12,7 +12,7 @@ This manual describes the end user interface of the GNU Readline Library
|
||||
consistency of user interface across discrete programs which provide
|
||||
a command line interface.
|
||||
|
||||
Copyright @copyright{} 1988--2022 Free Software Foundation, Inc.
|
||||
Copyright @copyright{} 1988--2024 Free Software Foundation, Inc.
|
||||
|
||||
@quotation
|
||||
Permission is granted to copy, distribute and/or modify this document
|
||||
|
||||
@@ -40,7 +40,7 @@ typedef void *histdata_t;
|
||||
|
||||
/* Let's not step on anyone else's define for now, since we don't use this yet. */
|
||||
#ifndef HS_HISTORY_VERSION
|
||||
# define HS_HISTORY_VERSION 0x0802 /* History 8.2 */
|
||||
# define HS_HISTORY_VERSION 0x0803 /* History 8.3 */
|
||||
#endif
|
||||
|
||||
/* The structure used to store a history entry. */
|
||||
|
||||
+3
-3
@@ -4855,9 +4855,9 @@ sub update_sec_num {
|
||||
my $ret;
|
||||
|
||||
$level--; # here we start at 0
|
||||
if ($name =~ /^appendix/ || defined(@appendix_sec_num)) {
|
||||
if ($name =~ /^appendix/ || @appendix_sec_num) {
|
||||
# appendix style
|
||||
if (defined(@appendix_sec_num)) {
|
||||
if (@appendix_sec_num) {
|
||||
&incr_sec_num($level, @appendix_sec_num);
|
||||
} else {
|
||||
@appendix_sec_num = ('A', 0, 0, 0);
|
||||
@@ -4865,7 +4865,7 @@ sub update_sec_num {
|
||||
$ret = join('.', @appendix_sec_num[0..$level]);
|
||||
} else {
|
||||
# normal style
|
||||
if (defined(@normal_sec_num))
|
||||
if (@normal_sec_num)
|
||||
{
|
||||
&incr_sec_num($level, @normal_sec_num);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user