readline/doc/hstech.texinfo

   1 @ignore
   2 This file documents the user interface to the GNU History library.
   3
   4 Copyright (C) 1988, 1991 Free Software Foundation, Inc.
   5 Authored by Brian Fox.
   6
   7 Permission is granted to make and distribute verbatim copies of this manual
   8 provided the copyright notice and this permission notice are preserved on
   9 all copies.
  10
  11 Permission is granted to process this file through Tex and print the
  12 results, provided the printed document carries copying permission notice
  13 identical to this one except for the removal of this paragraph (this
  14 paragraph not being relevant to the printed manual).
  15
  16 Permission is granted to copy and distribute modified versions of this
  17 manual under the conditions for verbatim copying, provided also that the
  18 GNU Copyright statement is available to the distributee, and provided that
  19 the entire resulting derived work is distributed under the terms of a
  20 permission notice identical to this one.
  21
  22 Permission is granted to copy and distribute translations of this manual
  23 into another language, under the above conditions for modified versions.
  24 @end ignore
  25
  26 @node Programming with GNU History
  27 @chapter Programming with GNU History
  28
  29 This chapter describes how to interface the GNU History Library with
  30 programs that you write.  It should be considered a technical guide.
  31 For information on the interactive use of GNU History, @pxref{Using
  32 History Interactively}.
  33
  34 @menu
  35 * Introduction to History::     What is the GNU History library for?
  36 * History Storage::             How information is stored.
  37 * History Functions::           Functions that you can use.
  38 * History Variables::           Variables that control behaviour.
  39 * History Programming Example:: Example of using the GNU History Library.
  40 @end menu
  41
  42 @node Introduction to History
  43 @section Introduction to History
  44
  45 Many programs read input from the user a line at a time.  The GNU history
  46 library is able to keep track of those lines, associate arbitrary data with
  47 each line, and utilize information from previous lines in making up new
  48 ones.
  49
  50 The programmer using the History library has available to him functions
  51 for remembering lines on a history stack, associating arbitrary data
  52 with a line, removing lines from the stack, searching through the stack
  53 for a line containing an arbitrary text string, and referencing any line
  54 on the stack directly.  In addition, a history @dfn{expansion} function
  55 is available which provides for a consistent user interface across many
  56 different programs.
  57
  58 The end-user using programs written with the History library has the
  59 benifit of a consistent user interface, with a set of well-known
  60 commands for manipulating the text of previous lines and using that text
  61 in new commands.  The basic history manipulation commands are similar to
  62 the history substitution used by @code{Csh}.
  63
  64 If the programmer desires, he can use the Readline library, which
  65 includes some history manipulation by default, and has the added
  66 advantage of Emacs style command line editing.
  67
  68 @node History Storage
  69 @section History Storage
  70
  71 @example
  72 typedef struct _hist_entry @{
  73   char *line;
  74   char *data;
  75 @} HIST_ENTRY;
  76 @end example
  77
  78 @node History Functions
  79 @section History Functions
  80
  81 This section describes the calling sequence for the various functions
  82 present in GNU History.
  83
  84 @defun {void using_history} ()
  85 Begin a session in which the history functions might be used.  This
  86 just initializes the interactive variables.
  87 @end defun
  88
  89 @defun {void add_history} (char *string)
  90 Place @var{string} at the end of the history list.  The associated data
  91 field (if any) is set to @code{NULL}.
  92 @end defun
  93
  94 @defun {int where_history} ()
  95 Returns the number which says what history element we are now looking
  96 at.
  97 @end defun
  98
  99 @defun {int history_set_pos} (int pos)
 100 Set the position in the history list to @var{pos}.
 101 @end defun
 102
 103 @defun {int history_search_pos} (char *string, int direction, int pos)
 104 Search for @var{string} in the history list, starting at @var{pos}, an
 105 absolute index into the list.  @var{direction}, if negative, says to search
 106 backwards from @var{pos}, else forwards.  Returns the absolute index of
 107 the history element where @var{string} was found, or -1 otherwise.
 108 @end defun
 109
 110 @defun {HIST_ENTRY *remove_history} ();
 111 Remove history element @var{which} from the history.  The removed
 112 element is returned to you so you can free the line, data,
 113 and containing structure.
 114 @end defun
 115
 116 @defun {void stifle_history} (int max)
 117 Stifle the history list, remembering only @var{max} number of entries.
 118 @end defun
 119
 120 @defun {int unstifle_history} ();
 121 Stop stifling the history.  This returns the previous amount the
 122 history was stifled by.  The value is positive if the history was
 123 stifled, negative if it wasn't.
 124 @end defun
 125
 126 @defun {int read_history} (char *filename)
 127 Add the contents of @var{filename} to the history list, a line at a
 128 time.  If @var{filename} is @code{NULL}, then read from
 129 @file{~/.history}.  Returns 0 if successful, or errno if not.
 130 @end defun
 131
 132 @defun {int read_history_range} (char *filename, int from, int to)
 133 Read a range of lines from @var{filename}, adding them to the history list.
 134 Start reading at the @var{from}'th line and end at the @var{to}'th.  If
 135 @var{from} is zero, start at the beginning.  If @var{to} is less than
 136 @var{from}, then read until the end of the file.  If @var{filename} is
 137 @code{NULL}, then read from @file{~/.history}.  Returns 0 if successful,
 138 or @code{errno} if not.
 139 @end defun
 140
 141 @defun {int write_history} (char *filename)
 142 Append the current history to @var{filename}.  If @var{filename} is
 143 @code{NULL}, then append the history list to @file{~/.history}.  Values
 144 returned are as in @code{read_history ()}.
 145 @end defun
 146
 147 @defun {int append_history} (int nelements, char *filename)
 148 Append @var{nelement} entries to @var{filename}.  The entries appended
 149 are from the end of the list minus @var{nelements} up to the end of the
 150 list.
 151 @end defun
 152
 153 @defun {HIST_ENTRY *replace_history_entry} ()
 154 Make the history entry at @var{which} have @var{line} and @var{data}.
 155 This returns the old entry so you can dispose of the data.  In the case
 156 of an invalid @var{which}, a @code{NULL} pointer is returned.
 157 @end defun
 158
 159 @defun {HIST_ENTRY *current_history} ()
 160 Return the history entry at the current position, as determined by
 161 @code{history_offset}.  If there is no entry there, return a @code{NULL}
 162 pointer.
 163 @end defun
 164
 165 @defun {HIST_ENTRY *previous_history} ()
 166 Back up @var{history_offset} to the previous history entry, and return a
 167 pointer to that entry.  If there is no previous entry, return a
 168 @code{NULL} pointer.
 169 @end defun
 170
 171 @defun {HIST_ENTRY *next_history} ()
 172 Move @code{history_offset} forward to the next history entry, and return
 173 the a pointer to that entry.  If there is no next entry, return a
 174 @code{NULL} pointer.
 175 @end defun
 176
 177 @defun {HIST_ENTRY **history_list} ()
 178 Return a @code{NULL} terminated array of @code{HIST_ENTRY} which is the
 179 current input history.  Element 0 of this list is the beginning of time.
 180 If there is no history, return @code{NULL}.
 181 @end defun
 182
 183 @defun {int history_search} (char *string, int direction)
 184 Search the history for @var{string}, starting at @code{history_offset}.
 185 If @var{direction} < 0, then the search is through previous entries,
 186 else through subsequent.  If @var{string} is found, then
 187 @code{current_history ()} is the history entry, and the value of this
 188 function is the offset in the line of that history entry that the
 189 @var{string} was found in.  Otherwise, nothing is changed, and a -1 is
 190 returned.
 191 @end defun
 192
 193 @defun {int history_expand} (char *string, char **output)
 194 Expand @var{string}, placing the result into @var{output}, a pointer
 195 to a string.  Returns:
 196 @table @code
 197 @item 0
 198 If no expansions took place (or, if the only change in
 199 the text was the de-slashifying of the history expansion
 200 character),
 201 @item 1
 202 if expansions did take place, or
 203 @item -1
 204 if there was an error in expansion.
 205 @end table
 206
 207 If an error ocurred in expansion, then @var{output} contains a descriptive
 208 error message.
 209 @end defun
 210
 211 @defun {char *history_arg_extract} (int first, int last, char *string)
 212 Extract a string segment consisting of the @var{first} through @var{last}
 213 arguments present in @var{string}.  Arguments are broken up as in
 214 the GNU Bash shell.
 215 @end defun
 216
 217 @defun {int history_total_bytes} ();
 218 Return the number of bytes that the primary history entries are using.
 219 This just adds up the lengths of @code{the_history->lines}.
 220 @end defun
 221
 222 @node History Variables
 223 @section History Variables
 224
 225 This section describes the variables in GNU History that are externally
 226 visible.
 227
 228 @defvar {int history_base}
 229 For convenience only.  You set this when interpreting history commands.
 230 It is the logical offset of the first history element.
 231 @end defvar
 232
 233 @node History Programming Example
 234 @section History Programming Example
 235
 236 The following snippet of code demonstrates simple use of the GNU History
 237 Library.
 238
 239 @smallexample
 240 main ()
 241 @{
 242   char line[1024], *t;
 243   int done = 0;
 244
 245   line[0] = 0;
 246
 247   while (!done)
 248     @{
 249       fprintf (stdout, "history%% ");
 250       t = gets (line);
 251
 252       if (!t)
 253         strcpy (line, "quit");
 254
 255       if (line[0])
 256         @{
 257           char *expansion;
 258           int result;
 259
 260           using_history ();
 261
 262           result = history_expand (line, &expansion);
 263           strcpy (line, expansion);
 264           free (expansion);
 265           if (result)
 266             fprintf (stderr, "%s\n", line);
 267
 268           if (result < 0)
 269             continue;
 270
 271           add_history (line);
 272         @}
 273
 274       if (strcmp (line, "quit") == 0) done = 1;
 275       if (strcmp (line, "save") == 0) write_history (0);
 276       if (strcmp (line, "read") == 0) read_history (0);
 277       if (strcmp (line, "list") == 0)
 278         @{
 279           register HIST_ENTRY **the_list = history_list ();
 280           register int i;
 281
 282           if (the_list)
 283             for (i = 0; the_list[i]; i++)
 284               fprintf (stdout, "%d: %s\n",
 285                  i + history_base, the_list[i]->line);
 286         @}
 287       if (strncmp (line, "delete", strlen ("delete")) == 0)
 288         @{
 289           int which;
 290           if ((sscanf (line + strlen ("delete"), "%d", &which)) == 1)
 291             @{
 292               HIST_ENTRY *entry = remove_history (which);
 293               if (!entry)
 294                 fprintf (stderr, "No such entry %d\n", which);
 295               else
 296                 @{
 297                   free (entry->line);
 298                   free (entry);
 299                 @}
 300             @}
 301           else
 302             @{
 303               fprintf (stderr, "non-numeric arg given to `delete'\n");
 304             @}
 305         @}
 306     @}
 307 @}
 308 @end smallexample
 309
 310
 311