# HG changeset patch
# User jwe
# Date 865635119 0
# Node ID 639808eda8ebc46874cfb90094f8f1e442823d46
# Parent d2046ca9a380291cccddb66d398252cba1610355
[project @ 1997-06-06 22:11:57 by jwe]
diff --git a/readline/doc/history.dvi b/readline/doc/history.dvi
deleted file mode 100644
index 4a4673cd2221a39e2375d04dc427408231bd24c9..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
GIT binary patch
literal 0
Hc$@
-
-
-
-This document describes the GNU History library, a programming tool that
-provides a consistent user interface for recalling lines of previously
-typed input.
-
-
-Published by the Free Software Foundation
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are 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.
-
-
-Copyright (C) 1989, 1991 Free Software Foundation, Inc.
-
-
-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,
-see section Programming with GNU History.
-
-
-The History library provides a history expansion feature that is similar
-to the history expansion provided by
-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.
-
-
-An event designator is a reference to a command line entry in the
-history list.
-
-
-
-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.
-
-
-If a word designator is supplied without an event specification, the
-previous command is used as the event.
-
-
-After the optional word designator, you can add a sequence of one or more
-of the following modifiers, each preceded by a `:'.
-
-
-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, see section Using History Interactively.
-
-
-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
-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.
-
-
-The history list is an array of history entries. A history entry is
-declared as follows:
-
-
-The history list itself might therefore be declared as
-
-
-The state of the History library is encapsulated into a single structure:
-
-
-If the flags member includes
-This section describes the calling sequence for the various functions
-present in GNU History.
-
-
-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.
-
-
-GNU History Library
-Edition 2.1, for
-History Library
Version 2.1.March 1996
-Brian Fox, Free Software Foundation
-Chet Ramey, Case Western Reserve University
-
-675 Massachusetts Avenue,
-Cambridge, MA 02139 USA
-
-Using History Interactively
-
-Interactive History Expansion
-
-csh
. This section
-describes the syntax used to manipulate the history information.
-
-Event Designators
-
-
-
-
-
-
-
-!
-!n
-!-n
-!!
-!string
-!?string[?]
-^string1^string2^
-!!:s/string1/string2/
.
-
-!#
-Word Designators
-
-
-
-
-
-0 (zero)
-0
th word. For many applications, this is the command word.
-
-n
-^
-$
-%
-x-y
-*
-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*
-x-
-Modifiers
-
-
-
-
-
-
-
-h
-t
-r
-e
-p
-s/old/new/
-&
-g
-gs/old/new/
,
-or with `&'.
-
-Programming with GNU History
-
-Introduction to History
-
-csh
.
-
-History Storage
-
-
-typedef struct _hist_entry {
- char *line;
- char *data;
-} HIST_ENTRY;
-
-
-
-HIST_ENTRY **the_history_list;
-
-
-
-/* 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;
-
-
-HS_STIFLED
, the history has been
-stifled.
-
-History Functions
-
-Initializing History and State Management
-
-
-
-
-These functions manage individual entries on the history list, or set -parameters managing the list itself. - -
--
NULL
.
--
-
NULL
pointer is returned.
--
-
-
-
-These functions return information about the entire history list or -individual list entries. - -
--
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
.
--
-
where_history ()
. If there is no entry there, return a NULL
-pointer.
--
history_base
. If there is no entry there, or if offset
-is greater than the history length, return a NULL
pointer.
--
-These functions allow the current index into the history list to be -set or changed. - -
--
-
NULL
pointer.
--
NULL
pointer.
--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. - - -
--
-
-
-The History library can read the history from and write it to a file. -This section documents the functions for managing a history file. - -
--
NULL
, then read from
-`~/.history'. Returns 0 if successful, or errno if not.
--
NULL
, then read from `~/.history'. Returns 0 if successful,
-or errno
if not.
--
NULL
, then write the history list to `~/.history'. Values
-returned are as in read_history ()
.
--
-
-These functions implement csh
-like history expansion.
-
-
-
0
-1
--1
-2
-:p
modifier (see section Modifiers).
--If an error ocurred in expansion, then output contains a descriptive -error message. -
-
-
-
()<>;&|$
, and shell quoting conventions are
-obeyed.
--This section describes the externally visible variables exported by -the GNU History Library. - -
--
-
-
stifle_history ()
.
--
-
-
-
-
-
-
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.
--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"); - } - } - } -} -- - - -
-
-
-This document was generated on 16 April 1997 using the -texi2html -translator version 1.51.
- -