|
2996
|
1 This is Info file history.info, produced by Makeinfo-1.55 from the |
|
|
2 input file /usr/homes/chet/src/bash/readline-src/doc/hist.texinfo. |
|
|
3 |
|
|
4 This document describes the GNU History library, a programming tool |
|
|
5 that provides a consistent user interface for recalling lines of |
|
|
6 previously typed input. |
|
|
7 |
|
|
8 Copyright (C) 1988, 1991, 1993, 1995, 1996 Free Software Foundation, |
|
|
9 Inc. |
|
|
10 |
|
|
11 Permission is granted to make and distribute verbatim copies of this |
|
|
12 manual provided the copyright notice and this permission notice pare |
|
|
13 preserved on all copies. |
|
|
14 |
|
|
15 Permission is granted to copy and distribute modified versions of |
|
|
16 this manual under the conditions for verbatim copying, provided that |
|
|
17 the entire resulting derived work is distributed under the terms of a |
|
|
18 permission notice identical to this one. |
|
|
19 |
|
|
20 Permission is granted to copy and distribute translations of this |
|
|
21 manual into another language, under the above conditions for modified |
|
|
22 versions, except that this permission notice may be stated in a |
|
|
23 translation approved by the Foundation. |
|
|
24 |
|
|
25 |
|
|
26 File: history.info, Node: Top, Next: Using History Interactively, Prev: (DIR), Up: (DIR) |
|
|
27 |
|
|
28 GNU History Library |
|
|
29 ******************* |
|
|
30 |
|
|
31 This document describes the GNU History library, a programming tool |
|
|
32 that provides a consistent user interface for recalling lines of |
|
|
33 previously typed input. |
|
|
34 |
|
|
35 * Menu: |
|
|
36 |
|
|
37 * Using History Interactively:: GNU History User's Manual. |
|
|
38 * Programming with GNU History:: GNU History Programmer's Manual. |
|
|
39 * Concept Index:: Index of concepts described in this manual. |
|
|
40 * Function and Variable Index:: Index of externally visible functions |
|
|
41 and variables. |
|
|
42 |
|
|
43 |
|
|
44 File: history.info, Node: Using History Interactively, Next: Programming with GNU History, Prev: Top, Up: Top |
|
|
45 |
|
|
46 Using History Interactively |
|
|
47 *************************** |
|
|
48 |
|
|
49 This chapter describes how to use the GNU History Library |
|
|
50 interactively, from a user's standpoint. It should be considered a |
|
|
51 user's guide. For information on using the GNU History Library in your |
|
|
52 own programs, *note Programming with GNU History::.. |
|
|
53 |
|
|
54 * Menu: |
|
|
55 |
|
|
56 * History Interaction:: What it feels like using History as a user. |
|
|
57 |
|
|
58 |
|
|
59 File: history.info, Node: History Interaction, Up: Using History Interactively |
|
|
60 |
|
|
61 Interactive History Expansion |
|
|
62 ============================= |
|
|
63 |
|
|
64 The History library provides a history expansion feature that is |
|
|
65 similar to the history expansion provided by `csh'. This section |
|
|
66 describes the syntax used to manipulate the history information. |
|
|
67 |
|
|
68 History expansions introduce words from the history list into the |
|
|
69 input stream, making it easy to repeat commands, insert the arguments |
|
|
70 to a previous command into the current input line, or fix errors in |
|
|
71 previous commands quickly. |
|
|
72 |
|
|
73 History expansion takes place in two parts. The first is to |
|
|
74 determine which line from the previous history should be used during |
|
|
75 substitution. The second is to select portions of that line for |
|
|
76 inclusion into the current one. The line selected from the previous |
|
|
77 history is called the "event", and the portions of that line that are |
|
|
78 acted upon are called "words". Various "modifiers" are available to |
|
|
79 manipulate the selected words. The line is broken into words in the |
|
|
80 same fashion that Bash does, so that several English (or Unix) words |
|
|
81 surrounded by quotes are considered as one word. History expansions |
|
|
82 are introduced by the appearance of the history expansion character, |
|
|
83 which is `!' by default. |
|
|
84 |
|
|
85 * Menu: |
|
|
86 |
|
|
87 * Event Designators:: How to specify which history line to use. |
|
|
88 * Word Designators:: Specifying which words are of interest. |
|
|
89 * Modifiers:: Modifying the results of substitution. |
|
|
90 |
|
|
91 |
|
|
92 File: history.info, Node: Event Designators, Next: Word Designators, Up: History Interaction |
|
|
93 |
|
|
94 Event Designators |
|
|
95 ----------------- |
|
|
96 |
|
|
97 An event designator is a reference to a command line entry in the |
|
|
98 history list. |
|
|
99 |
|
|
100 `!' |
|
|
101 Start a history substitution, except when followed by a space, tab, |
|
|
102 the end of the line, = or (. |
|
|
103 |
|
|
104 `!N' |
|
|
105 Refer to command line N. |
|
|
106 |
|
|
107 `!-N' |
|
|
108 Refer to the command N lines back. |
|
|
109 |
|
|
110 `!!' |
|
|
111 Refer to the previous command. This is a synonym for `!-1'. |
|
|
112 |
|
|
113 `!STRING' |
|
|
114 Refer to the most recent command starting with STRING. |
|
|
115 |
|
|
116 `!?STRING[?]' |
|
|
117 Refer to the most recent command containing STRING. The trailing |
|
|
118 `?' may be omitted if the STRING is followed immediately by a |
|
|
119 newline. |
|
|
120 |
|
|
121 `^STRING1^STRING2^' |
|
|
122 Quick Substitution. Repeat the last command, replacing STRING1 |
|
|
123 with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. |
|
|
124 |
|
|
125 `!#' |
|
|
126 The entire command line typed so far. |
|
|
127 |
|
|
128 |
|
|
129 File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction |
|
|
130 |
|
|
131 Word Designators |
|
|
132 ---------------- |
|
|
133 |
|
|
134 Word designators are used to select desired words from the event. A |
|
|
135 `:' separates the event specification from the word designator. It can |
|
|
136 be omitted if the word designator begins with a `^', `$', `*', `-', or |
|
|
137 `%'. Words are numbered from the beginning of the line, with the first |
|
|
138 word being denoted by 0 (zero). Words are inserted into the current |
|
|
139 line separated by single spaces. |
|
|
140 |
|
|
141 `0 (zero)' |
|
|
142 The `0'th word. For many applications, this is the command word. |
|
|
143 |
|
|
144 `N' |
|
|
145 The Nth word. |
|
|
146 |
|
|
147 `^' |
|
|
148 The first argument; that is, word 1. |
|
|
149 |
|
|
150 `$' |
|
|
151 The last argument. |
|
|
152 |
|
|
153 `%' |
|
|
154 The word matched by the most recent `?STRING?' search. |
|
|
155 |
|
|
156 `X-Y' |
|
|
157 A range of words; `-Y' abbreviates `0-Y'. |
|
|
158 |
|
|
159 `*' |
|
|
160 All of the words, except the `0'th. This is a synonym for `1-$'. |
|
|
161 It is not an error to use `*' if there is just one word in the |
|
|
162 event; the empty string is returned in that case. |
|
|
163 |
|
|
164 `X*' |
|
|
165 Abbreviates `X-$' |
|
|
166 |
|
|
167 `X-' |
|
|
168 Abbreviates `X-$' like `X*', but omits the last word. |
|
|
169 |
|
|
170 If a word designator is supplied without an event specification, the |
|
|
171 previous command is used as the event. |
|
|
172 |
|
|
173 |
|
|
174 File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction |
|
|
175 |
|
|
176 Modifiers |
|
|
177 --------- |
|
|
178 |
|
|
179 After the optional word designator, you can add a sequence of one or |
|
|
180 more of the following modifiers, each preceded by a `:'. |
|
|
181 |
|
|
182 `h' |
|
|
183 Remove a trailing pathname component, leaving only the head. |
|
|
184 |
|
|
185 `t' |
|
|
186 Remove all leading pathname components, leaving the tail. |
|
|
187 |
|
|
188 `r' |
|
|
189 Remove a trailing suffix of the form `.SUFFIX', leaving the |
|
|
190 basename. |
|
|
191 |
|
|
192 `e' |
|
|
193 Remove all but the trailing suffix. |
|
|
194 |
|
|
195 `p' |
|
|
196 Print the new command but do not execute it. |
|
|
197 |
|
|
198 `s/OLD/NEW/' |
|
|
199 Substitute NEW for the first occurrence of OLD in the event line. |
|
|
200 Any delimiter may be used in place of `/'. The delimiter may be |
|
|
201 quoted in OLD and NEW with a single backslash. If `&' appears in |
|
|
202 NEW, it is replaced by OLD. A single backslash will quote the |
|
|
203 `&'. The final delimiter is optional if it is the last character |
|
|
204 on the input line. |
|
|
205 |
|
|
206 `&' |
|
|
207 Repeat the previous substitution. |
|
|
208 |
|
|
209 `g' |
|
|
210 Cause changes to be applied over the entire event line. Used in |
|
|
211 conjunction with `s', as in `gs/OLD/NEW/', or with `&'. |
|
|
212 |
|
|
213 |
|
|
214 File: history.info, Node: Programming with GNU History, Next: Concept Index, Prev: Using History Interactively, Up: Top |
|
|
215 |
|
|
216 Programming with GNU History |
|
|
217 **************************** |
|
|
218 |
|
|
219 This chapter describes how to interface programs that you write with |
|
|
220 the GNU History Library. It should be considered a technical guide. |
|
|
221 For information on the interactive use of GNU History, *note Using |
|
|
222 History Interactively::.. |
|
|
223 |
|
|
224 * Menu: |
|
|
225 |
|
|
226 * Introduction to History:: What is the GNU History library for? |
|
|
227 * History Storage:: How information is stored. |
|
|
228 * History Functions:: Functions that you can use. |
|
|
229 * History Variables:: Variables that control behaviour. |
|
|
230 * History Programming Example:: Example of using the GNU History Library. |
|
|
231 |
|
|
232 |
|
|
233 File: history.info, Node: Introduction to History, Next: History Storage, Up: Programming with GNU History |
|
|
234 |
|
|
235 Introduction to History |
|
|
236 ======================= |
|
|
237 |
|
|
238 Many programs read input from the user a line at a time. The GNU |
|
|
239 History library is able to keep track of those lines, associate |
|
|
240 arbitrary data with each line, and utilize information from previous |
|
|
241 lines in composing new ones. |
|
|
242 |
|
|
243 The programmer using the History library has available functions for |
|
|
244 remembering lines on a history list, associating arbitrary data with a |
|
|
245 line, removing lines from the list, searching through the list for a |
|
|
246 line containing an arbitrary text string, and referencing any line in |
|
|
247 the list directly. In addition, a history "expansion" function is |
|
|
248 available which provides for a consistent user interface across |
|
|
249 different programs. |
|
|
250 |
|
|
251 The user using programs written with the History library has the |
|
|
252 benefit of a consistent user interface with a set of well-known |
|
|
253 commands for manipulating the text of previous lines and using that text |
|
|
254 in new commands. The basic history manipulation commands are similar to |
|
|
255 the history substitution provided by `csh'. |
|
|
256 |
|
|
257 If the programmer desires, he can use the Readline library, which |
|
|
258 includes some history manipulation by default, and has the added |
|
|
259 advantage of command line editing. |
|
|
260 |
|
|
261 |
|
|
262 File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History |
|
|
263 |
|
|
264 History Storage |
|
|
265 =============== |
|
|
266 |
|
|
267 The history list is an array of history entries. A history entry is |
|
|
268 declared as follows: |
|
|
269 |
|
|
270 typedef struct _hist_entry { |
|
|
271 char *line; |
|
|
272 char *data; |
|
|
273 } HIST_ENTRY; |
|
|
274 |
|
|
275 The history list itself might therefore be declared as |
|
|
276 |
|
|
277 HIST_ENTRY **the_history_list; |
|
|
278 |
|
|
279 The state of the History library is encapsulated into a single |
|
|
280 structure: |
|
|
281 |
|
|
282 /* A structure used to pass the current state of the history stuff around. */ |
|
|
283 typedef struct _hist_state { |
|
|
284 HIST_ENTRY **entries; /* Pointer to the entries themselves. */ |
|
|
285 int offset; /* The location pointer within this array. */ |
|
|
286 int length; /* Number of elements within this array. */ |
|
|
287 int size; /* Number of slots allocated to this array. */ |
|
|
288 int flags; |
|
|
289 } HISTORY_STATE; |
|
|
290 |
|
|
291 If the flags member includes `HS_STIFLED', the history has been |
|
|
292 stifled. |
|
|
293 |
|
|
294 |
|
|
295 File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History |
|
|
296 |
|
|
297 History Functions |
|
|
298 ================= |
|
|
299 |
|
|
300 This section describes the calling sequence for the various functions |
|
|
301 present in GNU History. |
|
|
302 |
|
|
303 * Menu: |
|
|
304 |
|
|
305 * Initializing History and State Management:: Functions to call when you |
|
|
306 want to use history in a |
|
|
307 program. |
|
|
308 * History List Management:: Functions used to manage the list |
|
|
309 of history entries. |
|
|
310 * Information About the History List:: Functions returning information about |
|
|
311 the history list. |
|
|
312 * Moving Around the History List:: Functions used to change the position |
|
|
313 in the history list. |
|
|
314 * Searching the History List:: Functions to search the history list |
|
|
315 for entries containing a string. |
|
|
316 * Managing the History File:: Functions that read and write a file |
|
|
317 containing the history list. |
|
|
318 * History Expansion:: Functions to perform csh-like history |
|
|
319 expansion. |
|
|
320 |
|
|
321 |
|
|
322 File: history.info, Node: Initializing History and State Management, Next: History List Management, Up: History Functions |
|
|
323 |
|
|
324 Initializing History and State Management |
|
|
325 ----------------------------------------- |
|
|
326 |
|
|
327 This section describes functions used to initialize and manage the |
|
|
328 state of the History library when you want to use the history functions |
|
|
329 in your program. |
|
|
330 |
|
|
331 - Function: void using_history () |
|
|
332 Begin a session in which the history functions might be used. This |
|
|
333 initializes the interactive variables. |
|
|
334 |
|
|
335 - Function: HISTORY_STATE * history_get_history_state () |
|
|
336 Return a structure describing the current state of the input |
|
|
337 history. |
|
|
338 |
|
|
339 - Function: void history_set_history_state (HISTORY_STATE *state) |
|
|
340 Set the state of the history list according to STATE. |
|
|
341 |
|
|
342 |
|
|
343 File: history.info, Node: History List Management, Next: Information About the History List, Prev: Initializing History and State Management, Up: History Functions |
|
|
344 |
|
|
345 History List Management |
|
|
346 ----------------------- |
|
|
347 |
|
|
348 These functions manage individual entries on the history list, or set |
|
|
349 parameters managing the list itself. |
|
|
350 |
|
|
351 - Function: void add_history (char *string) |
|
|
352 Place STRING at the end of the history list. The associated data |
|
|
353 field (if any) is set to `NULL'. |
|
|
354 |
|
|
355 - Function: HIST_ENTRY * remove_history (int which) |
|
|
356 Remove history entry at offset WHICH from the history. The |
|
|
357 removed element is returned so you can free the line, data, and |
|
|
358 containing structure. |
|
|
359 |
|
|
360 - Function: HIST_ENTRY * replace_history_entry (int which, char *line, |
|
|
361 char *data) |
|
|
362 Make the history entry at offset WHICH have LINE and DATA. This |
|
|
363 returns the old entry so you can dispose of the data. In the case |
|
|
364 of an invalid WHICH, a `NULL' pointer is returned. |
|
|
365 |
|
|
366 - Function: void clear_history () |
|
|
367 Clear the history list by deleting all the entries. |
|
|
368 |
|
|
369 - Function: void stifle_history (int max) |
|
|
370 Stifle the history list, remembering only the last MAX entries. |
|
|
371 |
|
|
372 - Function: int unstifle_history () |
|
|
373 Stop stifling the history. This returns the previous amount the |
|
|
374 history was stifled. The value is positive if the history was |
|
|
375 stifled, negative if it wasn't. |
|
|
376 |
|
|
377 - Function: int history_is_stifled () |
|
|
378 Returns non-zero if the history is stifled, zero if it is not. |
|
|
379 |
|
|
380 |
|
|
381 File: history.info, Node: Information About the History List, Next: Moving Around the History List, Prev: History List Management, Up: History Functions |
|
|
382 |
|
|
383 Information About the History List |
|
|
384 ---------------------------------- |
|
|
385 |
|
|
386 These functions return information about the entire history list or |
|
|
387 individual list entries. |
|
|
388 |
|
|
389 - Function: HIST_ENTRY ** history_list () |
|
|
390 Return a `NULL' terminated array of `HIST_ENTRY' which is the |
|
|
391 current input history. Element 0 of this list is the beginning of |
|
|
392 time. If there is no history, return `NULL'. |
|
|
393 |
|
|
394 - Function: int where_history () |
|
|
395 Returns the offset of the current history element. |
|
|
396 |
|
|
397 - Function: HIST_ENTRY * current_history () |
|
|
398 Return the history entry at the current position, as determined by |
|
|
399 `where_history ()'. If there is no entry there, return a `NULL' |
|
|
400 pointer. |
|
|
401 |
|
|
402 - Function: HIST_ENTRY * history_get (int offset) |
|
|
403 Return the history entry at position OFFSET, starting from |
|
|
404 `history_base'. If there is no entry there, or if OFFSET is |
|
|
405 greater than the history length, return a `NULL' pointer. |
|
|
406 |
|
|
407 - Function: int history_total_bytes () |
|
|
408 Return the number of bytes that the primary history entries are |
|
|
409 using. This function returns the sum of the lengths of all the |
|
|
410 lines in the history. |
|
|
411 |
|
|
412 |
|
|
413 File: history.info, Node: Moving Around the History List, Next: Searching the History List, Prev: Information About the History List, Up: History Functions |
|
|
414 |
|
|
415 Moving Around the History List |
|
|
416 ------------------------------ |
|
|
417 |
|
|
418 These functions allow the current index into the history list to be |
|
|
419 set or changed. |
|
|
420 |
|
|
421 - Function: int history_set_pos (int pos) |
|
|
422 Set the position in the history list to POS, an absolute index |
|
|
423 into the list. |
|
|
424 |
|
|
425 - Function: HIST_ENTRY * previous_history () |
|
|
426 Back up the current history offset to the previous history entry, |
|
|
427 and return a pointer to that entry. If there is no previous |
|
|
428 entry, return a `NULL' pointer. |
|
|
429 |
|
|
430 - Function: HIST_ENTRY * next_history () |
|
|
431 Move the current history offset forward to the next history entry, |
|
|
432 and return the a pointer to that entry. If there is no next |
|
|
433 entry, return a `NULL' pointer. |
|
|
434 |
|
|
435 |
|
|
436 File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions |
|
|
437 |
|
|
438 Searching the History List |
|
|
439 -------------------------- |
|
|
440 |
|
|
441 These functions allow searching of the history list for entries |
|
|
442 containing a specific string. Searching may be performed both forward |
|
|
443 and backward from the current history position. The search may be |
|
|
444 "anchored", meaning that the string must match at the beginning of the |
|
|
445 history entry. |
|
|
446 |
|
|
447 - Function: int history_search (char *string, int direction) |
|
|
448 Search the history for STRING, starting at the current history |
|
|
449 offset. If DIRECTION < 0, then the search is through previous |
|
|
450 entries, else through subsequent. If STRING is found, then the |
|
|
451 current history index is set to that history entry, and the value |
|
|
452 returned is the offset in the line of the entry where STRING was |
|
|
453 found. Otherwise, nothing is changed, and a -1 is returned. |
|
|
454 |
|
|
455 - Function: int history_search_prefix (char *string, int direction) |
|
|
456 Search the history for STRING, starting at the current history |
|
|
457 offset. The search is anchored: matching lines must begin with |
|
|
458 STRING. If DIRECTION < 0, then the search is through previous |
|
|
459 entries, else through subsequent. If STRING is found, then the |
|
|
460 current history index is set to that entry, and the return value |
|
|
461 is 0. Otherwise, nothing is changed, and a -1 is returned. |
|
|
462 |
|
|
463 - Function: int history_search_pos (char *string, int direction, int |
|
|
464 pos) |
|
|
465 Search for STRING in the history list, starting at POS, an |
|
|
466 absolute index into the list. If DIRECTION is negative, the search |
|
|
467 proceeds backward from POS, otherwise forward. Returns the |
|
|
468 absolute index of the history element where STRING was found, or |
|
|
469 -1 otherwise. |
|
|
470 |
|
|
471 |
|
|
472 File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions |
|
|
473 |
|
|
474 Managing the History File |
|
|
475 ------------------------- |
|
|
476 |
|
|
477 The History library can read the history from and write it to a file. |
|
|
478 This section documents the functions for managing a history file. |
|
|
479 |
|
|
480 - Function: int read_history (char *filename) |
|
|
481 Add the contents of FILENAME to the history list, a line at a |
|
|
482 time. If FILENAME is `NULL', then read from `~/.history'. |
|
|
483 Returns 0 if successful, or errno if not. |
|
|
484 |
|
|
485 - Function: int read_history_range (char *filename, int from, int to) |
|
|
486 Read a range of lines from FILENAME, adding them to the history |
|
|
487 list. Start reading at line FROM and end at TO. If FROM is zero, |
|
|
488 start at the beginning. If TO is less than FROM, then read until |
|
|
489 the end of the file. If FILENAME is `NULL', then read from |
|
|
490 `~/.history'. Returns 0 if successful, or `errno' if not. |
|
|
491 |
|
|
492 - Function: int write_history (char *filename) |
|
|
493 Write the current history to FILENAME, overwriting FILENAME if |
|
|
494 necessary. If FILENAME is `NULL', then write the history list to |
|
|
495 `~/.history'. Values returned are as in `read_history ()'. |
|
|
496 |
|
|
497 - Function: int append_history (int nelements, char *filename) |
|
|
498 Append the last NELEMENTS of the history list to FILENAME. |
|
|
499 |
|
|
500 - Function: int history_truncate_file (char *filename, int nlines) |
|
|
501 Truncate the history file FILENAME, leaving only the last NLINES |
|
|
502 lines. |
|
|
503 |
|
|
504 |
|
|
505 File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions |
|
|
506 |
|
|
507 History Expansion |
|
|
508 ----------------- |
|
|
509 |
|
|
510 These functions implement `csh'-like history expansion. |
|
|
511 |
|
|
512 - Function: int history_expand (char *string, char **output) |
|
|
513 Expand STRING, placing the result into OUTPUT, a pointer to a |
|
|
514 string (*note History Interaction::.). Returns: |
|
|
515 `0' |
|
|
516 If no expansions took place (or, if the only change in the |
|
|
517 text was the de-slashifying of the history expansion |
|
|
518 character); |
|
|
519 |
|
|
520 `1' |
|
|
521 if expansions did take place; |
|
|
522 |
|
|
523 `-1' |
|
|
524 if there was an error in expansion; |
|
|
525 |
|
|
526 `2' |
|
|
527 if the returned line should only be displayed, but not |
|
|
528 executed, as with the `:p' modifier (*note Modifiers::.). |
|
|
529 |
|
|
530 If an error ocurred in expansion, then OUTPUT contains a |
|
|
531 descriptive error message. |
|
|
532 |
|
|
533 - Function: char * history_arg_extract (int first, int last, char |
|
|
534 *string) |
|
|
535 Extract a string segment consisting of the FIRST through LAST |
|
|
536 arguments present in STRING. Arguments are broken up as in Bash. |
|
|
537 |
|
|
538 - Function: char * get_history_event (char *string, int *cindex, int |
|
|
539 qchar) |
|
|
540 Returns the text of the history event beginning at STRING + |
|
|
541 *CINDEX. *CINDEX is modified to point to after the event |
|
|
542 specifier. At function entry, CINDEX points to the index into |
|
|
543 STRING where the history event specification begins. QCHAR is a |
|
|
544 character that is allowed to end the event specification in |
|
|
545 addition to the "normal" terminating characters. |
|
|
546 |
|
|
547 - Function: char ** history_tokenize (char *string) |
|
|
548 Return an array of tokens parsed out of STRING, much as the shell |
|
|
549 might. The tokens are split on white space and on the characters |
|
|
550 `()<>;&|$', and shell quoting conventions are obeyed. |
|
|
551 |
|
|
552 |
|
|
553 File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History |
|
|
554 |
|
|
555 History Variables |
|
|
556 ================= |
|
|
557 |
|
|
558 This section describes the externally visible variables exported by |
|
|
559 the GNU History Library. |
|
|
560 |
|
|
561 - Variable: int history_base |
|
|
562 The logical offset of the first entry in the history list. |
|
|
563 |
|
|
564 - Variable: int history_length |
|
|
565 The number of entries currently stored in the history list. |
|
|
566 |
|
|
567 - Variable: int max_input_history |
|
|
568 The maximum number of history entries. This must be changed using |
|
|
569 `stifle_history ()'. |
|
|
570 |
|
|
571 - Variable: char history_expansion_char |
|
|
572 The character that starts a history event. The default is `!'. |
|
|
573 |
|
|
574 - Variable: char history_subst_char |
|
|
575 The character that invokes word substitution if found at the start |
|
|
576 of a line. The default is `^'. |
|
|
577 |
|
|
578 - Variable: char history_comment_char |
|
|
579 During tokenization, if this character is seen as the first |
|
|
580 character of a word, then it and all subsequent characters up to a |
|
|
581 newline are ignored, suppressing history expansion for the |
|
|
582 remainder of the line. This is disabled by default. |
|
|
583 |
|
|
584 - Variable: char * history_no_expand_chars |
|
|
585 The list of characters which inhibit history expansion if found |
|
|
586 immediately following HISTORY_EXPANSION_CHAR. The default is |
|
|
587 whitespace and `='. |
|
|
588 |
|
|
589 - Variable: char * history_search_delimiter_chars |
|
|
590 The list of additional characters which can delimit a history |
|
|
591 search string, in addition to whitespace, `:' and `?' in the case |
|
|
592 of a substring search. The default is empty. |
|
|
593 |
|
|
594 - Variable: int history_quotes_inhibit_expansion |
|
|
595 If non-zero, single-quoted words are not scanned for the history |
|
|
596 expansion character. The default value is 0. |
|
|
597 |
|
|
598 - Variable: Function * history_inhibit_expansion_function |
|
|
599 This should be set to the address of a function that takes two |
|
|
600 arguments: a `char *' (STRING) and an integer index into that |
|
|
601 string (I). It should return a non-zero value if the history |
|
|
602 expansion starting at STRING[I] should not be performed; zero if |
|
|
603 the expansion should be done. It is intended for use by |
|
|
604 applications like Bash that use the history expansion character |
|
|
605 for additional purposes. By default, this variable is set to NULL. |
|
|
606 |
|
|
607 |
|
|
608 File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History |
|
|
609 |
|
|
610 History Programming Example |
|
|
611 =========================== |
|
|
612 |
|
|
613 The following program demonstrates simple use of the GNU History |
|
|
614 Library. |
|
|
615 |
|
|
616 main () |
|
|
617 { |
|
|
618 char line[1024], *t; |
|
|
619 int len, done = 0; |
|
|
620 |
|
|
621 line[0] = 0; |
|
|
622 |
|
|
623 using_history (); |
|
|
624 while (!done) |
|
|
625 { |
|
|
626 printf ("history$ "); |
|
|
627 fflush (stdout); |
|
|
628 t = fgets (line, sizeof (line) - 1, stdin); |
|
|
629 if (t && *t) |
|
|
630 { |
|
|
631 len = strlen (t); |
|
|
632 if (t[len - 1] == '\n') |
|
|
633 t[len - 1] = '\0'; |
|
|
634 } |
|
|
635 |
|
|
636 if (!t) |
|
|
637 strcpy (line, "quit"); |
|
|
638 |
|
|
639 if (line[0]) |
|
|
640 { |
|
|
641 char *expansion; |
|
|
642 int result; |
|
|
643 |
|
|
644 result = history_expand (line, &expansion); |
|
|
645 if (result) |
|
|
646 fprintf (stderr, "%s\n", expansion); |
|
|
647 |
|
|
648 if (result < 0 || result == 2) |
|
|
649 { |
|
|
650 free (expansion); |
|
|
651 continue; |
|
|
652 } |
|
|
653 |
|
|
654 add_history (expansion); |
|
|
655 strncpy (line, expansion, sizeof (line) - 1); |
|
|
656 free (expansion); |
|
|
657 } |
|
|
658 |
|
|
659 if (strcmp (line, "quit") == 0) |
|
|
660 done = 1; |
|
|
661 else if (strcmp (line, "save") == 0) |
|
|
662 write_history ("history_file"); |
|
|
663 else if (strcmp (line, "read") == 0) |
|
|
664 read_history ("history_file"); |
|
|
665 else if (strcmp (line, "list") == 0) |
|
|
666 { |
|
|
667 register HIST_ENTRY **the_list; |
|
|
668 register int i; |
|
|
669 |
|
|
670 the_list = history_list (); |
|
|
671 if (the_list) |
|
|
672 for (i = 0; the_list[i]; i++) |
|
|
673 printf ("%d: %s\n", i + history_base, the_list[i]->line); |
|
|
674 } |
|
|
675 else if (strncmp (line, "delete", 6) == 0) |
|
|
676 { |
|
|
677 int which; |
|
|
678 if ((sscanf (line + 6, "%d", &which)) == 1) |
|
|
679 { |
|
|
680 HIST_ENTRY *entry = remove_history (which); |
|
|
681 if (!entry) |
|
|
682 fprintf (stderr, "No such entry %d\n", which); |
|
|
683 else |
|
|
684 { |
|
|
685 free (entry->line); |
|
|
686 free (entry); |
|
|
687 } |
|
|
688 } |
|
|
689 else |
|
|
690 { |
|
|
691 fprintf (stderr, "non-numeric arg given to `delete'\n"); |
|
|
692 } |
|
|
693 } |
|
|
694 } |
|
|
695 } |
|
|
696 |
|
|
697 |
|
|
698 File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU History, Up: Top |
|
|
699 |
|
|
700 Concept Index |
|
|
701 ************* |
|
|
702 |
|
|
703 * Menu: |
|
|
704 |
|
|
705 * anchored search: Searching the History List. |
|
|
706 * event designators: Event Designators. |
|
|
707 * history events: Event Designators. |
|
|
708 * history expansion: History Interaction. |
|
|
709 * History Searching: Searching the History List. |
|
|
710 |
|
|
711 |
|
|
712 File: history.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top |
|
|
713 |
|
|
714 Function and Variable Index |
|
|
715 *************************** |
|
|
716 |
|
|
717 * Menu: |
|
|
718 |
|
|
719 * add_history: History List Management. |
|
|
720 * append_history: Managing the History File. |
|
|
721 * clear_history: History List Management. |
|
|
722 * current_history: Information About the History List. |
|
|
723 * get_history_event: History Expansion. |
|
|
724 * history_arg_extract: History Expansion. |
|
|
725 * history_base: History Variables. |
|
|
726 * history_comment_char: History Variables. |
|
|
727 * history_expand: History Expansion. |
|
|
728 * history_expansion_char: History Variables. |
|
|
729 * history_get: Information About the History List. |
|
|
730 * history_get_history_state: Initializing History and State Management. |
|
|
731 * history_inhibit_expansion_function: History Variables. |
|
|
732 * history_is_stifled: History List Management. |
|
|
733 * history_length: History Variables. |
|
|
734 * history_list: Information About the History List. |
|
|
735 * history_no_expand_chars: History Variables. |
|
|
736 * history_quotes_inhibit_expansion: History Variables. |
|
|
737 * history_search: Searching the History List. |
|
|
738 * history_search_delimiter_chars: History Variables. |
|
|
739 * history_search_pos: Searching the History List. |
|
|
740 * history_search_prefix: Searching the History List. |
|
|
741 * history_set_history_state: Initializing History and State Management. |
|
|
742 * history_set_pos: Moving Around the History List. |
|
|
743 * history_subst_char: History Variables. |
|
|
744 * history_tokenize: History Expansion. |
|
|
745 * history_total_bytes: Information About the History List. |
|
|
746 * history_truncate_file: Managing the History File. |
|
|
747 * max_input_history: History Variables. |
|
|
748 * next_history: Moving Around the History List. |
|
|
749 * previous_history: Moving Around the History List. |
|
|
750 * read_history: Managing the History File. |
|
|
751 * read_history_range: Managing the History File. |
|
|
752 * remove_history: History List Management. |
|
|
753 * replace_history_entry: History List Management. |
|
|
754 * stifle_history: History List Management. |
|
|
755 * unstifle_history: History List Management. |
|
|
756 * using_history: Initializing History and State Management. |
|
|
757 * where_history: Information About the History List. |
|
|
758 * write_history: Managing the History File. |
|
|
759 |
|
|
760 |
|
|
761 |
|
|
762 Tag Table: |
|
|
763 Node: Top1035 |
|
|
764 Node: Using History Interactively1629 |
|
|
765 Node: History Interaction2137 |
|
|
766 Node: Event Designators3614 |
|
|
767 Node: Word Designators4537 |
|
|
768 Node: Modifiers5786 |
|
|
769 Node: Programming with GNU History6924 |
|
|
770 Node: Introduction to History7650 |
|
|
771 Node: History Storage8971 |
|
|
772 Node: History Functions10064 |
|
|
773 Node: Initializing History and State Management11035 |
|
|
774 Node: History List Management11827 |
|
|
775 Node: Information About the History List13348 |
|
|
776 Node: Moving Around the History List14654 |
|
|
777 Node: Searching the History List15539 |
|
|
778 Node: Managing the History File17371 |
|
|
779 Node: History Expansion18877 |
|
|
780 Node: History Variables20721 |
|
|
781 Node: History Programming Example23039 |
|
|
782 Node: Concept Index25643 |
|
|
783 Node: Function and Variable Index26124 |
|
|
784 |
|
|
785 End Tag Table |
