+++ /dev/null
-This is Info file history.info, produced by Makeinfo-1.55 from the
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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 provided by `csh'. The following text
-describes the syntax used 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 Bash 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 substitution.
-
-\1f
-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 substitution, except when followed by a space, tab,
- 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 N lines back.
-
-`!string'
- Refer to the most recent command starting with STRING.
-
-`!?string'[`?']
- Refer to the most recent command containing STRING.
-
-`!#'
- The entire command line typed so far.
-
-`^string1^string2^'
- Quick Substitution. Repeat the last command, replacing STRING1
- with STRING2. Equivalent to `!!:s/string1/string2/'.
-
-\1f
-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 `0'th word. For many applications, this is the command word.
-
-`n'
- The Nth 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, except the `0'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.
-
-`x*'
- Abbreviates `x-$'
-
-`x-'
- Abbreviates `x-$' like `x*', but omits the last word.
-
-\1f
-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 :.
-
-`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 trailing suffix.
-
-`t'
- Remove all leading pathname components, leaving the tail.
-
-`p'
- Print the new command but do not execute it.
-
-`s/old/new/'
- Substitute NEW for the first occurrence of OLD in the event line.
- Any delimiter may be used in place of /. The delimiter may be
- quoted in OLD and NEW with a single backslash. If & appears in
- NEW, it is replaced by OLD. A single backslash will quote the &.
- The final delimiter is optional if it is the last character on the
- input line.
-
-`&'
- Repeat the previous substitution.
-
-`g'
- Cause changes to be applied over the entire event line. Used in
- conjunction with `s', as in `gs/old/new/', or with `&'.
-
-\1f
-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 programs that you write with
-the GNU History Library. 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.
-
-\1f
-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 composing new ones.
-
- The programmer using the History library has available functions for
-remembering lines on a history list, associating arbitrary data with a
-line, removing lines from the list, searching through the list for a
-line containing an arbitrary text string, and referencing any line in
-the list directly. In addition, a history "expansion" function is
-available which provides for a consistent user interface across
-different programs.
-
- The user using programs written with the History library has the
-benefit 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 provided 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 command line editing.
-
-\1f
-File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History
-
-History Storage
-===============
-
- The history list is an array of history entries. A history entry is
-declared as follows:
-
- typedef struct _hist_entry {
- char *line;
- char *data;
- } HIST_ENTRY;
-
- The history list itself might therefore be declared as
-
- HIST_ENTRY **the_history_list;
-
- The state of the History library is encapsulated into a single
-structure:
-
- /* A structure used to pass the current state of the history stuff around. */
- typedef struct _hist_state {
- HIST_ENTRY **entries; /* Pointer to the entries themselves. */
- int offset; /* The location pointer within this array. */
- int length; /* Number of elements within this array. */
- int size; /* Number of slots allocated to this array. */
- int flags;
- } HISTORY_STATE;
-
- If the flags member includes `HS_STIFLED', the history has been
-stifled.
-
-\1f
-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.
-
-* Menu:
-
-* Initializing History and State Management:: Functions to call when you
- want to use history in a
- program.
-* History List Management:: Functions used to manage the list
- of history entries.
-* Information About the History List:: Functions returning information about
- the history list.
-* Moving Around the History List:: Functions used to change the position
- in the history list.
-* Searching the History List:: Functions to search the history list
- for entries containing a string.
-* Managing the History File:: Functions that read and write a file
- containing the history list.
-* History Expansion:: Functions to perform csh-like history
- expansion.
-
-\1f
-File: history.info, Node: Initializing History and State Management, Next: History List Management, Up: History Functions
-
-Initializing History and State Management
------------------------------------------
-
- This section describes functions used to initialize and manage the
-state of the History library when you want to use the history functions
-in your program.
-
- - Function: void using_history ()
- Begin a session in which the history functions might be used. This
- initializes the interactive variables.
-
- - Function: HISTORY_STATE * history_get_history_state ()
- Return a structure describing the current state of the input
- history.
-
- - Function: void history_set_history_state (HISTORY_STATE *state)
- Set the state of the history list according to STATE.
-
-\1f
-File: history.info, Node: History List Management, Next: Information About the History List, Prev: Initializing History and State Management, Up: History Functions
-
-History List Management
------------------------
-
- These functions manage individual entries on the history list, or set
-parameters managing the list itself.
-
- - 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: HIST_ENTRY * remove_history (int which)
- Remove history entry at offset WHICH from the history. The
- removed element is returned so you can free the line, data, and
- containing structure.
-
- - Function: HIST_ENTRY * replace_history_entry (int which, char *line,
- char *data)
- Make the history entry at offset 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: void stifle_history (int max)
- Stifle the history list, remembering only the last MAX entries.
-
- - Function: int unstifle_history ()
- Stop stifling the history. This returns the previous amount the
- history was stifled. The value is positive if the history was
- stifled, negative if it wasn't.
-
- - Function: int history_is_stifled ()
- Returns non-zero if the history is stifled, zero if it is not.
-
-\1f
-File: history.info, Node: Information About the History List, Next: Moving Around the History List, Prev: History List Management, Up: History Functions
-
-Information About the History List
-----------------------------------
-
- These functions return information about the entire history list or
-individual list entries.
-
- - 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 where_history ()
- Returns the offset of the current history element.
-
- - Function: HIST_ENTRY * current_history ()
- Return the history entry at the current position, as determined by
- `where_history ()'. If there is no entry there, return a `NULL'
- pointer.
-
- - Function: HIST_ENTRY * history_get (int offset)
- Return the history entry at position OFFSET, starting from
- `history_base'. If there is no entry there, or if OFFSET is
- greater than the history length, return a `NULL' pointer.
-
- - Function: int history_total_bytes ()
- Return the number of bytes that the primary history entries are
- using. This function returns the sum of the lengths of all the
- lines in the history.
-
-\1f
-File: history.info, Node: Moving Around the History List, Next: Searching the History List, Prev: Information About the History List, Up: History Functions
-
-Moving Around the History List
-------------------------------
-
- These functions allow the current index into the history list to be
-set or changed.
-
- - Function: int history_set_pos (int pos)
- Set the position in the history list to POS, an absolute index
- into the list.
-
- - Function: HIST_ENTRY * previous_history ()
- Back up the current 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 the current 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.
-
-\1f
-File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions
-
-Searching the History List
---------------------------
-
- These functions allow searching of the history list for entries
-containing a specific string. Searching may be performed both forward
-and backward from the current history position. The search may be
-"anchored", meaning that the string must match at the beginning of the
-history entry.
-
- - Function: int history_search (char *string, int direction)
- Search the history for STRING, starting at the current history
- offset. If DIRECTION < 0, then the search is through previous
- entries, else through subsequent. If STRING is found, then the
- current history index is set to that history entry, and the value
- returned is the offset in the line of the entry where STRING was
- found. Otherwise, nothing is changed, and a -1 is returned.
-
- - Function: int history_search_prefix (char *string, int direction)
- Search the history for STRING, starting at the current history
- offset. The search is anchored: matching lines must begin with
- STRING. If DIRECTION < 0, then the search is through previous
- entries, else through subsequent. If STRING is found, then the
- current history index is set to that entry, and the return value
- is 0. Otherwise, nothing is changed, and a -1 is returned.
-
- - 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. If DIRECTION is negative, the search
- proceeds backward from POS, otherwise forward. Returns the
- absolute index of the history element where STRING was found, or
- -1 otherwise.
-
-\1f
-File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions
-
-Managing the History File
--------------------------
-
- The History library can read the history from and write it to a file.
-This section documents the functions for managing a history file.
-
- - 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 line FROM and end at TO. 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)
- Write the current history to FILENAME, overwriting FILENAME if
- necessary. If FILENAME is `NULL', then write the history list to
- `~/.history'. Values returned are as in `read_history ()'.
-
- - Function: int append_history (int nelements, char *filename)
- Append the last NELEMENTS of the history list to FILENAME.
-
- - Function: int history_truncate_file (char *filename, int nlines)
- Truncate the history file FILENAME, leaving only the last NLINES
- lines.
-
-\1f
-File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions
-
-History Expansion
------------------
-
- These functions implement `csh'-like history expansion.
-
- - Function: int history_expand (char *string, char **output)
- Expand STRING, placing the result into OUTPUT, a pointer to a
- string (*note History Interaction::.). 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;
-
- `-1'
- if there was an error in expansion;
-
- `2'
- if the returned line should only be displayed, but not
- executed, as with the `:p' modifier (*note Modifiers::.).
-
- 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 Bash.
-
- - Function: char * get_history_event (char *string, int *cindex, int
- qchar)
- Returns the text of the history event beginning at STRING +
- *CINDEX. *CINDEX is modified to point to after the event
- specifier. At function entry, CINDEX points to the index into
- STRING where the history event specification begins. QCHAR is a
- character that is allowed to end the event specification in
- addition to the "normal" terminating characters.
-
- - Function: char ** history_tokenize (char *string)
- Return an array of tokens parsed out of STRING, much as the shell
- might. The tokens are split on white space and on the characters
- `()<>;&|$', and shell quoting conventions are obeyed.
-
-\1f
-File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History
-
-History Variables
-=================
-
- This section describes the externally visible variables exported by
-the GNU History Library.
-
- - Variable: int history_base
- The logical offset of the first entry in the history list.
-
- - Variable: int history_length
- The number of entries currently stored in the history list.
-
- - Variable: int max_input_history
- The maximum number of history entries. This must be changed using
- `stifle_history ()'.
-
- - Variable: char history_expansion_char
- The character that starts a history event. The default is `!'.
-
- - Variable: char history_subst_char
- The character that invokes word substitution if found at the start
- of a line. The default is `^'.
-
- - Variable: char history_comment_char
- During tokenization, if this character is seen as the first
- character of a word, then it and all subsequent characters up to a
- newline are ignored, suppressing history expansion for the
- remainder of the line. This is disabled by default.
-
- - Variable: char * history_no_expand_chars
- The list of characters which inhibit history expansion if found
- immediately following HISTORY_EXPANSION_CHAR. The default is
- whitespace and `='.
-
-\1f
-File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History
-
-History Programming Example
-===========================
-
- The following program demonstrates simple use of the GNU History
-Library.
-
- main ()
- {
- char line[1024], *t;
- int len, done = 0;
-
- line[0] = 0;
-
- using_history ();
- while (!done)
- {
- printf ("history$ ");
- fflush (stdout);
- t = fgets (line, sizeof (line) - 1, stdin);
- if (t && *t)
- {
- len = strlen (t);
- if (t[len - 1] == '\n')
- t[len - 1] = '\0';
- }
-
- if (!t)
- strcpy (line, "quit");
-
- if (line[0])
- {
- char *expansion;
- int result;
-
- result = history_expand (line, &expansion);
- if (result)
- fprintf (stderr, "%s\n", expansion);
-
- if (result < 0 || result == 2)
- {
- free (expansion);
- continue;
- }
-
- add_history (expansion);
- strncpy (line, expansion, sizeof (line) - 1);
- free (expansion);
- }
-
- if (strcmp (line, "quit") == 0)
- done = 1;
- else if (strcmp (line, "save") == 0)
- write_history ("history_file");
- else if (strcmp (line, "read") == 0)
- read_history ("history_file");
- else if (strcmp (line, "list") == 0)
- {
- register HIST_ENTRY **the_list;
- register int i;
-
- the_list = history_list ();
- if (the_list)
- for (i = 0; the_list[i]; i++)
- printf ("%d: %s\n", i + history_base, the_list[i]->line);
- }
- else if (strncmp (line, "delete", 6) == 0)
- {
- int which;
- if ((sscanf (line + 6, "%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");
- }
- }
- }
- }
-
-\1f
-File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU History, Up: Top
-
-Concept Index
-*************
-
-* Menu:
-
-* anchored search: Searching the History List.
-* event designators: Event Designators.
-* expansion: History Interaction.
-* history events: Event Designators.
-* History Searching: Searching the History List.
-
-\1f
-File: history.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top
-
-Function and Variable Index
-***************************
-
-* Menu:
-
-* add_history: History List Management.
-* append_history: Managing the History File.
-* current_history: Information About the History List.
-* get_history_event: History Expansion.
-* history_arg_extract: History Expansion.
-* history_base: History Variables.
-* history_comment_char: History Variables.
-* history_expand: History Expansion.
-* history_expansion_char: History Variables.
-* history_get: Information About the History List.
-* history_get_history_state: Initializing History and State Management.
-* history_is_stifled: History List Management.
-* history_length: History Variables.
-* history_list: Information About the History List.
-* history_no_expand_chars: History Variables.
-* history_search: Searching the History List.
-* history_search_pos: Searching the History List.
-* history_search_prefix: Searching the History List.
-* history_set_history_state: Initializing History and State Management.
-* history_set_pos: Moving Around the History List.
-* history_subst_char: History Variables.
-* history_tokenize: History Expansion.
-* history_total_bytes: Information About the History List.
-* history_truncate_file: Managing the History File.
-* max_input_history: History Variables.
-* next_history: Moving Around the History List.
-* previous_history: Moving Around the History List.
-* read_history: Managing the History File.
-* read_history_range: Managing the History File.
-* remove_history: History List Management.
-* replace_history_entry: History List Management.
-* stifle_history: History List Management.
-* unstifle_history: History List Management.
-* using_history: Initializing History and State Management.
-* where_history: Information About the History List.
-* write_history: Managing the History File.
-
-
-\1f
-Tag Table:
-Node: Top\7f975
-Node: Using History Interactively\7f1569
-Node: History Interaction\7f2077
-Node: Event Designators\7f3122
-Node: Word Designators\7f3952
-Node: Modifiers\7f4936
-Node: Programming with GNU History\7f6065
-Node: Introduction to History\7f6791
-Node: History Storage\7f8112
-Node: History Functions\7f9205
-Node: Initializing History and State Management\7f10176
-Node: History List Management\7f10968
-Node: Information About the History List\7f12396
-Node: Moving Around the History List\7f13702
-Node: Searching the History List\7f14587
-Node: Managing the History File\7f16419
-Node: History Expansion\7f17925
-Node: History Variables\7f19769
-Node: History Programming Example\7f21138
-Node: Concept Index\7f23742
-Node: Function and Variable Index\7f24223
-\1f
-End Tag Table
projects / thirdparty / bash.git / blobdiff