readline/doc/history.html

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.51
   4      from /usr/homes/chet/src/bash/readline-2.2/doc/hist.texinfo on 2 April 1998 -->
   5
   6 <TITLE>GNU History Library</TITLE>
   7 </HEAD>
   8 <BODY>
   9 <H1>GNU History Library</H1>
  10 <H2>Edition 2.1, for <CODE>History Library</CODE> Version 2.1.</H2>
  11 <H2>March 1996</H2>
  12 <ADDRESS>Brian Fox, Free Software Foundation</ADDRESS>
  13 <ADDRESS>Chet Ramey, Case Western Reserve University</ADDRESS>
  14 <P>
  15 <P><HR><P>
  16
  17 <P>
  18 @dircategory Libraries
  19 @direntry
  20 * History: (history).       The GNU history library API
  21
  22 </P>
  23
  24 <P>
  25 This document describes the GNU History library, a programming tool that
  26 provides a consistent user interface for recalling lines of previously
  27 typed input.
  28
  29 </P>
  30 <P>
  31 Published by the Free Software Foundation <BR>
  32 675 Massachusetts Avenue, <BR>
  33 Cambridge, MA 02139 USA
  34
  35 </P>
  36 <P>
  37 Permission is granted to make and distribute verbatim copies of
  38 this manual provided the copyright notice and this permission notice
  39 are preserved on all copies.
  40
  41 </P>
  42 <P>
  43 Permission is granted to copy and distribute modified versions of this
  44 manual under the conditions for verbatim copying, provided that the entire
  45 resulting derived work is distributed under the terms of a permission
  46 notice identical to this one.
  47
  48 </P>
  49 <P>
  50 Permission is granted to copy and distribute translations of this manual
  51 into another language, under the above conditions for modified versions,
  52 except that this permission notice may be stated in a translation approved
  53 by the Foundation.
  54
  55 </P>
  56 <P>
  57 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
  58
  59 </P>
  60
  61
  62
  63 <H1><A NAME="SEC1" HREF="history_toc.html#TOC1">Using History Interactively</A></H1>
  64
  65 <P>
  66 This chapter describes how to use the GNU History Library interactively,
  67 from a user's standpoint.  It should be considered a user's guide.  For
  68 information on using the GNU History Library in your own programs,
  69 see section <A HREF="history.html#SEC6">Programming with GNU History</A>.
  70
  71 </P>
  72
  73
  74
  75 <H2><A NAME="SEC2" HREF="history_toc.html#TOC2">History Expansion</A></H2>
  76 <P>
  77 <A NAME="IDX1"></A>
  78
  79 </P>
  80 <P>
  81 The History library provides a history expansion feature that is similar
  82 to the history expansion provided by <CODE>csh</CODE>.  This section
  83 describes the syntax used to manipulate the history information.
  84
  85 </P>
  86 <P>
  87 History expansions introduce words from the history list into
  88 the input stream, making it easy to repeat commands, insert the
  89 arguments to a previous command into the current input line, or
  90 fix errors in previous commands quickly.
  91
  92 </P>
  93 <P>
  94 History expansion takes place in two parts.  The first is to determine
  95 which line from the history list should be used during substitution.
  96 The second is to select portions of that line for inclusion into the
  97 current one.  The line selected from the history is called the
  98 <STRONG>event</STRONG>, and the portions of that line that are acted upon are
  99 called <STRONG>words</STRONG>.  Various <STRONG>modifiers</STRONG> are available to manipulate
 100 the selected words.  The line is broken into words in the same fashion
 101 that Bash does, so that several words
 102 surrounded by quotes are considered one word.
 103 History expansions are introduced by the appearance of the
 104 history expansion character, which is <SAMP>`!'</SAMP> by default.
 105
 106 </P>
 107
 108
 109
 110 <H3><A NAME="SEC3" HREF="history_toc.html#TOC3">Event Designators</A></H3>
 111 <P>
 112 <A NAME="IDX2"></A>
 113
 114 </P>
 115 <P>
 116 An event designator is a reference to a command line entry in the
 117 history list.
 118 <A NAME="IDX3"></A>
 119
 120 </P>
 121 <DL COMPACT>
 122
 123 <DT><CODE>!</CODE>
 124 <DD>
 125 Start a history substitution, except when followed by a space, tab,
 126 the end of the line, <SAMP>`='</SAMP> or <SAMP>`('</SAMP>.
 127
 128 <DT><CODE>!<VAR>n</VAR></CODE>
 129 <DD>
 130 Refer to command line <VAR>n</VAR>.
 131
 132 <DT><CODE>!-<VAR>n</VAR></CODE>
 133 <DD>
 134 Refer to the command <VAR>n</VAR> lines back.
 135
 136 <DT><CODE>!!</CODE>
 137 <DD>
 138 Refer to the previous command.  This is a synonym for <SAMP>`!-1'</SAMP>.
 139
 140 <DT><CODE>!<VAR>string</VAR></CODE>
 141 <DD>
 142 Refer to the most recent command starting with <VAR>string</VAR>.
 143
 144 <DT><CODE>!?<VAR>string</VAR>[?]</CODE>
 145 <DD>
 146 Refer to the most recent command containing <VAR>string</VAR>.  The trailing
 147 <SAMP>`?'</SAMP> may be omitted if the <VAR>string</VAR> is followed immediately by
 148 a newline.
 149
 150 <DT><CODE>^<VAR>string1</VAR>^<VAR>string2</VAR>^</CODE>
 151 <DD>
 152 Quick Substitution.  Repeat the last command, replacing <VAR>string1</VAR>
 153 with <VAR>string2</VAR>.  Equivalent to
 154 <CODE>!!:s/<VAR>string1</VAR>/<VAR>string2</VAR>/</CODE>.
 155
 156 <DT><CODE>!#</CODE>
 157 <DD>
 158 The entire command line typed so far.
 159
 160 </DL>
 161
 162
 163
 164 <H3><A NAME="SEC4" HREF="history_toc.html#TOC4">Word Designators</A></H3>
 165
 166 <P>
 167 Word designators are used to select desired words from the event.
 168 A <SAMP>`:'</SAMP> separates the event specification from the word designator.  It
 169 may be omitted if the word designator begins with a <SAMP>`^'</SAMP>, <SAMP>`$'</SAMP>,
 170 <SAMP>`*'</SAMP>, <SAMP>`-'</SAMP>, or <SAMP>`%'</SAMP>.  Words are numbered from the beginning
 171 of the line, with the first word being denoted by 0 (zero).  Words are
 172 inserted into the current line separated by single spaces.
 173
 174 </P>
 175 <DL COMPACT>
 176
 177 <DT><CODE>0 (zero)</CODE>
 178 <DD>
 179 The <CODE>0</CODE>th word.  For many applications, this is the command word.
 180
 181 <DT><CODE><VAR>n</VAR></CODE>
 182 <DD>
 183 The <VAR>n</VAR>th word.
 184
 185 <DT><CODE>^</CODE>
 186 <DD>
 187 The first argument; that is, word 1.
 188
 189 <DT><CODE>$</CODE>
 190 <DD>
 191 The last argument.
 192
 193 <DT><CODE>%</CODE>
 194 <DD>
 195 The word matched by the most recent <SAMP>`?<VAR>string</VAR>?'</SAMP> search.
 196
 197 <DT><CODE><VAR>x</VAR>-<VAR>y</VAR></CODE>
 198 <DD>
 199 A range of words; <SAMP>`-<VAR>y</VAR>'</SAMP> abbreviates <SAMP>`0-<VAR>y</VAR>'</SAMP>.
 200
 201 <DT><CODE>*</CODE>
 202 <DD>
 203 All of the words, except the <CODE>0</CODE>th.  This is a synonym for <SAMP>`1-$'</SAMP>.
 204 It is not an error to use <SAMP>`*'</SAMP> if there is just one word in the event;
 205 the empty string is returned in that case.
 206
 207 <DT><CODE><VAR>x</VAR>*</CODE>
 208 <DD>
 209 Abbreviates <SAMP>`<VAR>x</VAR>-$'</SAMP>
 210
 211 <DT><CODE><VAR>x</VAR>-</CODE>
 212 <DD>
 213 Abbreviates <SAMP>`<VAR>x</VAR>-$'</SAMP> like <SAMP>`<VAR>x</VAR>*'</SAMP>, but omits the last word.
 214
 215 </DL>
 216
 217 <P>
 218 If a word designator is supplied without an event specification, the
 219 previous command is used as the event.
 220
 221 </P>
 222
 223
 224 <H3><A NAME="SEC5" HREF="history_toc.html#TOC5">Modifiers</A></H3>
 225
 226 <P>
 227 After the optional word designator, you can add a sequence of one or more
 228 of the following modifiers, each preceded by a <SAMP>`:'</SAMP>.
 229
 230 </P>
 231 <DL COMPACT>
 232
 233 <DT><CODE>h</CODE>
 234 <DD>
 235 Remove a trailing pathname component, leaving only the head.
 236
 237 <DT><CODE>t</CODE>
 238 <DD>
 239 Remove all leading  pathname  components, leaving the tail.
 240
 241 <DT><CODE>r</CODE>
 242 <DD>
 243 Remove a trailing suffix of the form <SAMP>`.<VAR>suffix</VAR>'</SAMP>, leaving
 244 the basename.
 245
 246 <DT><CODE>e</CODE>
 247 <DD>
 248 Remove all but the trailing suffix.
 249
 250 <DT><CODE>p</CODE>
 251 <DD>
 252 Print the new command but do not execute it.
 253
 254 <DT><CODE>s/<VAR>old</VAR>/<VAR>new</VAR>/</CODE>
 255 <DD>
 256 Substitute <VAR>new</VAR> for the first occurrence of <VAR>old</VAR> in the
 257 event line.  Any delimiter may be used in place of <SAMP>`/'</SAMP>.
 258 The delimiter may be quoted in <VAR>old</VAR> and <VAR>new</VAR>
 259 with a single backslash.  If <SAMP>`&#38;'</SAMP> appears in <VAR>new</VAR>,
 260 it is replaced by <VAR>old</VAR>.  A single backslash will quote
 261 the <SAMP>`&#38;'</SAMP>.  The final delimiter is optional if it is the last
 262 character on the input line.
 263
 264 <DT><CODE>&#38;</CODE>
 265 <DD>
 266 Repeat the previous substitution.
 267
 268 <DT><CODE>g</CODE>
 269 <DD>
 270 Cause changes to be applied over the entire event line.  Used in
 271 conjunction with <SAMP>`s'</SAMP>, as in <CODE>gs/<VAR>old</VAR>/<VAR>new</VAR>/</CODE>,
 272 or with <SAMP>`&#38;'</SAMP>.
 273
 274 </DL>
 275
 276
 277
 278 <H1><A NAME="SEC6" HREF="history_toc.html#TOC6">Programming with GNU History</A></H1>
 279
 280 <P>
 281 This chapter describes how to interface programs that you write
 282 with the GNU History Library.
 283 It should be considered a technical guide.
 284 For information on the interactive use of GNU History, see section <A HREF="history.html#SEC1">Using History Interactively</A>.
 285
 286 </P>
 287
 288
 289
 290 <H2><A NAME="SEC7" HREF="history_toc.html#TOC7">Introduction to History</A></H2>
 291
 292 <P>
 293 Many programs read input from the user a line at a time.  The GNU History
 294 library is able to keep track of those lines, associate arbitrary data with
 295 each line, and utilize information from previous lines in composing new
 296 ones.
 297
 298 </P>
 299 <P>
 300 The programmer using the History library has available functions
 301 for remembering lines on a history list, associating arbitrary data
 302 with a line, removing lines from the list, searching through the list
 303 for a line containing an arbitrary text string, and referencing any line
 304 in the list directly.  In addition, a history <STRONG>expansion</STRONG> function
 305 is available which provides for a consistent user interface across
 306 different programs.
 307
 308 </P>
 309 <P>
 310 The user using programs written with the History library has the
 311 benefit of a consistent user interface with a set of well-known
 312 commands for manipulating the text of previous lines and using that text
 313 in new commands.  The basic history manipulation commands are similar to
 314 the history substitution provided by <CODE>csh</CODE>.
 315
 316 </P>
 317 <P>
 318 If the programmer desires, he can use the Readline library, which
 319 includes some history manipulation by default, and has the added
 320 advantage of command line editing.
 321
 322 </P>
 323
 324
 325 <H2><A NAME="SEC8" HREF="history_toc.html#TOC8">History Storage</A></H2>
 326
 327 <P>
 328 The history list is an array of history entries.  A history entry is
 329 declared as follows:
 330
 331 </P>
 332
 333 <PRE>
 334 typedef struct _hist_entry {
 335   char *line;
 336   char *data;
 337 } HIST_ENTRY;
 338 </PRE>
 339
 340 <P>
 341 The history list itself might therefore be declared as
 342
 343 </P>
 344
 345 <PRE>
 346 HIST_ENTRY **the_history_list;
 347 </PRE>
 348
 349 <P>
 350 The state of the History library is encapsulated into a single structure:
 351
 352 </P>
 353
 354 <PRE>
 355 /* A structure used to pass the current state of the history stuff around. */
 356 typedef struct _hist_state {
 357   HIST_ENTRY **entries;         /* Pointer to the entries themselves. */
 358   int offset;                   /* The location pointer within this array. */
 359   int length;                   /* Number of elements within this array. */
 360   int size;                     /* Number of slots allocated to this array. */
 361   int flags;
 362 } HISTORY_STATE;
 363 </PRE>
 364
 365 <P>
 366 If the flags member includes <CODE>HS_STIFLED</CODE>, the history has been
 367 stifled.
 368
 369 </P>
 370
 371
 372 <H2><A NAME="SEC9" HREF="history_toc.html#TOC9">History Functions</A></H2>
 373
 374 <P>
 375 This section describes the calling sequence for the various functions
 376 present in GNU History.
 377
 378 </P>
 379
 380
 381
 382 <H3><A NAME="SEC10" HREF="history_toc.html#TOC10">Initializing History and State Management</A></H3>
 383
 384 <P>
 385 This section describes functions used to initialize and manage
 386 the state of the History library when you want to use the history
 387 functions in your program.
 388
 389 </P>
 390 <P>
 391 <DL>
 392 <DT><U>Function:</U> void <B>using_history</B> <I>()</I>
 393 <DD><A NAME="IDX4"></A>
 394 Begin a session in which the history functions might be used.  This
 395 initializes the interactive variables.
 396 </DL>
 397
 398 </P>
 399 <P>
 400 <DL>
 401 <DT><U>Function:</U> HISTORY_STATE * <B>history_get_history_state</B> <I>()</I>
 402 <DD><A NAME="IDX5"></A>
 403 Return a structure describing the current state of the input history.
 404 </DL>
 405
 406 </P>
 407 <P>
 408 <DL>
 409 <DT><U>Function:</U> void <B>history_set_history_state</B> <I>(HISTORY_STATE *state)</I>
 410 <DD><A NAME="IDX6"></A>
 411 Set the state of the history list according to <VAR>state</VAR>.
 412 </DL>
 413
 414 </P>
 415
 416
 417 <H3><A NAME="SEC11" HREF="history_toc.html#TOC11">History List Management</A></H3>
 418
 419 <P>
 420 These functions manage individual entries on the history list, or set
 421 parameters managing the list itself.
 422
 423 </P>
 424 <P>
 425 <DL>
 426 <DT><U>Function:</U> void <B>add_history</B> <I>(char *string)</I>
 427 <DD><A NAME="IDX7"></A>
 428 Place <VAR>string</VAR> at the end of the history list.  The associated data
 429 field (if any) is set to <CODE>NULL</CODE>.
 430 </DL>
 431
 432 </P>
 433 <P>
 434 <DL>
 435 <DT><U>Function:</U> HIST_ENTRY * <B>remove_history</B> <I>(int which)</I>
 436 <DD><A NAME="IDX8"></A>
 437 Remove history entry at offset <VAR>which</VAR> from the history.  The
 438 removed element is returned so you can free the line, data,
 439 and containing structure.
 440 </DL>
 441
 442 </P>
 443 <P>
 444 <DL>
 445 <DT><U>Function:</U> HIST_ENTRY * <B>replace_history_entry</B> <I>(int which, char *line, char *data)</I>
 446 <DD><A NAME="IDX9"></A>
 447 Make the history entry at offset <VAR>which</VAR> have <VAR>line</VAR> and <VAR>data</VAR>.
 448 This returns the old entry so you can dispose of the data.  In the case
 449 of an invalid <VAR>which</VAR>, a <CODE>NULL</CODE> pointer is returned.
 450 </DL>
 451
 452 </P>
 453 <P>
 454 <DL>
 455 <DT><U>Function:</U> void <B>clear_history</B> <I>()</I>
 456 <DD><A NAME="IDX10"></A>
 457 Clear the history list by deleting all the entries.
 458 </DL>
 459
 460 </P>
 461 <P>
 462 <DL>
 463 <DT><U>Function:</U> void <B>stifle_history</B> <I>(int max)</I>
 464 <DD><A NAME="IDX11"></A>
 465 Stifle the history list, remembering only the last <VAR>max</VAR> entries.
 466 </DL>
 467
 468 </P>
 469 <P>
 470 <DL>
 471 <DT><U>Function:</U> int <B>unstifle_history</B> <I>()</I>
 472 <DD><A NAME="IDX12"></A>
 473 Stop stifling the history.  This returns the previous amount the
 474 history was stifled.  The value is positive if the history was
 475 stifled, negative if it wasn't.
 476 </DL>
 477
 478 </P>
 479 <P>
 480 <DL>
 481 <DT><U>Function:</U> int <B>history_is_stifled</B> <I>()</I>
 482 <DD><A NAME="IDX13"></A>
 483 Returns non-zero if the history is stifled, zero if it is not.
 484 </DL>
 485
 486 </P>
 487
 488
 489 <H3><A NAME="SEC12" HREF="history_toc.html#TOC12">Information About the History List</A></H3>
 490
 491 <P>
 492 These functions return information about the entire history list or
 493 individual list entries.
 494
 495 </P>
 496 <P>
 497 <DL>
 498 <DT><U>Function:</U> HIST_ENTRY ** <B>history_list</B> <I>()</I>
 499 <DD><A NAME="IDX14"></A>
 500 Return a <CODE>NULL</CODE> terminated array of <CODE>HIST_ENTRY</CODE> which is the
 501 current input history.  Element 0 of this list is the beginning of time.
 502 If there is no history, return <CODE>NULL</CODE>.
 503 </DL>
 504
 505 </P>
 506 <P>
 507 <DL>
 508 <DT><U>Function:</U> int <B>where_history</B> <I>()</I>
 509 <DD><A NAME="IDX15"></A>
 510 Returns the offset of the current history element.
 511 </DL>
 512
 513 </P>
 514 <P>
 515 <DL>
 516 <DT><U>Function:</U> HIST_ENTRY * <B>current_history</B> <I>()</I>
 517 <DD><A NAME="IDX16"></A>
 518 Return the history entry at the current position, as determined by
 519 <CODE>where_history ()</CODE>.  If there is no entry there, return a <CODE>NULL</CODE>
 520 pointer.
 521 </DL>
 522
 523 </P>
 524 <P>
 525 <DL>
 526 <DT><U>Function:</U> HIST_ENTRY * <B>history_get</B> <I>(int offset)</I>
 527 <DD><A NAME="IDX17"></A>
 528 Return the history entry at position <VAR>offset</VAR>, starting from
 529 <CODE>history_base</CODE>.  If there is no entry there, or if <VAR>offset</VAR>
 530 is greater than the history length, return a <CODE>NULL</CODE> pointer.
 531 </DL>
 532
 533 </P>
 534 <P>
 535 <DL>
 536 <DT><U>Function:</U> int <B>history_total_bytes</B> <I>()</I>
 537 <DD><A NAME="IDX18"></A>
 538 Return the number of bytes that the primary history entries are using.
 539 This function returns the sum of the lengths of all the lines in the
 540 history.
 541 </DL>
 542
 543 </P>
 544
 545
 546 <H3><A NAME="SEC13" HREF="history_toc.html#TOC13">Moving Around the History List</A></H3>
 547
 548 <P>
 549 These functions allow the current index into the history list to be
 550 set or changed.
 551
 552 </P>
 553 <P>
 554 <DL>
 555 <DT><U>Function:</U> int <B>history_set_pos</B> <I>(int pos)</I>
 556 <DD><A NAME="IDX19"></A>
 557 Set the position in the history list to <VAR>pos</VAR>, an absolute index
 558 into the list.
 559 </DL>
 560
 561 </P>
 562 <P>
 563 <DL>
 564 <DT><U>Function:</U> HIST_ENTRY * <B>previous_history</B> <I>()</I>
 565 <DD><A NAME="IDX20"></A>
 566 Back up the current history offset to the previous history entry, and
 567 return a pointer to that entry.  If there is no previous entry, return
 568 a <CODE>NULL</CODE> pointer.
 569 </DL>
 570
 571 </P>
 572 <P>
 573 <DL>
 574 <DT><U>Function:</U> HIST_ENTRY * <B>next_history</B> <I>()</I>
 575 <DD><A NAME="IDX21"></A>
 576 Move the current history offset forward to the next history entry, and
 577 return the a pointer to that entry.  If there is no next entry, return
 578 a <CODE>NULL</CODE> pointer.
 579 </DL>
 580
 581 </P>
 582
 583
 584 <H3><A NAME="SEC14" HREF="history_toc.html#TOC14">Searching the History List</A></H3>
 585 <P>
 586 <A NAME="IDX22"></A>
 587
 588 </P>
 589 <P>
 590 These functions allow searching of the history list for entries containing
 591 a specific string.  Searching may be performed both forward and backward
 592 from the current history position.  The search may be <STRONG>anchored</STRONG>,
 593 meaning that the string must match at the beginning of the history entry.
 594 <A NAME="IDX23"></A>
 595
 596 </P>
 597 <P>
 598 <DL>
 599 <DT><U>Function:</U> int <B>history_search</B> <I>(char *string, int direction)</I>
 600 <DD><A NAME="IDX24"></A>
 601 Search the history for <VAR>string</VAR>, starting at the current history
 602 offset.  If <VAR>direction</VAR> &#60; 0, then the search is through previous entries,
 603 else through subsequent.  If <VAR>string</VAR> is found, then
 604 the current history index is set to that history entry, and the value
 605 returned is the offset in the line of the entry where
 606 <VAR>string</VAR> was found.  Otherwise, nothing is changed, and a -1 is
 607 returned.
 608 </DL>
 609
 610 </P>
 611 <P>
 612 <DL>
 613 <DT><U>Function:</U> int <B>history_search_prefix</B> <I>(char *string, int direction)</I>
 614 <DD><A NAME="IDX25"></A>
 615 Search the history for <VAR>string</VAR>, starting at the current history
 616 offset.  The search is anchored: matching lines must begin with
 617 <VAR>string</VAR>.  If <VAR>direction</VAR> &#60; 0, then the search is through previous
 618 entries, else through subsequent.  If <VAR>string</VAR> is found, then the
 619 current history index is set to that entry, and the return value is 0.
 620 Otherwise, nothing is changed, and a -1 is returned.
 621 </DL>
 622
 623 </P>
 624 <P>
 625 <DL>
 626 <DT><U>Function:</U> int <B>history_search_pos</B> <I>(char *string, int direction, int pos)</I>
 627 <DD><A NAME="IDX26"></A>
 628 Search for <VAR>string</VAR> in the history list, starting at <VAR>pos</VAR>, an
 629 absolute index into the list.  If <VAR>direction</VAR> is negative, the search
 630 proceeds backward from <VAR>pos</VAR>, otherwise forward.  Returns the absolute
 631 index of the history element where <VAR>string</VAR> was found, or -1 otherwise.
 632 </DL>
 633
 634 </P>
 635
 636
 637 <H3><A NAME="SEC15" HREF="history_toc.html#TOC15">Managing the History File</A></H3>
 638
 639 <P>
 640 The History library can read the history from and write it to a file.
 641 This section documents the functions for managing a history file.
 642
 643 </P>
 644 <P>
 645 <DL>
 646 <DT><U>Function:</U> int <B>read_history</B> <I>(char *filename)</I>
 647 <DD><A NAME="IDX27"></A>
 648 Add the contents of <VAR>filename</VAR> to the history list, a line at a
 649 time.  If <VAR>filename</VAR> is <CODE>NULL</CODE>, then read from
 650 <TT>`~/.history'</TT>.  Returns 0 if successful, or errno if not.
 651 </DL>
 652
 653 </P>
 654 <P>
 655 <DL>
 656 <DT><U>Function:</U> int <B>read_history_range</B> <I>(char *filename, int from, int to)</I>
 657 <DD><A NAME="IDX28"></A>
 658 Read a range of lines from <VAR>filename</VAR>, adding them to the history list.
 659 Start reading at line <VAR>from</VAR> and end at <VAR>to</VAR>.  If
 660 <VAR>from</VAR> is zero, start at the beginning.  If <VAR>to</VAR> is less than
 661 <VAR>from</VAR>, then read until the end of the file.  If <VAR>filename</VAR> is
 662 <CODE>NULL</CODE>, then read from <TT>`~/.history'</TT>.  Returns 0 if successful,
 663 or <CODE>errno</CODE> if not.
 664 </DL>
 665
 666 </P>
 667 <P>
 668 <DL>
 669 <DT><U>Function:</U> int <B>write_history</B> <I>(char *filename)</I>
 670 <DD><A NAME="IDX29"></A>
 671 Write the current history to <VAR>filename</VAR>, overwriting <VAR>filename</VAR>
 672 if necessary.  If <VAR>filename</VAR> is
 673 <CODE>NULL</CODE>, then write the history list to <TT>`~/.history'</TT>.  Values
 674 returned are as in <CODE>read_history ()</CODE>.
 675 </DL>
 676
 677 </P>
 678 <P>
 679 <DL>
 680 <DT><U>Function:</U> int <B>append_history</B> <I>(int nelements, char *filename)</I>
 681 <DD><A NAME="IDX30"></A>
 682 Append the last <VAR>nelements</VAR> of the history list to <VAR>filename</VAR>.
 683 </DL>
 684
 685 </P>
 686 <P>
 687 <DL>
 688 <DT><U>Function:</U> int <B>history_truncate_file</B> <I>(char *filename, int nlines)</I>
 689 <DD><A NAME="IDX31"></A>
 690 Truncate the history file <VAR>filename</VAR>, leaving only the last
 691 <VAR>nlines</VAR> lines.
 692 </DL>
 693
 694 </P>
 695
 696
 697 <H3><A NAME="SEC16" HREF="history_toc.html#TOC16">History Expansion</A></H3>
 698
 699 <P>
 700 These functions implement <CODE>csh</CODE>-like history expansion.
 701
 702 </P>
 703 <P>
 704 <DL>
 705 <DT><U>Function:</U> int <B>history_expand</B> <I>(char *string, char **output)</I>
 706 <DD><A NAME="IDX32"></A>
 707 Expand <VAR>string</VAR>, placing the result into <VAR>output</VAR>, a pointer
 708 to a string (see section <A HREF="history.html#SEC2">History Expansion</A>).  Returns:
 709 <DL COMPACT>
 710
 711 <DT><CODE>0</CODE>
 712 <DD>
 713 If no expansions took place (or, if the only change in
 714 the text was the de-slashifying of the history expansion
 715 character);
 716 <DT><CODE>1</CODE>
 717 <DD>
 718 if expansions did take place;
 719 <DT><CODE>-1</CODE>
 720 <DD>
 721 if there was an error in expansion;
 722 <DT><CODE>2</CODE>
 723 <DD>
 724 if the returned line should only be displayed, but not executed,
 725 as with the <CODE>:p</CODE> modifier (see section <A HREF="history.html#SEC5">Modifiers</A>).
 726 </DL>
 727
 728 <P>
 729 If an error ocurred in expansion, then <VAR>output</VAR> contains a descriptive
 730 error message.
 731 </DL>
 732
 733 </P>
 734 <P>
 735 <DL>
 736 <DT><U>Function:</U> char * <B>history_arg_extract</B> <I>(int first, int last, char *string)</I>
 737 <DD><A NAME="IDX33"></A>
 738 Extract a string segment consisting of the <VAR>first</VAR> through <VAR>last</VAR>
 739 arguments present in <VAR>string</VAR>.  Arguments are broken up as in Bash.
 740 </DL>
 741
 742 </P>
 743 <P>
 744 <DL>
 745 <DT><U>Function:</U> char * <B>get_history_event</B> <I>(char *string, int *cindex, int qchar)</I>
 746 <DD><A NAME="IDX34"></A>
 747 Returns the text of the history event beginning at <VAR>string</VAR> +
 748 <VAR>*cindex</VAR>.  <VAR>*cindex</VAR> is modified to point to after the event
 749 specifier.  At function entry, <VAR>cindex</VAR> points to the index into
 750 <VAR>string</VAR> where the history event specification begins.  <VAR>qchar</VAR>
 751 is a character that is allowed to end the event specification in addition
 752 to the "normal" terminating characters.
 753 </DL>
 754
 755 </P>
 756 <P>
 757 <DL>
 758 <DT><U>Function:</U> char ** <B>history_tokenize</B> <I>(char *string)</I>
 759 <DD><A NAME="IDX35"></A>
 760 Return an array of tokens parsed out of <VAR>string</VAR>, much as the
 761 shell might.  The tokens are split on white space and on the
 762 characters <CODE>()&#60;&#62;;&#38;|$</CODE>, and shell quoting conventions are
 763 obeyed.
 764 </DL>
 765
 766 </P>
 767
 768
 769 <H2><A NAME="SEC17" HREF="history_toc.html#TOC17">History Variables</A></H2>
 770
 771 <P>
 772 This section describes the externally visible variables exported by
 773 the GNU History Library.
 774
 775 </P>
 776 <P>
 777 <DL>
 778 <DT><U>Variable:</U> int <B>history_base</B>
 779 <DD><A NAME="IDX36"></A>
 780 The logical offset of the first entry in the history list.
 781 </DL>
 782
 783 </P>
 784 <P>
 785 <DL>
 786 <DT><U>Variable:</U> int <B>history_length</B>
 787 <DD><A NAME="IDX37"></A>
 788 The number of entries currently stored in the history list.
 789 </DL>
 790
 791 </P>
 792 <P>
 793 <DL>
 794 <DT><U>Variable:</U> int <B>max_input_history</B>
 795 <DD><A NAME="IDX38"></A>
 796 The maximum number of history entries.  This must be changed using
 797 <CODE>stifle_history ()</CODE>.
 798 </DL>
 799
 800 </P>
 801 <P>
 802 <DL>
 803 <DT><U>Variable:</U> char <B>history_expansion_char</B>
 804 <DD><A NAME="IDX39"></A>
 805 The character that starts a history event.  The default is <SAMP>`!'</SAMP>.
 806 </DL>
 807
 808 </P>
 809 <P>
 810 <DL>
 811 <DT><U>Variable:</U> char <B>history_subst_char</B>
 812 <DD><A NAME="IDX40"></A>
 813 The character that invokes word substitution if found at the start of
 814 a line.  The default is <SAMP>`^'</SAMP>.
 815 </DL>
 816
 817 </P>
 818 <P>
 819 <DL>
 820 <DT><U>Variable:</U> char <B>history_comment_char</B>
 821 <DD><A NAME="IDX41"></A>
 822 During tokenization, if this character is seen as the first character
 823 of a word, then it and all subsequent characters up to a newline are
 824 ignored, suppressing history expansion for the remainder of the line.
 825 This is disabled by default.
 826 </DL>
 827
 828 </P>
 829 <P>
 830 <DL>
 831 <DT><U>Variable:</U> char * <B>history_no_expand_chars</B>
 832 <DD><A NAME="IDX42"></A>
 833 The list of characters which inhibit history expansion if found immediately
 834 following <VAR>history_expansion_char</VAR>.  The default is whitespace and
 835 <SAMP>`='</SAMP>.
 836 </DL>
 837
 838 </P>
 839 <P>
 840 <DL>
 841 <DT><U>Variable:</U> char * <B>history_search_delimiter_chars</B>
 842 <DD><A NAME="IDX43"></A>
 843 The list of additional characters which can delimit a history search
 844 string, in addition to whitespace, <SAMP>`:'</SAMP> and <SAMP>`?'</SAMP> in the case of
 845 a substring search.  The default is empty.
 846 </DL>
 847
 848 </P>
 849 <P>
 850 <DL>
 851 <DT><U>Variable:</U> int <B>history_quotes_inhibit_expansion</B>
 852 <DD><A NAME="IDX44"></A>
 853 If non-zero, single-quoted words are not scanned for the history expansion
 854 character.  The default value is 0.
 855 </DL>
 856
 857 </P>
 858 <P>
 859 <DL>
 860 <DT><U>Variable:</U> Function * <B>history_inhibit_expansion_function</B>
 861 <DD><A NAME="IDX45"></A>
 862 This should be set to the address of a function that takes two arguments:
 863 a <CODE>char *</CODE> (<VAR>string</VAR>) and an integer index into that string (<VAR>i</VAR>).
 864 It should return a non-zero value if the history expansion starting at
 865 <VAR>string[i]</VAR> should not be performed; zero if the expansion should
 866 be done.
 867 It is intended for use by applications like Bash that use the history
 868 expansion character for additional purposes.
 869 By default, this variable is set to NULL.
 870 </DL>
 871
 872 </P>
 873
 874
 875 <H2><A NAME="SEC18" HREF="history_toc.html#TOC18">History Programming Example</A></H2>
 876
 877 <P>
 878 The following program demonstrates simple use of the GNU History Library.
 879
 880 </P>
 881
 882 <PRE>
 883 main ()
 884 {
 885   char line[1024], *t;
 886   int len, done = 0;
 887
 888   line[0] = 0;
 889
 890   using_history ();
 891   while (!done)
 892     {
 893       printf ("history$ ");
 894       fflush (stdout);
 895       t = fgets (line, sizeof (line) - 1, stdin);
 896       if (t &#38;&#38; *t)
 897         {
 898           len = strlen (t);
 899           if (t[len - 1] == '\n')
 900             t[len - 1] = '\0';
 901         }
 902
 903       if (!t)
 904         strcpy (line, "quit");
 905
 906       if (line[0])
 907         {
 908           char *expansion;
 909           int result;
 910
 911           result = history_expand (line, &#38;expansion);
 912           if (result)
 913             fprintf (stderr, "%s\n", expansion);
 914
 915           if (result &#60; 0 || result == 2)
 916             {
 917               free (expansion);
 918               continue;
 919             }
 920
 921           add_history (expansion);
 922           strncpy (line, expansion, sizeof (line) - 1);
 923           free (expansion);
 924         }
 925
 926       if (strcmp (line, "quit") == 0)
 927         done = 1;
 928       else if (strcmp (line, "save") == 0)
 929         write_history ("history_file");
 930       else if (strcmp (line, "read") == 0)
 931         read_history ("history_file");
 932       else if (strcmp (line, "list") == 0)
 933         {
 934           register HIST_ENTRY **the_list;
 935           register int i;
 936
 937           the_list = history_list ();
 938           if (the_list)
 939             for (i = 0; the_list[i]; i++)
 940               printf ("%d: %s\n", i + history_base, the_list[i]-&#62;line);
 941         }
 942       else if (strncmp (line, "delete", 6) == 0)
 943         {
 944           int which;
 945           if ((sscanf (line + 6, "%d", &#38;which)) == 1)
 946             {
 947               HIST_ENTRY *entry = remove_history (which);
 948               if (!entry)
 949                 fprintf (stderr, "No such entry %d\n", which);
 950               else
 951                 {
 952                   free (entry-&#62;line);
 953                   free (entry);
 954                 }
 955             }
 956           else
 957             {
 958               fprintf (stderr, "non-numeric arg given to `delete'\n");
 959             }
 960         }
 961     }
 962 }
 963 </PRE>
 964
 965
 966
 967 <H1><A NAME="SEC19" HREF="history_toc.html#TOC19">Concept Index</A></H1>
 968 <P>
 969 <H2>a</H2>
 970 <DIR>
 971 <LI><A HREF="history.html#IDX23">anchored search</A>
 972 </DIR>
 973 <H2>e</H2>
 974 <DIR>
 975 <LI><A HREF="history.html#IDX2">event designators</A>
 976 </DIR>
 977 <H2>h</H2>
 978 <DIR>
 979 <LI><A HREF="history.html#IDX3">history events</A>
 980 <LI><A HREF="history.html#IDX1">history expansion</A>
 981 <LI><A HREF="history.html#IDX22">History Searching</A>
 982 </DIR>
 983
 984 </P>
 985
 986
 987 <H1><A NAME="SEC20" HREF="history_toc.html#TOC20">Function and Variable Index</A></H1>
 988 <P>
 989 <H2>a</H2>
 990 <DIR>
 991 <LI><A HREF="history.html#IDX7">add_history</A>
 992 <LI><A HREF="history.html#IDX30">append_history</A>
 993 </DIR>
 994 <H2>c</H2>
 995 <DIR>
 996 <LI><A HREF="history.html#IDX10">clear_history</A>
 997 <LI><A HREF="history.html#IDX16">current_history</A>
 998 </DIR>
 999 <H2>g</H2>
1000 <DIR>
1001 <LI><A HREF="history.html#IDX34">get_history_event</A>
1002 </DIR>
1003 <H2>h</H2>
1004 <DIR>
1005 <LI><A HREF="history.html#IDX33">history_arg_extract</A>
1006 <LI><A HREF="history.html#IDX36">history_base</A>
1007 <LI><A HREF="history.html#IDX41">history_comment_char</A>
1008 <LI><A HREF="history.html#IDX32">history_expand</A>
1009 <LI><A HREF="history.html#IDX39">history_expansion_char</A>
1010 <LI><A HREF="history.html#IDX17">history_get</A>
1011 <LI><A HREF="history.html#IDX5">history_get_history_state</A>
1012 <LI><A HREF="history.html#IDX45">history_inhibit_expansion_function</A>
1013 <LI><A HREF="history.html#IDX13">history_is_stifled</A>
1014 <LI><A HREF="history.html#IDX37">history_length</A>
1015 <LI><A HREF="history.html#IDX14">history_list</A>
1016 <LI><A HREF="history.html#IDX42">history_no_expand_chars</A>
1017 <LI><A HREF="history.html#IDX44">history_quotes_inhibit_expansion</A>
1018 <LI><A HREF="history.html#IDX24">history_search</A>
1019 <LI><A HREF="history.html#IDX43">history_search_delimiter_chars</A>
1020 <LI><A HREF="history.html#IDX26">history_search_pos</A>
1021 <LI><A HREF="history.html#IDX25">history_search_prefix</A>
1022 <LI><A HREF="history.html#IDX6">history_set_history_state</A>
1023 <LI><A HREF="history.html#IDX19">history_set_pos</A>
1024 <LI><A HREF="history.html#IDX40">history_subst_char</A>
1025 <LI><A HREF="history.html#IDX35">history_tokenize</A>
1026 <LI><A HREF="history.html#IDX18">history_total_bytes</A>
1027 <LI><A HREF="history.html#IDX31">history_truncate_file</A>
1028 </DIR>
1029 <H2>m</H2>
1030 <DIR>
1031 <LI><A HREF="history.html#IDX38">max_input_history</A>
1032 </DIR>
1033 <H2>n</H2>
1034 <DIR>
1035 <LI><A HREF="history.html#IDX21">next_history</A>
1036 </DIR>
1037 <H2>p</H2>
1038 <DIR>
1039 <LI><A HREF="history.html#IDX20">previous_history</A>
1040 </DIR>
1041 <H2>r</H2>
1042 <DIR>
1043 <LI><A HREF="history.html#IDX27">read_history</A>
1044 <LI><A HREF="history.html#IDX28">read_history_range</A>
1045 <LI><A HREF="history.html#IDX8">remove_history</A>
1046 <LI><A HREF="history.html#IDX9">replace_history_entry</A>
1047 </DIR>
1048 <H2>s</H2>
1049 <DIR>
1050 <LI><A HREF="history.html#IDX11">stifle_history</A>
1051 </DIR>
1052 <H2>u</H2>
1053 <DIR>
1054 <LI><A HREF="history.html#IDX12">unstifle_history</A>
1055 <LI><A HREF="history.html#IDX4">using_history</A>
1056 </DIR>
1057 <H2>w</H2>
1058 <DIR>
1059 <LI><A HREF="history.html#IDX15">where_history</A>
1060 <LI><A HREF="history.html#IDX29">write_history</A>
1061 </DIR>
1062
1063 </P>
1064 <P><HR><P>
1065 This document was generated on 2 April 1998 using the
1066 <A HREF="http://wwwcn.cern.ch/dci/texi2html/">texi2html</A>
1067 translator version 1.51.</P>
1068 </BODY>
1069 </HTML>