readline/doc/history.html

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