1 This is Info file history.info, produced by Makeinfo-1.55 from the
2 input file hist.texinfo.
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 this
11 manual provided the copyright notice and this permission notice pare
12 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 your
51 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 provided by `csh'. The following text
65 describes the syntax used 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 Bash does, so that several English (or Unix) words
74 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 substitution.
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 substitution, except when followed by a space, tab,
93 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 N lines back.
105 Refer to the most recent command starting with STRING.
108 Refer to the most recent command containing STRING.
111 The entire command line typed so far.
114 Quick Substitution. Repeat the last command, replacing STRING1
115 with STRING2. Equivalent to `!!:s/string1/string2/'.
118 File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction
123 A : separates the event specification from the word designator. It
124 can be omitted if the word designator begins with a ^, $, * or %.
125 Words are numbered from the beginning of the line, with the first word
126 being denoted by a 0 (zero).
129 The `0'th word. For many applications, this is the command word.
135 The first argument; that is, word 1.
141 The word matched by the most recent `?string?' search.
144 A range of words; `-Y' abbreviates `0-Y'.
147 All of the words, except the `0'th. This is a synonym for `1-$'.
148 It is not an error to use * if there is just one word in the event;
149 the empty string is returned in that case.
155 Abbreviates `x-$' like `x*', but omits the last word.
158 File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction
163 After the optional word designator, you can add a sequence of one or
164 more of the following modifiers, each preceded by a :.
167 Remove a trailing pathname component, leaving only the head.
170 Remove a trailing suffix of the form `.'SUFFIX, leaving the
174 Remove all but the trailing suffix.
177 Remove all leading pathname components, leaving the tail.
180 Print the new command but do not execute it.
183 Substitute NEW for the first occurrence of OLD in the event line.
184 Any delimiter may be used in place of /. The delimiter may be
185 quoted in OLD and NEW with a single backslash. If & appears in
186 NEW, it is replaced by OLD. A single backslash will quote the &.
187 The final delimiter is optional if it is the last character on the
191 Repeat the previous substitution.
194 Cause changes to be applied over the entire event line. Used in
195 conjunction with `s', as in `gs/old/new/', or with `&'.
198 File: history.info, Node: Programming with GNU History, Next: Concept Index, Prev: Using History Interactively, Up: Top
200 Programming with GNU History
201 ****************************
203 This chapter describes how to interface programs that you write with
204 the GNU History Library. It should be considered a technical guide.
205 For information on the interactive use of GNU History, *note Using
206 History Interactively::..
210 * Introduction to History:: What is the GNU History library for?
211 * History Storage:: How information is stored.
212 * History Functions:: Functions that you can use.
213 * History Variables:: Variables that control behaviour.
214 * History Programming Example:: Example of using the GNU History Library.
217 File: history.info, Node: Introduction to History, Next: History Storage, Up: Programming with GNU History
219 Introduction to History
220 =======================
222 Many programs read input from the user a line at a time. The GNU
223 History library is able to keep track of those lines, associate
224 arbitrary data with each line, and utilize information from previous
225 lines in composing new ones.
227 The programmer using the History library has available functions for
228 remembering lines on a history list, associating arbitrary data with a
229 line, removing lines from the list, searching through the list for a
230 line containing an arbitrary text string, and referencing any line in
231 the list directly. In addition, a history "expansion" function is
232 available which provides for a consistent user interface across
235 The user using programs written with the History library has the
236 benefit of a consistent user interface with a set of well-known
237 commands for manipulating the text of previous lines and using that text
238 in new commands. The basic history manipulation commands are similar to
239 the history substitution provided by `csh'.
241 If the programmer desires, he can use the Readline library, which
242 includes some history manipulation by default, and has the added
243 advantage of command line editing.
246 File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History
251 The history list is an array of history entries. A history entry is
254 typedef struct _hist_entry {
259 The history list itself might therefore be declared as
261 HIST_ENTRY **the_history_list;
263 The state of the History library is encapsulated into a single
266 /* A structure used to pass the current state of the history stuff around. */
267 typedef struct _hist_state {
268 HIST_ENTRY **entries; /* Pointer to the entries themselves. */
269 int offset; /* The location pointer within this array. */
270 int length; /* Number of elements within this array. */
271 int size; /* Number of slots allocated to this array. */
275 If the flags member includes `HS_STIFLED', the history has been
279 File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History
284 This section describes the calling sequence for the various functions
285 present in GNU History.
289 * Initializing History and State Management:: Functions to call when you
290 want to use history in a
292 * History List Management:: Functions used to manage the list
294 * Information About the History List:: Functions returning information about
296 * Moving Around the History List:: Functions used to change the position
298 * Searching the History List:: Functions to search the history list
299 for entries containing a string.
300 * Managing the History File:: Functions that read and write a file
301 containing the history list.
302 * History Expansion:: Functions to perform csh-like history
306 File: history.info, Node: Initializing History and State Management, Next: History List Management, Up: History Functions
308 Initializing History and State Management
309 -----------------------------------------
311 This section describes functions used to initialize and manage the
312 state of the History library when you want to use the history functions
315 - Function: void using_history ()
316 Begin a session in which the history functions might be used. This
317 initializes the interactive variables.
319 - Function: HISTORY_STATE * history_get_history_state ()
320 Return a structure describing the current state of the input
323 - Function: void history_set_history_state (HISTORY_STATE *state)
324 Set the state of the history list according to STATE.
327 File: history.info, Node: History List Management, Next: Information About the History List, Prev: Initializing History and State Management, Up: History Functions
329 History List Management
330 -----------------------
332 These functions manage individual entries on the history list, or set
333 parameters managing the list itself.
335 - Function: void add_history (char *string)
336 Place STRING at the end of the history list. The associated data
337 field (if any) is set to `NULL'.
339 - Function: HIST_ENTRY * remove_history (int which)
340 Remove history entry at offset WHICH from the history. The
341 removed element is returned so you can free the line, data, and
342 containing structure.
344 - Function: HIST_ENTRY * replace_history_entry (int which, char *line,
346 Make the history entry at offset WHICH have LINE and DATA. This
347 returns the old entry so you can dispose of the data. In the case
348 of an invalid WHICH, a `NULL' pointer is returned.
350 - Function: void stifle_history (int max)
351 Stifle the history list, remembering only the last MAX entries.
353 - Function: int unstifle_history ()
354 Stop stifling the history. This returns the previous amount the
355 history was stifled. The value is positive if the history was
356 stifled, negative if it wasn't.
358 - Function: int history_is_stifled ()
359 Returns non-zero if the history is stifled, zero if it is not.
362 File: history.info, Node: Information About the History List, Next: Moving Around the History List, Prev: History List Management, Up: History Functions
364 Information About the History List
365 ----------------------------------
367 These functions return information about the entire history list or
368 individual list entries.
370 - Function: HIST_ENTRY ** history_list ()
371 Return a `NULL' terminated array of `HIST_ENTRY' which is the
372 current input history. Element 0 of this list is the beginning of
373 time. If there is no history, return `NULL'.
375 - Function: int where_history ()
376 Returns the offset of the current history element.
378 - Function: HIST_ENTRY * current_history ()
379 Return the history entry at the current position, as determined by
380 `where_history ()'. If there is no entry there, return a `NULL'
383 - Function: HIST_ENTRY * history_get (int offset)
384 Return the history entry at position OFFSET, starting from
385 `history_base'. If there is no entry there, or if OFFSET is
386 greater than the history length, return a `NULL' pointer.
388 - Function: int history_total_bytes ()
389 Return the number of bytes that the primary history entries are
390 using. This function returns the sum of the lengths of all the
391 lines in the history.
394 File: history.info, Node: Moving Around the History List, Next: Searching the History List, Prev: Information About the History List, Up: History Functions
396 Moving Around the History List
397 ------------------------------
399 These functions allow the current index into the history list to be
402 - Function: int history_set_pos (int pos)
403 Set the position in the history list to POS, an absolute index
406 - Function: HIST_ENTRY * previous_history ()
407 Back up the current history offset to the previous history entry,
408 and return a pointer to that entry. If there is no previous
409 entry, return a `NULL' pointer.
411 - Function: HIST_ENTRY * next_history ()
412 Move the current history offset forward to the next history entry,
413 and return the a pointer to that entry. If there is no next
414 entry, return a `NULL' pointer.
417 File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions
419 Searching the History List
420 --------------------------
422 These functions allow searching of the history list for entries
423 containing a specific string. Searching may be performed both forward
424 and backward from the current history position. The search may be
425 "anchored", meaning that the string must match at the beginning of the
428 - Function: int history_search (char *string, int direction)
429 Search the history for STRING, starting at the current history
430 offset. If DIRECTION < 0, then the search is through previous
431 entries, else through subsequent. If STRING is found, then the
432 current history index is set to that history entry, and the value
433 returned is the offset in the line of the entry where STRING was
434 found. Otherwise, nothing is changed, and a -1 is returned.
436 - Function: int history_search_prefix (char *string, int direction)
437 Search the history for STRING, starting at the current history
438 offset. The search is anchored: matching lines must begin with
439 STRING. If DIRECTION < 0, then the search is through previous
440 entries, else through subsequent. If STRING is found, then the
441 current history index is set to that entry, and the return value
442 is 0. Otherwise, nothing is changed, and a -1 is returned.
444 - Function: int history_search_pos (char *string, int direction, int
446 Search for STRING in the history list, starting at POS, an
447 absolute index into the list. If DIRECTION is negative, the search
448 proceeds backward from POS, otherwise forward. Returns the
449 absolute index of the history element where STRING was found, or
453 File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions
455 Managing the History File
456 -------------------------
458 The History library can read the history from and write it to a file.
459 This section documents the functions for managing a history file.
461 - Function: int read_history (char *filename)
462 Add the contents of FILENAME to the history list, a line at a
463 time. If FILENAME is `NULL', then read from `~/.history'.
464 Returns 0 if successful, or errno if not.
466 - Function: int read_history_range (char *filename, int from, int to)
467 Read a range of lines from FILENAME, adding them to the history
468 list. Start reading at line FROM and end at TO. If FROM is zero,
469 start at the beginning. If TO is less than FROM, then read until
470 the end of the file. If FILENAME is `NULL', then read from
471 `~/.history'. Returns 0 if successful, or `errno' if not.
473 - Function: int write_history (char *filename)
474 Write the current history to FILENAME, overwriting FILENAME if
475 necessary. If FILENAME is `NULL', then write the history list to
476 `~/.history'. Values returned are as in `read_history ()'.
478 - Function: int append_history (int nelements, char *filename)
479 Append the last NELEMENTS of the history list to FILENAME.
481 - Function: int history_truncate_file (char *filename, int nlines)
482 Truncate the history file FILENAME, leaving only the last NLINES
486 File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions
491 These functions implement `csh'-like history expansion.
493 - Function: int history_expand (char *string, char **output)
494 Expand STRING, placing the result into OUTPUT, a pointer to a
495 string (*note History Interaction::.). Returns:
497 If no expansions took place (or, if the only change in the
498 text was the de-slashifying of the history expansion
502 if expansions did take place;
505 if there was an error in expansion;
508 if the returned line should only be displayed, but not
509 executed, as with the `:p' modifier (*note Modifiers::.).
511 If an error ocurred in expansion, then OUTPUT contains a
512 descriptive error message.
514 - Function: char * history_arg_extract (int first, int last, char
516 Extract a string segment consisting of the FIRST through LAST
517 arguments present in STRING. Arguments are broken up as in Bash.
519 - Function: char * get_history_event (char *string, int *cindex, int
521 Returns the text of the history event beginning at STRING +
522 *CINDEX. *CINDEX is modified to point to after the event
523 specifier. At function entry, CINDEX points to the index into
524 STRING where the history event specification begins. QCHAR is a
525 character that is allowed to end the event specification in
526 addition to the "normal" terminating characters.
528 - Function: char ** history_tokenize (char *string)
529 Return an array of tokens parsed out of STRING, much as the shell
530 might. The tokens are split on white space and on the characters
531 `()<>;&|$', and shell quoting conventions are obeyed.
534 File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History
539 This section describes the externally visible variables exported by
540 the GNU History Library.
542 - Variable: int history_base
543 The logical offset of the first entry in the history list.
545 - Variable: int history_length
546 The number of entries currently stored in the history list.
548 - Variable: int max_input_history
549 The maximum number of history entries. This must be changed using
552 - Variable: char history_expansion_char
553 The character that starts a history event. The default is `!'.
555 - Variable: char history_subst_char
556 The character that invokes word substitution if found at the start
557 of a line. The default is `^'.
559 - Variable: char history_comment_char
560 During tokenization, if this character is seen as the first
561 character of a word, then it and all subsequent characters up to a
562 newline are ignored, suppressing history expansion for the
563 remainder of the line. This is disabled by default.
565 - Variable: char * history_no_expand_chars
566 The list of characters which inhibit history expansion if found
567 immediately following HISTORY_EXPANSION_CHAR. The default is
571 File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History
573 History Programming Example
574 ===========================
576 The following program demonstrates simple use of the GNU History
589 printf ("history$ ");
591 t = fgets (line, sizeof (line) - 1, stdin);
595 if (t[len - 1] == '\n')
600 strcpy (line, "quit");
607 result = history_expand (line, &expansion);
609 fprintf (stderr, "%s\n", expansion);
611 if (result < 0 || result == 2)
617 add_history (expansion);
618 strncpy (line, expansion, sizeof (line) - 1);
622 if (strcmp (line, "quit") == 0)
624 else if (strcmp (line, "save") == 0)
625 write_history ("history_file");
626 else if (strcmp (line, "read") == 0)
627 read_history ("history_file");
628 else if (strcmp (line, "list") == 0)
630 register HIST_ENTRY **the_list;
633 the_list = history_list ();
635 for (i = 0; the_list[i]; i++)
636 printf ("%d: %s\n", i + history_base, the_list[i]->line);
638 else if (strncmp (line, "delete", 6) == 0)
641 if ((sscanf (line + 6, "%d", &which)) == 1)
643 HIST_ENTRY *entry = remove_history (which);
645 fprintf (stderr, "No such entry %d\n", which);
654 fprintf (stderr, "non-numeric arg given to `delete'\n");
661 File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU History, Up: Top
668 * anchored search: Searching the History List.
669 * event designators: Event Designators.
670 * expansion: History Interaction.
671 * history events: Event Designators.
672 * History Searching: Searching the History List.
675 File: history.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top
677 Function and Variable Index
678 ***************************
682 * add_history: History List Management.
683 * append_history: Managing the History File.
684 * current_history: Information About the History List.
685 * get_history_event: History Expansion.
686 * history_arg_extract: History Expansion.
687 * history_base: History Variables.
688 * history_comment_char: History Variables.
689 * history_expand: History Expansion.
690 * history_expansion_char: History Variables.
691 * history_get: Information About the History List.
692 * history_get_history_state: Initializing History and State Management.
693 * history_is_stifled: History List Management.
694 * history_length: History Variables.
695 * history_list: Information About the History List.
696 * history_no_expand_chars: History Variables.
697 * history_search: Searching the History List.
698 * history_search_pos: Searching the History List.
699 * history_search_prefix: Searching the History List.
700 * history_set_history_state: Initializing History and State Management.
701 * history_set_pos: Moving Around the History List.
702 * history_subst_char: History Variables.
703 * history_tokenize: History Expansion.
704 * history_total_bytes: Information About the History List.
705 * history_truncate_file: Managing the History File.
706 * max_input_history: History Variables.
707 * next_history: Moving Around the History List.
708 * previous_history: Moving Around the History List.
709 * read_history: Managing the History File.
710 * read_history_range: Managing the History File.
711 * remove_history: History List Management.
712 * replace_history_entry: History List Management.
713 * stifle_history: History List Management.
714 * unstifle_history: History List Management.
715 * using_history: Initializing History and State Management.
716 * where_history: Information About the History List.
717 * write_history: Managing the History File.
723 Node: Using History Interactively
\7f1569
724 Node: History Interaction
\7f2077
725 Node: Event Designators
\7f3122
726 Node: Word Designators
\7f3952
727 Node: Modifiers
\7f4936
728 Node: Programming with GNU History
\7f6065
729 Node: Introduction to History
\7f6791
730 Node: History Storage
\7f8112
731 Node: History Functions
\7f9205
732 Node: Initializing History and State Management
\7f10176
733 Node: History List Management
\7f10968
734 Node: Information About the History List
\7f12396
735 Node: Moving Around the History List
\7f13702
736 Node: Searching the History List
\7f14587
737 Node: Managing the History File
\7f16419
738 Node: History Expansion
\7f17925
739 Node: History Variables
\7f19769
740 Node: History Programming Example
\7f21138
741 Node: Concept Index
\7f23742
742 Node: Function and Variable Index
\7f24223