diff options
Diffstat (limited to 'readline/doc/history.info')
| -rw-r--r-- | readline/doc/history.info | 514 |
1 files changed, 0 insertions, 514 deletions
diff --git a/readline/doc/history.info b/readline/doc/history.info deleted file mode 100644 index df7651d..0000000 --- a/readline/doc/history.info +++ /dev/null @@ -1,514 +0,0 @@ -Info file history.info, produced by Makeinfo, -*- Text -*- from input -file hist.texinfo. - - This document describes the GNU History library, a programming tool -that provides a consistent user interface for recalling lines of -previously typed input. - - Copyright (C) 1988, 1991 Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -pare preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Foundation. - - -File: history.info, Node: Top, Next: Using History Interactively, Prev: (DIR), Up: (DIR) - -GNU History Library -******************* - - This document describes the GNU History library, a programming tool -that provides a consistent user interface for recalling lines of -previously typed input. - -* Menu: - -* Using History Interactively:: GNU History User's Manual. -* Programming with GNU History:: GNU History Programmer's Manual. -* Concept Index:: Index of concepts described in this manual. -* Function and Variable Index:: Index of externally visible functions - and variables. - - -File: history.info, Node: Using History Interactively, Next: Programming with GNU History, Prev: Top, Up: Top - -Using History Interactively -*************************** - - This chapter describes how to use the GNU History Library -interactively, from a user's standpoint. It should be considered a -user's guide. For information on using the GNU History Library in -your own programs, *note Programming with GNU History::.. - -* Menu: - -* History Interaction:: What it feels like using History as a user. - - -File: history.info, Node: History Interaction, Up: Using History Interactively - -History Interaction -=================== - - The History library provides a history expansion feature that is -similar to the history expansion in Csh. The following text describes -the sytax that you use to manipulate the history information. - - History expansion takes place in two parts. The first is to -determine which line from the previous history should be used during -substitution. The second is to select portions of that line for -inclusion into the current one. The line selected from the previous -history is called the "event", and the portions of that line that are -acted upon are called "words". The line is broken into words in the -same fashion that the Bash shell does, so that several English (or -Unix) words surrounded by quotes are considered as one word. - -* Menu: - -* Event Designators:: How to specify which history line to use. -* Word Designators:: Specifying which words are of interest. -* Modifiers:: Modifying the results of susbstitution. - - -File: history.info, Node: Event Designators, Next: Word Designators, Up: History Interaction - -Event Designators ------------------ - - An event designator is a reference to a command line entry in the -history list. - -`!' - Start a history subsititution, except when followed by a space, - tab, or the end of the line... = or (. - -`!!' - Refer to the previous command. This is a synonym for `!-1'. - -`!n' - Refer to command line N. - -`!-n' - Refer to the command line N lines back. - -`!string' - Refer to the most recent command starting with STRING. - -`!?string'[`?'] - Refer to the most recent command containing STRING. - - -File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction - -Word Designators ----------------- - - A : separates the event specification from the word designator. It -can be omitted if the word designator begins with a ^, $, * or %. -Words are numbered from the beginning of the line, with the first word -being denoted by a 0 (zero). - -`0 (zero)' - The zero'th word. For many applications, this is the command - word. - -`n' - The N'th word. - -`^' - The first argument. that is, word 1. - -`$' - The last argument. - -`%' - The word matched by the most recent `?string?' search. - -`x-y' - A range of words; `-Y' Abbreviates `0-Y'. - -`*' - All of the words, excepting the zero'th. This is a synonym for - `1-$'. It is not an error to use * if there is just one word in - the event. The empty string is returned in that case. - - -File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction - -Modifiers ---------- - - After the optional word designator, you can add a sequence of one -or more of the following modifiers, each preceded by a :. - -`#' - The entire command line typed so far. This means the current - command, not the previous command, so it really isn't a word - designator, and doesn't belong in this section. - -`h' - Remove a trailing pathname component, leaving only the head. - -`r' - Remove a trailing suffix of the form `.'SUFFIX, leaving the - basename. - -`e' - Remove all but the suffix. - -`t' - Remove all leading pathname components, leaving the tail. - -`p' - Print the new command but do not execute it. - - -File: history.info, Node: Programming with GNU History, Next: Concept Index, Prev: Using History Interactively, Up: Top - -Programming with GNU History -**************************** - - This chapter describes how to interface the GNU History Library with -programs that you write. It should be considered a technical guide. -For information on the interactive use of GNU History, *note Using -History Interactively::.. - -* Menu: - -* Introduction to History:: What is the GNU History library for? -* History Storage:: How information is stored. -* History Functions:: Functions that you can use. -* History Variables:: Variables that control behaviour. -* History Programming Example:: Example of using the GNU History Library. - - -File: history.info, Node: Introduction to History, Next: History Storage, Up: Programming with GNU History - -Introduction to History -======================= - - Many programs read input from the user a line at a time. The GNU -history library is able to keep track of those lines, associate -arbitrary data with each line, and utilize information from previous -lines in making up new ones. - - The programmer using the History library has available to him -functions for remembering lines on a history stack, associating -arbitrary data with a line, removing lines from the stack, searching -through the stack for a line containing an arbitrary text string, and -referencing any line on the stack directly. In addition, a history -"expansion" function is available which provides for a consistent user -interface across many different programs. - - The end-user using programs written with the History library has the -benifit of a consistent user interface, with a set of well-known -commands for manipulating the text of previous lines and using that -text in new commands. The basic history manipulation commands are -similar to the history substitution used by `Csh'. - - If the programmer desires, he can use the Readline library, which -includes some history manipulation by default, and has the added -advantage of Emacs style command line editing. - - -File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History - -History Storage -=============== - - typedef struct _hist_entry { - char *line; - char *data; - } HIST_ENTRY; - - -File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History - -History Functions -================= - - This section describes the calling sequence for the various -functions present in GNU History. - - * Function: void using_history () - Begin a session in which the history functions might be used. - This just initializes the interactive variables. - - * Function: void add_history (CHAR *STRING) - Place STRING at the end of the history list. The associated data - field (if any) is set to `NULL'. - - * Function: int where_history () - Returns the number which says what history element we are now - looking at. - - * Function: int history_set_pos (INT POS) - Set the position in the history list to POS. - - * Function: int history_search_pos (CHAR *STRING, INT DIRECTION, INT - POS) - Search for STRING in the history list, starting at POS, an - absolute index into the list. DIRECTION, if negative, says to - search backwards from POS, else forwards. Returns the absolute - index of the history element where STRING was found, or -1 - otherwise. - - * Function: HIST_ENTRY *remove_history (); - Remove history element WHICH from the history. The removed - element is returned to you so you can free the line, data, and - containing structure. - - * Function: void stifle_history (INT MAX) - Stifle the history list, remembering only MAX number of entries. - - * Function: int unstifle_history (); - Stop stifling the history. This returns the previous amount the - history was stifled by. The value is positive if the history was - stifled, negative if it wasn't. - - * Function: int read_history (CHAR *FILENAME) - Add the contents of FILENAME to the history list, a line at a - time. If FILENAME is `NULL', then read from `~/.history'. - Returns 0 if successful, or errno if not. - - * Function: int read_history_range (CHAR *FILENAME, INT FROM, INT TO) - Read a range of lines from FILENAME, adding them to the history - list. Start reading at the FROM'th line and end at the TO'th. If - FROM is zero, start at the beginning. If TO is less than FROM, - then read until the end of the file. If FILENAME is `NULL', then - read from `~/.history'. Returns 0 if successful, or `errno' if - not. - - * Function: int write_history (CHAR *FILENAME) - Append the current history to FILENAME. If FILENAME is `NULL', - then append the history list to `~/.history'. Values returned - are as in `read_history ()'. - - * Function: int append_history (INT NELEMENTS, CHAR *FILENAME) - Append NELEMENT entries to FILENAME. The entries appended are - from the end of the list minus NELEMENTS up to the end of the - list. - - * Function: HIST_ENTRY *replace_history_entry () - Make the history entry at WHICH have LINE and DATA. This returns - the old entry so you can dispose of the data. In the case of an - invalid WHICH, a `NULL' pointer is returned. - - * Function: HIST_ENTRY *current_history () - Return the history entry at the current position, as determined by - `history_offset'. If there is no entry there, return a `NULL' - pointer. - - * Function: HIST_ENTRY *previous_history () - Back up HISTORY_OFFSET to the previous history entry, and return a - pointer to that entry. If there is no previous entry, return a - `NULL' pointer. - - * Function: HIST_ENTRY *next_history () - Move `history_offset' forward to the next history entry, and - return the a pointer to that entry. If there is no next entry, - return a `NULL' pointer. - - * Function: HIST_ENTRY **history_list () - Return a `NULL' terminated array of `HIST_ENTRY' which is the - current input history. Element 0 of this list is the beginning - of time. If there is no history, return `NULL'. - - * Function: int history_search (CHAR *STRING, INT DIRECTION) - Search the history for STRING, starting at `history_offset'. If - DIRECTION < 0, then the search is through previous entries, else - through subsequent. If STRING is found, then `current_history - ()' is the history entry, and the value of this function is the - offset in the line of that history entry that the STRING was - found in. Otherwise, nothing is changed, and a -1 is returned. - - * Function: int history_expand (CHAR *STRING, CHAR **OUTPUT) - Expand STRING, placing the result into OUTPUT, a pointer to a - string. Returns: - - `0' - If no expansions took place (or, if the only change in the - text was the de-slashifying of the history expansion - character), - - `1' - if expansions did take place, or - - `-1' - if there was an error in expansion. - - If an error ocurred in expansion, then OUTPUT contains a - descriptive error message. - - * Function: char *history_arg_extract (INT FIRST, INT LAST, CHAR - *STRING) - Extract a string segment consisting of the FIRST through LAST - arguments present in STRING. Arguments are broken up as in the - GNU Bash shell. - - * Function: int history_total_bytes (); - Return the number of bytes that the primary history entries are - using. This just adds up the lengths of `the_history->lines'. - - -File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History - -History Variables -================= - - This section describes the variables in GNU History that are -externally visible. - - * Variable: int history_base - For convenience only. You set this when interpreting history - commands. It is the logical offset of the first history element. - - -File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History - -History Programming Example -=========================== - - The following snippet of code demonstrates simple use of the GNU -History Library. - - main () - { - char line[1024], *t; - int done = 0; - - line[0] = 0; - - while (!done) - { - fprintf (stdout, "history%% "); - t = gets (line); - - if (!t) - strcpy (line, "quit"); - - if (line[0]) - { - char *expansion; - int result; - - using_history (); - - result = history_expand (line, &expansion); - strcpy (line, expansion); - free (expansion); - if (result) - fprintf (stderr, "%s\n", line); - - if (result < 0) - continue; - - add_history (line); - } - - if (strcmp (line, "quit") == 0) done = 1; - if (strcmp (line, "save") == 0) write_history (0); - if (strcmp (line, "read") == 0) read_history (0); - if (strcmp (line, "list") == 0) - { - register HIST_ENTRY **the_list = history_list (); - register int i; - - if (the_list) - for (i = 0; the_list[i]; i++) - fprintf (stdout, "%d: %s\n", - i + history_base, the_list[i]->line); - } - if (strncmp (line, "delete", strlen ("delete")) == 0) - { - int which; - if ((sscanf (line + strlen ("delete"), "%d", &which)) == 1) - { - HIST_ENTRY *entry = remove_history (which); - if (!entry) - fprintf (stderr, "No such entry %d\n", which); - else - { - free (entry->line); - free (entry); - } - } - else - { - fprintf (stderr, "non-numeric arg given to `delete'\n"); - } - } - } - } - - -File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU History, Up: Top - -Concept Index -************* - -* Menu: - -* event designators: Event Designators. -* expansion: History Interaction. - - -File: history.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top - -Function and Variable Index -*************************** - -* Menu: - -* HIST_ENTRY **history_list: History Functions. -* HIST_ENTRY *current_history: History Functions. -* HIST_ENTRY *next_history: History Functions. -* HIST_ENTRY *previous_history: History Functions. -* HIST_ENTRY *remove_history: History Functions. -* HIST_ENTRY *replace_history_entry: History Functions. -* char *history_arg_extract: History Functions. -* int append_history: History Functions. -* int history_base: History Variables. -* int history_expand: History Functions. -* int history_search: History Functions. -* int history_search_pos: History Functions. -* int history_set_pos: History Functions. -* int history_total_bytes: History Functions. -* int read_history: History Functions. -* int read_history_range: History Functions. -* int unstifle_history: History Functions. -* int where_history: History Functions. -* int write_history: History Functions. -* void add_history: History Functions. -* void stifle_history: History Functions. -* void using_history: History Functions. - - - -Tag Table: -Node: Top973 -Node: Using History Interactively1567 -Node: History Interaction2075 -Node: Event Designators3127 -Node: Word Designators3770 -Node: Modifiers4676 -Node: Programming with GNU History5425 -Node: Introduction to History6152 -Node: History Storage7502 -Node: History Functions7766 -Node: History Variables13063 -Node: History Programming Example13499 -Node: Concept Index15744 -Node: Function and Variable Index16030 - -End Tag Table |