7a67dd45 |
1 | \input texinfo.tex |
2 | @setfilename history.info |
3 | |
4 | @ifinfo |
5 | This file documents the GNU History library. |
6 | |
7 | Copyright (C) 1988 Free Software Foundation, Inc. |
8 | Authored by Brian Fox. |
9 | |
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 |
12 | all copies. |
13 | |
14 | @ignore |
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). |
19 | @end ignore |
20 | |
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. |
26 | |
27 | Permission is granted to copy and distribute translations of this manual |
28 | into another language, under the above conditions for modified versions. |
29 | @end ifinfo |
30 | |
31 | @node Top, Introduction, , (DIR) |
32 | |
33 | This document describes the GNU History library, a programming tool that |
34 | provides a consistent user interface for recalling lines of previously |
35 | typed input. |
36 | |
37 | @menu |
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. |
41 | @end menu |
42 | |
43 | @node Introduction, Interactive Use, , Top |
44 | @unnumbered Introduction |
45 | |
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 |
49 | ones. |
50 | |
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 |
57 | different programs. |
58 | |
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. |
64 | |
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 |
67 | command line editing. |
68 | |
69 | @node Interactive Use, Programming, Introduction, Top |
70 | @chapter Interactive Use |
71 | |
72 | @section History Expansion |
73 | @cindex expansion |
74 | |
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. |
78 | |
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. |
87 | |
88 | @menu |
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. |
92 | @end menu |
93 | |
94 | @node Event Designators, Word Designators, , Interactive Use |
95 | @subsection Event Designators |
96 | @cindex event designators |
97 | |
98 | An event designator is a reference to a command line entry in the history |
99 | list. |
100 | |
101 | @table @var |
102 | |
103 | @item ! |
104 | Start a history subsititution, except when followed by a @key{SPC}, |
105 | @key{TAB}, @key{RET}, @key{=} or @key{(}. |
106 | |
107 | @item !! |
108 | Refer to the previous command. This is a synonym for @code{!-1}. |
109 | |
110 | @item !n |
111 | Refer to command line @var{n}. |
112 | |
113 | @item !-n |
114 | Refer to the current command line minus @var{n}. |
115 | |
116 | @item !string |
117 | Refer to the most recent command starting with @var{string}. |
118 | |
119 | @item !?string[?] |
120 | Refer to the most recent command containing @var{string}. |
121 | |
122 | @end table |
123 | |
124 | @node Word Designators, Modifiers, Event Designators, Interactive Use |
125 | @subsection Word Designators |
126 | |
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). |
131 | |
132 | @table @asis |
133 | |
134 | @item @var{0} (zero) |
135 | The zero'th word. For many applications, this is the command word. |
136 | |
137 | @item n |
138 | The @var{n}'th word. |
139 | |
140 | @item @var{^} |
141 | The first argument. that is, word 1. |
142 | |
143 | @item @var{$} |
144 | The last argument. |
145 | |
146 | @item @var{%} |
147 | The word matched by the most recent @code{?string?} search. |
148 | |
149 | @item @var{x}-@var{y} |
150 | A range of words; @code{-@var{y}} is equivalent to @code{0-@var{y}}. |
151 | |
152 | @item @var{*} |
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. |
156 | |
157 | @end table |
158 | |
159 | @node Modifiers, , Word Designators, Interactive Use |
160 | @subsection Modifiers |
161 | |
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{:}. |
164 | |
165 | @table @code |
166 | |
167 | @item # |
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. |
171 | |
172 | @item h |
173 | Remove a trailing pathname component, leaving only the head. |
174 | |
175 | @item r |
176 | Remove a trailing suffix of the form ".xxx", leaving the basename. |
177 | |
178 | @item e |
179 | Remove all but the suffix. |
180 | |
181 | @item t |
182 | Remove all leading pathname components, leaving the tail. |
183 | |
184 | @item p |
185 | Print the new command but do not execute it. This takes effect |
186 | immediately, so it should be the last specifier on the line. |
187 | |
188 | @end table |
189 | |
190 | @node Programming, , Interactive Use, Top |
191 | @chapter Programming |
192 | |
193 | @bye |
194 | |