summaryrefslogtreecommitdiff
path: root/readline/doc/hstech.texinfo
diff options
context:
space:
mode:
Diffstat (limited to 'readline/doc/hstech.texinfo')
-rw-r--r--readline/doc/hstech.texinfo186
1 files changed, 107 insertions, 79 deletions
diff --git a/readline/doc/hstech.texinfo b/readline/doc/hstech.texinfo
index 12fff2c9a75..949444668fc 100644
--- a/readline/doc/hstech.texinfo
+++ b/readline/doc/hstech.texinfo
@@ -1,7 +1,7 @@
@ignore
This file documents the user interface to the GNU History library.
-Copyright (C) 1988, 1991, 1994, 1996 Free Software Foundation, Inc.
+Copyright (C) 1988-2002 Free Software Foundation, Inc.
Authored by Brian Fox and Chet Ramey.
Permission is granted to make and distribute verbatim copies of this manual
@@ -27,9 +27,9 @@ into another language, under the above conditions for modified versions.
@chapter Programming with GNU History
This chapter describes how to interface programs that you write
-with the GNU History Library.
+with the @sc{gnu} History Library.
It should be considered a technical guide.
-For information on the interactive use of GNU History, @pxref{Using
+For information on the interactive use of @sc{gnu} History, @pxref{Using
History Interactively}.
@menu
@@ -43,10 +43,10 @@ History Interactively}.
@node Introduction to History
@section 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.
+Many programs read input from the user a line at a time. The @sc{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
@@ -80,9 +80,11 @@ The history list is an array of history entries. A history entry is
declared as follows:
@example
+typedef void *histdata_t;
+
typedef struct _hist_entry @{
char *line;
- char *data;
+ histdata_t data;
@} HIST_ENTRY;
@end example
@@ -95,12 +97,14 @@ HIST_ENTRY **the_history_list;
The state of the History library is encapsulated into a single structure:
@example
-/* A structure used to pass the current state of the history stuff around. */
+/*
+ * A structure used to pass around the current state of the history.
+ */
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. */
+ 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;
@end example
@@ -112,7 +116,7 @@ stifled.
@section History Functions
This section describes the calling sequence for the various functions
-present in GNU History.
+exported by the @sc{gnu} History library.
@menu
* Initializing History and State Management:: Functions to call when you
@@ -139,12 +143,12 @@ 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.
-@deftypefun void using_history ()
+@deftypefun void using_history (void)
Begin a session in which the history functions might be used. This
initializes the interactive variables.
@end deftypefun
-@deftypefun {HISTORY_STATE *} history_get_history_state ()
+@deftypefun {HISTORY_STATE *} history_get_history_state (void)
Return a structure describing the current state of the input history.
@end deftypefun
@@ -158,7 +162,7 @@ Set the state of the history list according to @var{state}.
These functions manage individual entries on the history list, or set
parameters managing the list itself.
-@deftypefun void add_history (char *string)
+@deftypefun void add_history (const char *string)
Place @var{string} at the end of the history list. The associated data
field (if any) is set to @code{NULL}.
@end deftypefun
@@ -169,13 +173,13 @@ removed element is returned so you can free the line, data,
and containing structure.
@end deftypefun
-@deftypefun {HIST_ENTRY *} replace_history_entry (int which, char *line, char *data)
+@deftypefun {HIST_ENTRY *} replace_history_entry (int which, const char *line, histdata_t data)
Make the history entry at offset @var{which} have @var{line} and @var{data}.
This returns the old entry so you can dispose of the data. In the case
of an invalid @var{which}, a @code{NULL} pointer is returned.
@end deftypefun
-@deftypefun void clear_history ()
+@deftypefun void clear_history (void)
Clear the history list by deleting all the entries.
@end deftypefun
@@ -183,13 +187,14 @@ Clear the history list by deleting all the entries.
Stifle the history list, remembering only the last @var{max} entries.
@end deftypefun
-@deftypefun int unstifle_history ()
-Stop stifling the history. This returns the previous amount the
-history was stifled. The value is positive if the history was
+@deftypefun int unstifle_history (void)
+Stop stifling the history. This returns the previously-set
+maximum number of history entries (as set by @code{stifle_history()}).
+The value is positive if the history was
stifled, negative if it wasn't.
@end deftypefun
-@deftypefun int history_is_stifled ()
+@deftypefun int history_is_stifled (void)
Returns non-zero if the history is stifled, zero if it is not.
@end deftypefun
@@ -199,29 +204,30 @@ Returns non-zero if the history is stifled, zero if it is not.
These functions return information about the entire history list or
individual list entries.
-@deftypefun {HIST_ENTRY **} history_list ()
-Return a @code{NULL} terminated array of @code{HIST_ENTRY} which is the
+@deftypefun {HIST_ENTRY **} history_list (void)
+Return a @code{NULL} terminated array of @code{HIST_ENTRY *} which is the
current input history. Element 0 of this list is the beginning of time.
If there is no history, return @code{NULL}.
@end deftypefun
-@deftypefun int where_history ()
+@deftypefun int where_history (void)
Returns the offset of the current history element.
@end deftypefun
-@deftypefun {HIST_ENTRY *} current_history ()
+@deftypefun {HIST_ENTRY *} current_history (void)
Return the history entry at the current position, as determined by
-@code{where_history ()}. If there is no entry there, return a @code{NULL}
+@code{where_history()}. If there is no entry there, return a @code{NULL}
pointer.
@end deftypefun
@deftypefun {HIST_ENTRY *} history_get (int offset)
Return the history entry at position @var{offset}, starting from
-@code{history_base}. If there is no entry there, or if @var{offset}
+@code{history_base} (@pxref{History Variables}).
+If there is no entry there, or if @var{offset}
is greater than the history length, return a @code{NULL} pointer.
@end deftypefun
-@deftypefun int history_total_bytes ()
+@deftypefun int history_total_bytes (void)
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.
@@ -234,17 +240,19 @@ These functions allow the current index into the history list to be
set or changed.
@deftypefun int history_set_pos (int pos)
-Set the position in the history list to @var{pos}, an absolute index
+Set the current history offset to @var{pos}, an absolute index
into the list.
+Returns 1 on success, 0 if @var{pos} is less than zero or greater
+than the number of history entries.
@end deftypefun
-@deftypefun {HIST_ENTRY *} previous_history ()
+@deftypefun {HIST_ENTRY *} previous_history (void)
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 @code{NULL} pointer.
@end deftypefun
-@deftypefun {HIST_ENTRY *} next_history ()
+@deftypefun {HIST_ENTRY *} next_history (void)
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 @code{NULL} pointer.
@@ -260,26 +268,28 @@ from the current history position. The search may be @dfn{anchored},
meaning that the string must match at the beginning of the history entry.
@cindex anchored search
-@deftypefun int history_search (char *string, int direction)
-Search the history for @var{string}, starting at the current history
-offset. If @var{direction} < 0, then the search is through previous entries,
-else through subsequent. If @var{string} is found, then
+@deftypefun int history_search (const char *string, int direction)
+Search the history for @var{string}, starting at the current history offset.
+If @var{direction} is less than 0, then the search is through
+previous entries, otherwise through subsequent entries.
+If @var{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
@var{string} was found. Otherwise, nothing is changed, and a -1 is
returned.
@end deftypefun
-@deftypefun int history_search_prefix (char *string, int direction)
+@deftypefun int history_search_prefix (const char *string, int direction)
Search the history for @var{string}, starting at the current history
offset. The search is anchored: matching lines must begin with
-@var{string}. If @var{direction} < 0, then the search is through previous
-entries, else through subsequent. If @var{string} is found, then the
+@var{string}. If @var{direction} is less than 0, then the search is
+through previous entries, otherwise through subsequent entries.
+If @var{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.
@end deftypefun
-@deftypefun int history_search_pos (char *string, int direction, int pos)
+@deftypefun int history_search_pos (const char *string, int direction, int pos)
Search for @var{string} in the history list, starting at @var{pos}, an
absolute index into the list. If @var{direction} is negative, the search
proceeds backward from @var{pos}, otherwise forward. Returns the absolute
@@ -292,41 +302,46 @@ index of the history element where @var{string} was found, or -1 otherwise.
The History library can read the history from and write it to a file.
This section documents the functions for managing a history file.
-@deftypefun int read_history (char *filename)
-Add the contents of @var{filename} to the history list, a line at a
-time. If @var{filename} is @code{NULL}, then read from
-@file{~/.history}. Returns 0 if successful, or errno if not.
+@deftypefun int read_history (const char *filename)
+Add the contents of @var{filename} to the history list, a line at a time.
+If @var{filename} is @code{NULL}, then read from @file{~/.history}.
+Returns 0 if successful, or @code{errno} if not.
@end deftypefun
-@deftypefun int read_history_range (char *filename, int from, int to)
+@deftypefun int read_history_range (const char *filename, int from, int to)
Read a range of lines from @var{filename}, adding them to the history list.
-Start reading at line @var{from} and end at @var{to}. If
-@var{from} is zero, start at the beginning. If @var{to} is less than
+Start reading at line @var{from} and end at @var{to}.
+If @var{from} is zero, start at the beginning. If @var{to} is less than
@var{from}, then read until the end of the file. If @var{filename} is
@code{NULL}, then read from @file{~/.history}. Returns 0 if successful,
or @code{errno} if not.
@end deftypefun
-@deftypefun int write_history (char *filename)
+@deftypefun int write_history (const char *filename)
Write the current history to @var{filename}, overwriting @var{filename}
-if necessary. If @var{filename} is
-@code{NULL}, then write the history list to @file{~/.history}. Values
-returned are as in @code{read_history ()}.
+if necessary.
+If @var{filename} is @code{NULL}, then write the history list to
+@file{~/.history}.
+Returns 0 on success, or @code{errno} on a read or write error.
@end deftypefun
-@deftypefun int append_history (int nelements, char *filename)
+@deftypefun int append_history (int nelements, const char *filename)
Append the last @var{nelements} of the history list to @var{filename}.
+If @var{filename} is @code{NULL}, then append to @file{~/.history}.
+Returns 0 on success, or @code{errno} on a read or write error.
@end deftypefun
-@deftypefun int history_truncate_file (char *filename, int nlines)
+@deftypefun int history_truncate_file (const char *filename, int nlines)
Truncate the history file @var{filename}, leaving only the last
@var{nlines} lines.
+If @var{filename} is @code{NULL}, then @file{~/.history} is truncated.
+Returns 0 on success, or @code{errno} on failure.
@end deftypefun
@node History Expansion
@subsection History Expansion
-These functions implement @code{csh}-like history expansion.
+These functions implement history expansion.
@deftypefun int history_expand (char *string, char **output)
Expand @var{string}, placing the result into @var{output}, a pointer
@@ -334,7 +349,7 @@ to a string (@pxref{History Interaction}). Returns:
@table @code
@item 0
If no expansions took place (or, if the only change in
-the text was the de-slashifying of the history expansion
+the text was the removal of escape characters preceding the history expansion
character);
@item 1
if expansions did take place;
@@ -349,12 +364,7 @@ If an error ocurred in expansion, then @var{output} contains a descriptive
error message.
@end deftypefun
-@deftypefun {char *} history_arg_extract (int first, int last, char *string)
-Extract a string segment consisting of the @var{first} through @var{last}
-arguments present in @var{string}. Arguments are broken up as in Bash.
-@end deftypefun
-
-@deftypefun {char *} get_history_event (char *string, int *cindex, int qchar)
+@deftypefun {char *} get_history_event (const char *string, int *cindex, int qchar)
Returns the text of the history event beginning at @var{string} +
@var{*cindex}. @var{*cindex} is modified to point to after the event
specifier. At function entry, @var{cindex} points to the index into
@@ -363,18 +373,24 @@ is a character that is allowed to end the event specification in addition
to the ``normal'' terminating characters.
@end deftypefun
-@deftypefun {char **} history_tokenize (char *string)
+@deftypefun {char **} history_tokenize (const char *string)
Return an array of tokens parsed out of @var{string}, much as the
-shell might. The tokens are split on white space and on the
-characters @code{()<>;&|$}, and shell quoting conventions are
-obeyed.
+shell might. The tokens are split on the characters in the
+@var{history_word_delimiters} variable,
+and shell quoting conventions are obeyed.
+@end deftypefun
+
+@deftypefun {char *} history_arg_extract (int first, int last, const char *string)
+Extract a string segment consisting of the @var{first} through @var{last}
+arguments present in @var{string}. Arguments are split using
+@code{history_tokenize}.
@end deftypefun
@node History Variables
@section History Variables
-This section describes the externally visible variables exported by
-the GNU History Library.
+This section describes the externally-visible variables exported by
+the @sc{gnu} History Library.
@deftypevar int history_base
The logical offset of the first entry in the history list.
@@ -384,13 +400,14 @@ The logical offset of the first entry in the history list.
The number of entries currently stored in the history list.
@end deftypevar
-@deftypevar int max_input_history
+@deftypevar int history_max_entries
The maximum number of history entries. This must be changed using
-@code{stifle_history ()}.
+@code{stifle_history()}.
@end deftypevar
@deftypevar char history_expansion_char
-The character that starts a history event. The default is @samp{!}.
+The character that introduces a history event. The default is @samp{!}.
+Setting this to 0 inhibits history expansion.
@end deftypevar
@deftypevar char history_subst_char
@@ -405,15 +422,20 @@ ignored, suppressing history expansion for the remainder of the line.
This is disabled by default.
@end deftypevar
+@deftypevar {char *} history_word_delimiters
+The characters that separate tokens for @code{history_tokenize()}.
+The default value is @code{" \t\n()<>;&|"}.
+@end deftypevar
+
@deftypevar {char *} history_no_expand_chars
The list of characters which inhibit history expansion if found immediately
-following @var{history_expansion_char}. The default is whitespace and
-@samp{=}.
+following @var{history_expansion_char}. The default is space, tab, newline,
+carriage return, and @samp{=}.
@end deftypevar
@deftypevar {char *} history_search_delimiter_chars
The list of additional characters which can delimit a history search
-string, in addition to whitespace, @samp{:} and @samp{?} in the case of
+string, in addition to space, TAB, @samp{:} and @samp{?} in the case of
a substring search. The default is empty.
@end deftypevar
@@ -422,24 +444,30 @@ If non-zero, single-quoted words are not scanned for the history expansion
character. The default value is 0.
@end deftypevar
-@deftypevar {Function *} history_inhibit_expansion_function
+@deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function
This should be set to the address of a function that takes two arguments:
-a @code{char *} (@var{string}) and an integer index into that string (@var{i}).
+a @code{char *} (@var{string})
+and an @code{int} index into that string (@var{i}).
It should return a non-zero value if the history expansion starting at
@var{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.
+By default, this variable is set to @code{NULL}.
@end deftypevar
@node History Programming Example
@section History Programming Example
-The following program demonstrates simple use of the GNU History Library.
+The following program demonstrates simple use of the @sc{gnu} History Library.
@smallexample
-main ()
+#include <stdio.h>
+#include <readline/history.h>
+
+main (argc, argv)
+ int argc;
+ char **argv;
@{
char line[1024], *t;
int len, done = 0;