2 @setfilename history.info
5 This file documents the GNU History library.
7 Copyright (C) 1988 Free Software Foundation, Inc.
10 Permission is granted to make and distribute verbatim copies of this manual
11 provided the copyright notice and this permission notice are preserved on
15 Permission is granted to process this file through Tex and print the
16 results, provided the printed document carries copying permission notice
17 identical to this one except for the removal of this paragraph (this
18 paragraph not being relevant to the printed manual).
21 Permission is granted to copy and distribute modified versions of this
22 manual under the conditions for verbatim copying, provided also that the
23 GNU Copyright statement is available to the distributee, and provided that
24 the entire resulting derived work is distributed under the terms of a
25 permission notice identical to this one.
27 Permission is granted to copy and distribute translations of this manual
28 into another language, under the above conditions for modified versions.
31 @node Top, Introduction, , (DIR)
33 This document describes the GNU History library, a programming tool that
34 provides a consistent user interface for recalling lines of previously
38 * Introduction:: What is the GNU History library for?
39 * Interactive Use:: What it feels like using History as a user.
40 * Programming:: How to use History in your programs.
43 @node Introduction, Interactive Use, , Top
44 @unnumbered Introduction
46 Many programs read input from the user a line at a time. The GNU history
47 library is able to keep track of those lines, associate arbitrary data with
48 each line, and utilize information from previous lines in making up new
51 The programmer using the History library has available to him functions for
52 remembering lines on a history stack, associating arbitrary data with a
53 line, removing lines from the stack, searching through the stack for a
54 line containing an arbitrary text string, and referencing any line on the
55 stack directly. In addition, a history @dfn{expansion} function is
56 available which provides for a consistent user interface across many
59 The end-user using programs written with the History library has the
60 benifit of a consistent user interface, with a set of well-known commands
61 for manipulating the text of previous lines and using that text in new
62 commands. The basic history manipulation commands are similar to the
63 history substitution used by Csh.
65 If the programmer desires, he can use the Readline library, which includes
66 history manipulation by default, and has the added advantage of Emacs style
69 @node Interactive Use, Programming, Introduction, Top
70 @chapter Interactive Use
72 @section History Expansion
75 The History library provides a history expansion feature that is similar to
76 the history expansion in Csh. The following text describes what syntax
77 features are available.
79 History expansion takes place in two parts. The first is to determine
80 which line from the previous history should be used during substitution.
81 The second is to select portions of that line for inclusion into the
82 current one. The line selected from the previous history is called the
83 @dfn{event}, and the portions of that line that are acted upon are called
84 @dfn{words}. The line is broken into words in the same fashion that the
85 Bash shell does, so that several English (or Unix) words surrounded by
86 quotes are considered as one word.
89 * Event Designators:: How to specify which history line to use.
90 * Word Designators:: Specifying which words are of interest.
91 * Modifiers:: Modifying the results of susbstitution.
94 @node Event Designators, Word Designators, , Interactive Use
95 @subsection Event Designators
96 @cindex event designators
98 An event designator is a reference to a command line entry in the history
104 Start a history subsititution, except when followed by a @key{SPC},
105 @key{TAB}, @key{RET}, @key{=} or @key{(}.
108 Refer to the previous command. This is a synonym for @code{!-1}.
111 Refer to command line @var{n}.
114 Refer to the current command line minus @var{n}.
117 Refer to the most recent command starting with @var{string}.
120 Refer to the most recent command containing @var{string}.
124 @node Word Designators, Modifiers, Event Designators, Interactive Use
125 @subsection Word Designators
127 A @key{:} separates the event specification from the word designator. It
128 can be omitted if the word designator begins with a @key{^}, @key{$},
129 @key{*} or @key{%}. Words are numbered from the beginning of the line,
130 with the first word being denoted by a 0 (zero).
135 The zero'th word. For many applications, this is the command word.
141 The first argument. that is, word 1.
147 The word matched by the most recent @code{?string?} search.
149 @item @var{x}-@var{y}
150 A range of words; @code{-@var{y}} is equivalent to @code{0-@var{y}}.
153 All of the words, excepting the zero'th. This is a synonym for @samp{1-$}.
154 It is not an error to use @samp{*} if there is just one word in the event.
155 The empty string is returned in that case.
159 @node Modifiers, , Word Designators, Interactive Use
160 @subsection Modifiers
162 After the optional word designator, you can add a sequence of one or more
163 of the following modifiers, each preceded by a @key{:}.
168 The entire command line typed so far. This means the current command,
169 not the previous command, so it really isn't a word designator, and doesn't
170 belong in this section.
173 Remove a trailing pathname component, leaving only the head.
176 Remove a trailing suffix of the form ".xxx", leaving the basename (root).
179 Remove all but the suffix (end).
182 Remove all leading pathname components (before the last slash), leaving
186 Print the new command but do not execute it. This takes effect
187 immediately, so it should be the last specifier on the line.
191 @node Programming, , Interactive Use, Top