Commit | Line | Data |
---|---|---|
be9485d5 SG |
1 | @ignore |
2 | This file documents the user interface to the GNU History library. | |
3 | ||
4 | Copyright (C) 1988, 1991 Free Software Foundation, Inc. | |
5 | Authored by Brian Fox. | |
6 | ||
7 | Permission is granted to make and distribute verbatim copies of this manual | |
8 | provided the copyright notice and this permission notice are preserved on | |
9 | all copies. | |
10 | ||
11 | Permission is granted to process this file through Tex and print the | |
12 | results, provided the printed document carries copying permission notice | |
13 | identical to this one except for the removal of this paragraph (this | |
14 | paragraph not being relevant to the printed manual). | |
15 | ||
16 | Permission is granted to copy and distribute modified versions of this | |
17 | manual under the conditions for verbatim copying, provided also that the | |
18 | GNU Copyright statement is available to the distributee, and provided that | |
19 | the entire resulting derived work is distributed under the terms of a | |
20 | permission notice identical to this one. | |
21 | ||
22 | Permission is granted to copy and distribute translations of this manual | |
23 | into another language, under the above conditions for modified versions. | |
24 | @end ignore | |
25 | ||
26 | @node Programming with GNU History | |
27 | @chapter Programming with GNU History | |
28 | ||
29 | This chapter describes how to interface the GNU History Library with | |
30 | programs that you write. It should be considered a technical guide. | |
31 | For information on the interactive use of GNU History, @pxref{Using | |
32 | History Interactively}. | |
33 | ||
34 | @menu | |
35 | * Introduction to History:: What is the GNU History library for? | |
36 | * History Storage:: How information is stored. | |
37 | * History Functions:: Functions that you can use. | |
38 | * History Variables:: Variables that control behaviour. | |
39 | * History Programming Example:: Example of using the GNU History Library. | |
40 | @end menu | |
41 | ||
42 | @node Introduction to History | |
43 | @section Introduction to History | |
44 | ||
45 | Many programs read input from the user a line at a time. The GNU history | |
46 | library is able to keep track of those lines, associate arbitrary data with | |
47 | each line, and utilize information from previous lines in making up new | |
48 | ones. | |
49 | ||
50 | The programmer using the History library has available to him functions | |
51 | for remembering lines on a history stack, associating arbitrary data | |
52 | with a line, removing lines from the stack, searching through the stack | |
53 | for a line containing an arbitrary text string, and referencing any line | |
54 | on the stack directly. In addition, a history @dfn{expansion} function | |
55 | is available which provides for a consistent user interface across many | |
56 | different programs. | |
57 | ||
58 | The end-user using programs written with the History library has the | |
59 | benifit of a consistent user interface, with a set of well-known | |
60 | commands for manipulating the text of previous lines and using that text | |
61 | in new commands. The basic history manipulation commands are similar to | |
62 | the history substitution used by @code{Csh}. | |
63 | ||
64 | If the programmer desires, he can use the Readline library, which | |
65 | includes some history manipulation by default, and has the added | |
66 | advantage of Emacs style command line editing. | |
67 | ||
68 | @node History Storage | |
69 | @section History Storage | |
70 | ||
71 | @example | |
72 | typedef struct _hist_entry @{ | |
73 | char *line; | |
74 | char *data; | |
75 | @} HIST_ENTRY; | |
76 | @end example | |
77 | ||
78 | @node History Functions | |
79 | @section History Functions | |
80 | ||
81 | This section describes the calling sequence for the various functions | |
82 | present in GNU History. | |
83 | ||
84 | @defun {void using_history} () | |
85 | Begin a session in which the history functions might be used. This | |
86 | just initializes the interactive variables. | |
87 | @end defun | |
88 | ||
89 | @defun {void add_history} (char *string) | |
90 | Place @var{string} at the end of the history list. The associated data | |
91 | field (if any) is set to @code{NULL}. | |
92 | @end defun | |
93 | ||
94 | @defun {int where_history} () | |
95 | Returns the number which says what history element we are now looking | |
96 | at. | |
97 | @end defun | |
98 | ||
99 | @defun {int history_set_pos} (int pos) | |
100 | Set the position in the history list to @var{pos}. | |
101 | @end defun | |
102 | ||
103 | @defun {int history_search_pos} (char *string, int direction, int pos) | |
104 | Search for @var{string} in the history list, starting at @var{pos}, an | |
105 | absolute index into the list. @var{direction}, if negative, says to search | |
106 | backwards from @var{pos}, else forwards. Returns the absolute index of | |
107 | the history element where @var{string} was found, or -1 otherwise. | |
108 | @end defun | |
109 | ||
110 | @defun {HIST_ENTRY *remove_history} (); | |
111 | Remove history element @var{which} from the history. The removed | |
112 | element is returned to you so you can free the line, data, | |
113 | and containing structure. | |
114 | @end defun | |
115 | ||
116 | @defun {void stifle_history} (int max) | |
117 | Stifle the history list, remembering only @var{max} number of entries. | |
118 | @end defun | |
119 | ||
120 | @defun {int unstifle_history} (); | |
121 | Stop stifling the history. This returns the previous amount the | |
122 | history was stifled by. The value is positive if the history was | |
123 | stifled, negative if it wasn't. | |
124 | @end defun | |
125 | ||
126 | @defun {int read_history} (char *filename) | |
127 | Add the contents of @var{filename} to the history list, a line at a | |
128 | time. If @var{filename} is @code{NULL}, then read from | |
129 | @file{~/.history}. Returns 0 if successful, or errno if not. | |
130 | @end defun | |
131 | ||
132 | @defun {int read_history_range} (char *filename, int from, int to) | |
133 | Read a range of lines from @var{filename}, adding them to the history list. | |
134 | Start reading at the @var{from}'th line and end at the @var{to}'th. If | |
135 | @var{from} is zero, start at the beginning. If @var{to} is less than | |
136 | @var{from}, then read until the end of the file. If @var{filename} is | |
137 | @code{NULL}, then read from @file{~/.history}. Returns 0 if successful, | |
138 | or @code{errno} if not. | |
139 | @end defun | |
140 | ||
141 | @defun {int write_history} (char *filename) | |
142 | Append the current history to @var{filename}. If @var{filename} is | |
143 | @code{NULL}, then append the history list to @file{~/.history}. Values | |
144 | returned are as in @code{read_history ()}. | |
145 | @end defun | |
146 | ||
147 | @defun {int append_history} (int nelements, char *filename) | |
148 | Append @var{nelement} entries to @var{filename}. The entries appended | |
149 | are from the end of the list minus @var{nelements} up to the end of the | |
150 | list. | |
151 | @end defun | |
152 | ||
153 | @defun {HIST_ENTRY *replace_history_entry} () | |
154 | Make the history entry at @var{which} have @var{line} and @var{data}. | |
155 | This returns the old entry so you can dispose of the data. In the case | |
156 | of an invalid @var{which}, a @code{NULL} pointer is returned. | |
157 | @end defun | |
158 | ||
159 | @defun {HIST_ENTRY *current_history} () | |
160 | Return the history entry at the current position, as determined by | |
161 | @code{history_offset}. If there is no entry there, return a @code{NULL} | |
162 | pointer. | |
163 | @end defun | |
164 | ||
165 | @defun {HIST_ENTRY *previous_history} () | |
166 | Back up @var{history_offset} to the previous history entry, and return a | |
167 | pointer to that entry. If there is no previous entry, return a | |
168 | @code{NULL} pointer. | |
169 | @end defun | |
170 | ||
171 | @defun {HIST_ENTRY *next_history} () | |
172 | Move @code{history_offset} forward to the next history entry, and return | |
173 | the a pointer to that entry. If there is no next entry, return a | |
174 | @code{NULL} pointer. | |
175 | @end defun | |
176 | ||
177 | @defun {HIST_ENTRY **history_list} () | |
178 | Return a @code{NULL} terminated array of @code{HIST_ENTRY} which is the | |
179 | current input history. Element 0 of this list is the beginning of time. | |
180 | If there is no history, return @code{NULL}. | |
181 | @end defun | |
182 | ||
183 | @defun {int history_search} (char *string, int direction) | |
184 | Search the history for @var{string}, starting at @code{history_offset}. | |
185 | If @var{direction} < 0, then the search is through previous entries, | |
186 | else through subsequent. If @var{string} is found, then | |
187 | @code{current_history ()} is the history entry, and the value of this | |
188 | function is the offset in the line of that history entry that the | |
189 | @var{string} was found in. Otherwise, nothing is changed, and a -1 is | |
190 | returned. | |
191 | @end defun | |
192 | ||
193 | @defun {int history_expand} (char *string, char **output) | |
194 | Expand @var{string}, placing the result into @var{output}, a pointer | |
195 | to a string. Returns: | |
196 | @table @code | |
197 | @item 0 | |
198 | If no expansions took place (or, if the only change in | |
199 | the text was the de-slashifying of the history expansion | |
200 | character), | |
201 | @item 1 | |
202 | if expansions did take place, or | |
203 | @item -1 | |
204 | if there was an error in expansion. | |
205 | @end table | |
206 | ||
207 | If an error ocurred in expansion, then @var{output} contains a descriptive | |
208 | error message. | |
209 | @end defun | |
210 | ||
211 | @defun {char *history_arg_extract} (int first, int last, char *string) | |
212 | Extract a string segment consisting of the @var{first} through @var{last} | |
213 | arguments present in @var{string}. Arguments are broken up as in | |
214 | the GNU Bash shell. | |
215 | @end defun | |
216 | ||
217 | @defun {int history_total_bytes} (); | |
218 | Return the number of bytes that the primary history entries are using. | |
219 | This just adds up the lengths of @code{the_history->lines}. | |
220 | @end defun | |
221 | ||
222 | @node History Variables | |
223 | @section History Variables | |
224 | ||
225 | This section describes the variables in GNU History that are externally | |
226 | visible. | |
227 | ||
228 | @defvar {int history_base} | |
229 | For convenience only. You set this when interpreting history commands. | |
230 | It is the logical offset of the first history element. | |
231 | @end defvar | |
232 | ||
233 | @node History Programming Example | |
234 | @section History Programming Example | |
235 | ||
236 | The following snippet of code demonstrates simple use of the GNU History | |
237 | Library. | |
238 | ||
239 | @smallexample | |
240 | main () | |
241 | @{ | |
242 | char line[1024], *t; | |
243 | int done = 0; | |
244 | ||
245 | line[0] = 0; | |
246 | ||
247 | while (!done) | |
248 | @{ | |
249 | fprintf (stdout, "history%% "); | |
250 | t = gets (line); | |
251 | ||
252 | if (!t) | |
253 | strcpy (line, "quit"); | |
254 | ||
255 | if (line[0]) | |
256 | @{ | |
257 | char *expansion; | |
258 | int result; | |
259 | ||
260 | using_history (); | |
261 | ||
262 | result = history_expand (line, &expansion); | |
263 | strcpy (line, expansion); | |
264 | free (expansion); | |
265 | if (result) | |
266 | fprintf (stderr, "%s\n", line); | |
267 | ||
268 | if (result < 0) | |
269 | continue; | |
270 | ||
271 | add_history (line); | |
272 | @} | |
273 | ||
274 | if (strcmp (line, "quit") == 0) done = 1; | |
275 | if (strcmp (line, "save") == 0) write_history (0); | |
276 | if (strcmp (line, "read") == 0) read_history (0); | |
277 | if (strcmp (line, "list") == 0) | |
278 | @{ | |
279 | register HIST_ENTRY **the_list = history_list (); | |
280 | register int i; | |
281 | ||
282 | if (the_list) | |
283 | for (i = 0; the_list[i]; i++) | |
284 | fprintf (stdout, "%d: %s\n", | |
285 | i + history_base, the_list[i]->line); | |
286 | @} | |
287 | if (strncmp (line, "delete", strlen ("delete")) == 0) | |
288 | @{ | |
289 | int which; | |
290 | if ((sscanf (line + strlen ("delete"), "%d", &which)) == 1) | |
291 | @{ | |
292 | HIST_ENTRY *entry = remove_history (which); | |
293 | if (!entry) | |
294 | fprintf (stderr, "No such entry %d\n", which); | |
295 | else | |
296 | @{ | |
297 | free (entry->line); | |
298 | free (entry); | |
299 | @} | |
300 | @} | |
301 | else | |
302 | @{ | |
303 | fprintf (stderr, "non-numeric arg given to `delete'\n"); | |
304 | @} | |
305 | @} | |
306 | @} | |
307 | @} | |
308 | @end smallexample | |
309 | ||
310 | ||
311 |