octave-nkf: readline/doc/history.info comparison

comparison readline/doc/history.info @ 2996:9d4e3a9de17e

[project @ 1997-05-22 20:58:07 by jwe]

author	jwe
date	Thu, 22 May 1997 20:59:27 +0000
parents
children

comparison

equal deleted inserted replaced

-:953ce4558485
+:9d4e3a9de17e
+This is Info file history.info, produced by Makeinfo-1.55 from the
+input file /usr/homes/chet/src/bash/readline-src/doc/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, 1993, 1995, 1996 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
+Interactive History Expansion
+=============================
+The History library provides a history expansion feature that is
+similar to the history expansion provided by `csh'.  This section
+describes the syntax used to manipulate the history information.
+History expansions introduce words from the history list into the
+input stream, making it easy to repeat commands, insert the arguments
+to a previous command into the current input line, or fix errors in
+previous commands quickly.
+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".  Various "modifiers" are available to
+manipulate the selected 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.  History expansions
+are introduced by the appearance of the history expansion character,
+which is `!' by default.
+* 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.
+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 (.
+`!N'
+Refer to command line N.
+`!-N'
+Refer to the command N lines back.
+`!!'
+Refer to the previous command.  This is a synonym for `!-1'.
+`!STRING'
+Refer to the most recent command starting with STRING.
+`!?STRING[?]'
+Refer to the most recent command containing STRING.  The trailing
+`?' may be omitted if the STRING is followed immediately by a
+newline.
+`^STRING1^STRING2^'
+Quick Substitution.  Repeat the last command, replacing STRING1
+with STRING2.  Equivalent to `!!:s/STRING1/STRING2/'.
+`!#'
+The entire command line typed so far.
+File: history.info,  Node: Word Designators,  Next: Modifiers,  Prev: Event Designators,  Up: History Interaction
+Word Designators
+----------------
+Word designators are used to select desired words from the event.  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 0 (zero).  Words are inserted into the current
+line separated by single spaces.
+`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.
+If a word designator is supplied without an event specification, the
+previous command is used as the event.
+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.
+`t'
+Remove all leading  pathname  components, leaving the tail.
+`r'
+Remove a trailing suffix of the form `.SUFFIX', leaving the
+basename.
+`e'
+Remove all but the trailing suffix.
+`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 `&'.
+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.
+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.
+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.
+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.
+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.
+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 clear_history ()
+Clear the history list by deleting all the entries.
+- 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.
+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.
+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.
+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.
+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.
+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.
+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 `='.
+- Variable: char * history_search_delimiter_chars
+The list of additional characters which can delimit a history
+search string, in addition to whitespace, `:' and `?' in the case
+of a substring search.  The default is empty.
+- Variable: int history_quotes_inhibit_expansion
+If non-zero, single-quoted words are not scanned for the history
+expansion character.  The default value is 0.
+- Variable: Function * history_inhibit_expansion_function
+This should be set to the address of a function that takes two
+arguments: a `char *' (STRING) and an integer index into that
+string (I).  It should return a non-zero value if the history
+expansion starting at STRING[I] should not be performed; zero if
+the expansion should be done.  It is intended for use by
+applications like Bash that use the history expansion character
+for additional purposes.  By default, this variable is set to NULL.
+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");
+}
+}
+}
+}
+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.
+* history events:                       Event Designators.
+* history expansion:                    History Interaction.
+* History Searching:                    Searching the History List.
+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.
+* clear_history:                        History List Management.
+* 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_inhibit_expansion_function:   History Variables.
+* history_is_stifled:                   History List Management.
+* history_length:                       History Variables.
+* history_list:                         Information About the History List.
+* history_no_expand_chars:              History Variables.
+* history_quotes_inhibit_expansion:     History Variables.
+* history_search:                       Searching the History List.
+* history_search_delimiter_chars:       History Variables.
+* 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.
+Tag Table:
+Node: Top1035
+Node: Using History Interactively1629
+Node: History Interaction2137
+Node: Event Designators3614
+Node: Word Designators4537
+Node: Modifiers5786
+Node: Programming with GNU History6924
+Node: Introduction to History7650
+Node: History Storage8971
+Node: History Functions10064
+Node: Initializing History and State Management11035
+Node: History List Management11827
+Node: Information About the History List13348
+Node: Moving Around the History List14654
+Node: Searching the History List15539
+Node: Managing the History File17371
+Node: History Expansion18877
+Node: History Variables20721
+Node: History Programming Example23039
+Node: Concept Index25643
+Node: Function and Variable Index26124
+End Tag Table

Mercurial > octave-nkf

comparison readline/doc/history.info @ 2996:9d4e3a9de17e