1 Info file history.info, produced by Makeinfo, -*- Text -*- from input
4 This document describes the GNU History library, a programming tool
5 that provides a consistent user interface for recalling lines of
6 previously typed input.
8 Copyright (C) 1988, 1991 Free Software Foundation, Inc.
10 Permission is granted to make and distribute verbatim copies of
11 this manual provided the copyright notice and this permission notice
12 pare preserved on all copies.
14 Permission is granted to copy and distribute modified versions of
15 this manual under the conditions for verbatim copying, provided that
16 the entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
19 Permission is granted to copy and distribute translations of this
20 manual into another language, under the above conditions for modified
21 versions, except that this permission notice may be stated in a
22 translation approved by the Foundation.
25 File: history.info, Node: Top, Next: Using History Interactively, Prev: (DIR), Up: (DIR)
30 This document describes the GNU History library, a programming tool
31 that provides a consistent user interface for recalling lines of
32 previously typed input.
36 * Using History Interactively:: GNU History User's Manual.
37 * Programming with GNU History:: GNU History Programmer's Manual.
38 * Concept Index:: Index of concepts described in this manual.
39 * Function and Variable Index:: Index of externally visible functions
43 File: history.info, Node: Using History Interactively, Next: Programming with GNU History, Prev: Top, Up: Top
45 Using History Interactively
46 ***************************
48 This chapter describes how to use the GNU History Library
49 interactively, from a user's standpoint. It should be considered a
50 user's guide. For information on using the GNU History Library in
51 your own programs, *note Programming with GNU History::..
55 * History Interaction:: What it feels like using History as a user.
58 File: history.info, Node: History Interaction, Up: Using History Interactively
63 The History library provides a history expansion feature that is
64 similar to the history expansion in Csh. The following text describes
65 the sytax that you use to manipulate the history information.
67 History expansion takes place in two parts. The first is to
68 determine which line from the previous history should be used during
69 substitution. The second is to select portions of that line for
70 inclusion into the current one. The line selected from the previous
71 history is called the "event", and the portions of that line that are
72 acted upon are called "words". The line is broken into words in the
73 same fashion that the Bash shell does, so that several English (or
74 Unix) words surrounded by quotes are considered as one word.
78 * Event Designators:: How to specify which history line to use.
79 * Word Designators:: Specifying which words are of interest.
80 * Modifiers:: Modifying the results of susbstitution.
83 File: history.info, Node: Event Designators, Next: Word Designators, Up: History Interaction
88 An event designator is a reference to a command line entry in the
92 Start a history subsititution, except when followed by a space,
93 tab, or the end of the line... = or (.
96 Refer to the previous command. This is a synonym for `!-1'.
99 Refer to command line N.
102 Refer to the command line N lines back.
105 Refer to the most recent command starting with STRING.
108 Refer to the most recent command containing STRING.
111 File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
116 A : separates the event specification from the word designator. It
117 can be omitted if the word designator begins with a ^, $, * or %.
118 Words are numbered from the beginning of the line, with the first word
119 being denoted by a 0 (zero).
122 The zero'th word. For many applications, this is the command
129 The first argument. that is, word 1.
135 The word matched by the most recent `?string?' search.
138 A range of words; `-Y' Abbreviates `0-Y'.
141 All of the words, excepting the zero'th. This is a synonym for
142 `1-$'. It is not an error to use * if there is just one word in
143 the event. The empty string is returned in that case.
146 File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
151 After the optional word designator, you can add a sequence of one
152 or more of the following modifiers, each preceded by a :.
155 The entire command line typed so far. This means the current
156 command, not the previous command, so it really isn't a word
157 designator, and doesn't belong in this section.
160 Remove a trailing pathname component, leaving only the head.
163 Remove a trailing suffix of the form `.'SUFFIX, leaving the
167 Remove all but the suffix.
170 Remove all leading pathname components, leaving the tail.
173 Print the new command but do not execute it.
176 File: history.info, Node: Programming with GNU History, Next: Concept Index, Prev: Using History Interactively, Up: Top
178 Programming with GNU History
179 ****************************
181 This chapter describes how to interface the GNU History Library with
182 programs that you write. It should be considered a technical guide.
183 For information on the interactive use of GNU History, *note Using
184 History Interactively::..
188 * Introduction to History:: What is the GNU History library for?
189 * History Storage:: How information is stored.
190 * History Functions:: Functions that you can use.
191 * History Variables:: Variables that control behaviour.
192 * History Programming Example:: Example of using the GNU History Library.
195 File: history.info, Node: Introduction to History, Next: History Storage, Up: Programming with GNU History
197 Introduction to History
198 =======================
200 Many programs read input from the user a line at a time. The GNU
201 history library is able to keep track of those lines, associate
202 arbitrary data with each line, and utilize information from previous
203 lines in making up new ones.
205 The programmer using the History library has available to him
206 functions for remembering lines on a history stack, associating
207 arbitrary data with a line, removing lines from the stack, searching
208 through the stack for a line containing an arbitrary text string, and
209 referencing any line on the stack directly. In addition, a history
210 "expansion" function is available which provides for a consistent user
211 interface across many different programs.
213 The end-user using programs written with the History library has the
214 benifit of a consistent user interface, with a set of well-known
215 commands for manipulating the text of previous lines and using that
216 text in new commands. The basic history manipulation commands are
217 similar to the history substitution used by `Csh'.
219 If the programmer desires, he can use the Readline library, which
220 includes some history manipulation by default, and has the added
221 advantage of Emacs style command line editing.
224 File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History
229 typedef struct _hist_entry {
235 File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History
240 This section describes the calling sequence for the various
241 functions present in GNU History.
243 * Function: void using_history ()
244 Begin a session in which the history functions might be used.
245 This just initializes the interactive variables.
247 * Function: void add_history (CHAR *STRING)
248 Place STRING at the end of the history list. The associated data
249 field (if any) is set to `NULL'.
251 * Function: int where_history ()
252 Returns the number which says what history element we are now
255 * Function: int history_set_pos (INT POS)
256 Set the position in the history list to POS.
258 * Function: int history_search_pos (CHAR *STRING, INT DIRECTION, INT
260 Search for STRING in the history list, starting at POS, an
261 absolute index into the list. DIRECTION, if negative, says to
262 search backwards from POS, else forwards. Returns the absolute
263 index of the history element where STRING was found, or -1
266 * Function: HIST_ENTRY *remove_history ();
267 Remove history element WHICH from the history. The removed
268 element is returned to you so you can free the line, data, and
269 containing structure.
271 * Function: void stifle_history (INT MAX)
272 Stifle the history list, remembering only MAX number of entries.
274 * Function: int unstifle_history ();
275 Stop stifling the history. This returns the previous amount the
276 history was stifled by. The value is positive if the history was
277 stifled, negative if it wasn't.
279 * Function: int read_history (CHAR *FILENAME)
280 Add the contents of FILENAME to the history list, a line at a
281 time. If FILENAME is `NULL', then read from `~/.history'.
282 Returns 0 if successful, or errno if not.
284 * Function: int read_history_range (CHAR *FILENAME, INT FROM, INT TO)
285 Read a range of lines from FILENAME, adding them to the history
286 list. Start reading at the FROM'th line and end at the TO'th. If
287 FROM is zero, start at the beginning. If TO is less than FROM,
288 then read until the end of the file. If FILENAME is `NULL', then
289 read from `~/.history'. Returns 0 if successful, or `errno' if
292 * Function: int write_history (CHAR *FILENAME)
293 Append the current history to FILENAME. If FILENAME is `NULL',
294 then append the history list to `~/.history'. Values returned
295 are as in `read_history ()'.
297 * Function: int append_history (INT NELEMENTS, CHAR *FILENAME)
298 Append NELEMENT entries to FILENAME. The entries appended are
299 from the end of the list minus NELEMENTS up to the end of the
302 * Function: HIST_ENTRY *replace_history_entry ()
303 Make the history entry at WHICH have LINE and DATA. This returns
304 the old entry so you can dispose of the data. In the case of an
305 invalid WHICH, a `NULL' pointer is returned.
307 * Function: HIST_ENTRY *current_history ()
308 Return the history entry at the current position, as determined by
309 `history_offset'. If there is no entry there, return a `NULL'
312 * Function: HIST_ENTRY *previous_history ()
313 Back up HISTORY_OFFSET to the previous history entry, and return a
314 pointer to that entry. If there is no previous entry, return a
317 * Function: HIST_ENTRY *next_history ()
318 Move `history_offset' forward to the next history entry, and
319 return the a pointer to that entry. If there is no next entry,
320 return a `NULL' pointer.
322 * Function: HIST_ENTRY **history_list ()
323 Return a `NULL' terminated array of `HIST_ENTRY' which is the
324 current input history. Element 0 of this list is the beginning
325 of time. If there is no history, return `NULL'.
327 * Function: int history_search (CHAR *STRING, INT DIRECTION)
328 Search the history for STRING, starting at `history_offset'. If
329 DIRECTION < 0, then the search is through previous entries, else
330 through subsequent. If STRING is found, then `current_history
331 ()' is the history entry, and the value of this function is the
332 offset in the line of that history entry that the STRING was
333 found in. Otherwise, nothing is changed, and a -1 is returned.
335 * Function: int history_expand (CHAR *STRING, CHAR **OUTPUT)
336 Expand STRING, placing the result into OUTPUT, a pointer to a
340 If no expansions took place (or, if the only change in the
341 text was the de-slashifying of the history expansion
345 if expansions did take place, or
348 if there was an error in expansion.
350 If an error ocurred in expansion, then OUTPUT contains a
351 descriptive error message.
353 * Function: char *history_arg_extract (INT FIRST, INT LAST, CHAR
355 Extract a string segment consisting of the FIRST through LAST
356 arguments present in STRING. Arguments are broken up as in the
359 * Function: int history_total_bytes ();
360 Return the number of bytes that the primary history entries are
361 using. This just adds up the lengths of `the_history->lines'.
364 File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History
369 This section describes the variables in GNU History that are
372 * Variable: int history_base
373 For convenience only. You set this when interpreting history
374 commands. It is the logical offset of the first history element.
377 File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History
379 History Programming Example
380 ===========================
382 The following snippet of code demonstrates simple use of the GNU
394 fprintf (stdout, "history%% ");
398 strcpy (line, "quit");
407 result = history_expand (line, &expansion);
408 strcpy (line, expansion);
411 fprintf (stderr, "%s\n", line);
419 if (strcmp (line, "quit") == 0) done = 1;
420 if (strcmp (line, "save") == 0) write_history (0);
421 if (strcmp (line, "read") == 0) read_history (0);
422 if (strcmp (line, "list") == 0)
424 register HIST_ENTRY **the_list = history_list ();
428 for (i = 0; the_list[i]; i++)
429 fprintf (stdout, "%d: %s\n",
430 i + history_base, the_list[i]->line);
432 if (strncmp (line, "delete", strlen ("delete")) == 0)
435 if ((sscanf (line + strlen ("delete"), "%d", &which)) == 1)
437 HIST_ENTRY *entry = remove_history (which);
439 fprintf (stderr, "No such entry %d\n", which);
448 fprintf (stderr, "non-numeric arg given to `delete'\n");
455 File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU History, Up: Top
462 * event designators: Event Designators.
463 * expansion: History Interaction.
466 File: history.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top
468 Function and Variable Index
469 ***************************
473 * HIST_ENTRY **history_list: History Functions.
474 * HIST_ENTRY *current_history: History Functions.
475 * HIST_ENTRY *next_history: History Functions.
476 * HIST_ENTRY *previous_history: History Functions.
477 * HIST_ENTRY *remove_history: History Functions.
478 * HIST_ENTRY *replace_history_entry: History Functions.
479 * char *history_arg_extract: History Functions.
480 * int append_history: History Functions.
481 * int history_base: History Variables.
482 * int history_expand: History Functions.
483 * int history_search: History Functions.
484 * int history_search_pos: History Functions.
485 * int history_set_pos: History Functions.
486 * int history_total_bytes: History Functions.
487 * int read_history: History Functions.
488 * int read_history_range: History Functions.
489 * int unstifle_history: History Functions.
490 * int where_history: History Functions.
491 * int write_history: History Functions.
492 * void add_history: History Functions.
493 * void stifle_history: History Functions.
494 * void using_history: History Functions.
500 Node: Using History Interactively
\7f1567
501 Node: History Interaction
\7f2075
502 Node: Event Designators
\7f3127
503 Node: Word Designators
\7f3770
504 Node: Modifiers
\7f4676
505 Node: Programming with GNU History
\7f5425
506 Node: Introduction to History
\7f6152
507 Node: History Storage
\7f7502
508 Node: History Functions
\7f7766
509 Node: History Variables
\7f13063
510 Node: History Programming Example
\7f13499
511 Node: Concept Index
\7f15744
512 Node: Function and Variable Index
\7f16030