Mercurial > octave

comparison readline/doc/history.html @ 2996:9d4e3a9de17e

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