OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [gdb-5.0/] [readline/] [doc/] [hstech.texinfo] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 106 markom
@ignore
2
This file documents the user interface to the GNU History library.
3
 
4
Copyright (C) 1988, 1991, 1994, 1996 Free Software Foundation, Inc.
5
Authored by Brian Fox and Chet Ramey.
6
 
7
Permission is granted to make and distribute verbatim copies of this manual
8
provided the copyright notice and this permission notice are preserved on
9
all copies.
10
 
11
Permission is granted to process this file through Tex and print the
12
results, provided the printed document carries copying permission notice
13
identical to this one except for the removal of this paragraph (this
14
paragraph not being relevant to the printed manual).
15
 
16
Permission is granted to copy and distribute modified versions of this
17
manual under the conditions for verbatim copying, provided also that the
18
GNU Copyright statement is available to the distributee, and provided that
19
the entire resulting derived work is distributed under the terms of a
20
permission notice identical to this one.
21
 
22
Permission is granted to copy and distribute translations of this manual
23
into another language, under the above conditions for modified versions.
24
@end ignore
25
 
26
@node Programming with GNU History
27
@chapter Programming with GNU History
28
 
29
This chapter describes how to interface programs that you write
30
with the GNU History Library.
31
It should be considered a technical guide.
32
For information on the interactive use of GNU History, @pxref{Using
33
History Interactively}.
34
 
35
@menu
36
* Introduction to History::     What is the GNU History library for?
37
* History Storage::             How information is stored.
38
* History Functions::           Functions that you can use.
39
* History Variables::           Variables that control behaviour.
40
* History Programming Example:: Example of using the GNU History Library.
41
@end menu
42
 
43
@node Introduction to History
44
@section Introduction to History
45
 
46
Many programs read input from the user a line at a time.  The GNU History
47
library is able to keep track of those lines, associate arbitrary data with
48
each line, and utilize information from previous lines in composing new
49
ones.
50
 
51
The programmer using the History library has available functions
52
for remembering lines on a history list, associating arbitrary data
53
with a line, removing lines from the list, searching through the list
54
for a line containing an arbitrary text string, and referencing any line
55
in the list directly.  In addition, a history @dfn{expansion} function
56
is available which provides for a consistent user interface across
57
different programs.
58
 
59
The user using programs written with the History library has the
60
benefit of a consistent user interface with a set of well-known
61
commands for manipulating the text of previous lines and using that text
62
in new commands.  The basic history manipulation commands are similar to
63
the history substitution provided by @code{csh}.
64
 
65
If the programmer desires, he can use the Readline library, which
66
includes some history manipulation by default, and has the added
67
advantage of command line editing.
68
 
69
@node History Storage
70
@section History Storage
71
 
72
The history list is an array of history entries.  A history entry is
73
declared as follows:
74
 
75
@example
76
typedef struct _hist_entry @{
77
  char *line;
78
  char *data;
79
@} HIST_ENTRY;
80
@end example
81
 
82
The history list itself might therefore be declared as
83
 
84
@example
85
HIST_ENTRY **the_history_list;
86
@end example
87
 
88
The state of the History library is encapsulated into a single structure:
89
 
90
@example
91
/* A structure used to pass the current state of the history stuff around. */
92
typedef struct _hist_state @{
93
  HIST_ENTRY **entries;         /* Pointer to the entries themselves. */
94
  int offset;                   /* The location pointer within this array. */
95
  int length;                   /* Number of elements within this array. */
96
  int size;                     /* Number of slots allocated to this array. */
97
  int flags;
98
@} HISTORY_STATE;
99
@end example
100
 
101
If the flags member includes @code{HS_STIFLED}, the history has been
102
stifled.
103
 
104
@node History Functions
105
@section History Functions
106
 
107
This section describes the calling sequence for the various functions
108
present in GNU History.
109
 
110
@menu
111
* Initializing History and State Management::   Functions to call when you
112
                                                want to use history in a
113
                                                program.
114
* History List Management::             Functions used to manage the list
115
                                        of history entries.
116
* Information About the History List::  Functions returning information about
117
                                        the history list.
118
* Moving Around the History List::      Functions used to change the position
119
                                        in the history list.
120
* Searching the History List::          Functions to search the history list
121
                                        for entries containing a string.
122
* Managing the History File::           Functions that read and write a file
123
                                        containing the history list.
124
* History Expansion::                   Functions to perform csh-like history
125
                                        expansion.
126
@end menu
127
 
128
@node Initializing History and State Management
129
@subsection Initializing History and State Management
130
 
131
This section describes functions used to initialize and manage
132
the state of the History library when you want to use the history
133
functions in your program.
134
 
135
@deftypefun void using_history ()
136
Begin a session in which the history functions might be used.  This
137
initializes the interactive variables.
138
@end deftypefun
139
 
140
@deftypefun {HISTORY_STATE *} history_get_history_state ()
141
Return a structure describing the current state of the input history.
142
@end deftypefun
143
 
144
@deftypefun void history_set_history_state (HISTORY_STATE *state)
145
Set the state of the history list according to @var{state}.
146
@end deftypefun
147
 
148
@node History List Management
149
@subsection History List Management
150
 
151
These functions manage individual entries on the history list, or set
152
parameters managing the list itself.
153
 
154
@deftypefun void add_history (char *string)
155
Place @var{string} at the end of the history list.  The associated data
156
field (if any) is set to @code{NULL}.
157
@end deftypefun
158
 
159
@deftypefun {HIST_ENTRY *} remove_history (int which)
160
Remove history entry at offset @var{which} from the history.  The
161
removed element is returned so you can free the line, data,
162
and containing structure.
163
@end deftypefun
164
 
165
@deftypefun {HIST_ENTRY *} replace_history_entry (int which, char *line, char *data)
166
Make the history entry at offset @var{which} have @var{line} and @var{data}.
167
This returns the old entry so you can dispose of the data.  In the case
168
of an invalid @var{which}, a @code{NULL} pointer is returned.
169
@end deftypefun
170
 
171
@deftypefun void clear_history ()
172
Clear the history list by deleting all the entries.
173
@end deftypefun
174
 
175
@deftypefun void stifle_history (int max)
176
Stifle the history list, remembering only the last @var{max} entries.
177
@end deftypefun
178
 
179
@deftypefun int unstifle_history ()
180
Stop stifling the history.  This returns the previous amount the
181
history was stifled.  The value is positive if the history was
182
stifled, negative if it wasn't.
183
@end deftypefun
184
 
185
@deftypefun int history_is_stifled ()
186
Returns non-zero if the history is stifled, zero if it is not.
187
@end deftypefun
188
 
189
@node Information About the History List
190
@subsection Information About the History List
191
 
192
These functions return information about the entire history list or
193
individual list entries.
194
 
195
@deftypefun {HIST_ENTRY **} history_list ()
196
Return a @code{NULL} terminated array of @code{HIST_ENTRY} which is the
197
current input history.  Element 0 of this list is the beginning of time.
198
If there is no history, return @code{NULL}.
199
@end deftypefun
200
 
201
@deftypefun int where_history ()
202
Returns the offset of the current history element.
203
@end deftypefun
204
 
205
@deftypefun {HIST_ENTRY *} current_history ()
206
Return the history entry at the current position, as determined by
207
@code{where_history ()}.  If there is no entry there, return a @code{NULL}
208
pointer.
209
@end deftypefun
210
 
211
@deftypefun {HIST_ENTRY *} history_get (int offset)
212
Return the history entry at position @var{offset}, starting from
213
@code{history_base}.  If there is no entry there, or if @var{offset}
214
is greater than the history length, return a @code{NULL} pointer.
215
@end deftypefun
216
 
217
@deftypefun int history_total_bytes ()
218
Return the number of bytes that the primary history entries are using.
219
This function returns the sum of the lengths of all the lines in the
220
history.
221
@end deftypefun
222
 
223
@node Moving Around the History List
224
@subsection Moving Around the History List
225
 
226
These functions allow the current index into the history list to be
227
set or changed.
228
 
229
@deftypefun int history_set_pos (int pos)
230
Set the position in the history list to @var{pos}, an absolute index
231
into the list.
232
@end deftypefun
233
 
234
@deftypefun {HIST_ENTRY *} previous_history ()
235
Back up the current history offset to the previous history entry, and
236
return a pointer to that entry.  If there is no previous entry, return
237
a @code{NULL} pointer.
238
@end deftypefun
239
 
240
@deftypefun {HIST_ENTRY *} next_history ()
241
Move the current history offset forward to the next history entry, and
242
return the a pointer to that entry.  If there is no next entry, return
243
a @code{NULL} pointer.
244
@end deftypefun
245
 
246
@node Searching the History List
247
@subsection Searching the History List
248
@cindex History Searching
249
 
250
These functions allow searching of the history list for entries containing
251
a specific string.  Searching may be performed both forward and backward
252
from the current history position.  The search may be @dfn{anchored},
253
meaning that the string must match at the beginning of the history entry.
254
@cindex anchored search
255
 
256
@deftypefun int history_search (char *string, int direction)
257
Search the history for @var{string}, starting at the current history
258
offset.  If @var{direction} < 0, then the search is through previous entries,
259
else through subsequent.  If @var{string} is found, then
260
the current history index is set to that history entry, and the value
261
returned is the offset in the line of the entry where
262
@var{string} was found.  Otherwise, nothing is changed, and a -1 is
263
returned.
264
@end deftypefun
265
 
266
@deftypefun int history_search_prefix (char *string, int direction)
267
Search the history for @var{string}, starting at the current history
268
offset.  The search is anchored: matching lines must begin with
269
@var{string}.  If @var{direction} < 0, then the search is through previous
270
entries, else through subsequent.  If @var{string} is found, then the
271
current history index is set to that entry, and the return value is 0.
272
Otherwise, nothing is changed, and a -1 is returned.
273
@end deftypefun
274
 
275
@deftypefun int history_search_pos (char *string, int direction, int pos)
276
Search for @var{string} in the history list, starting at @var{pos}, an
277
absolute index into the list.  If @var{direction} is negative, the search
278
proceeds backward from @var{pos}, otherwise forward.  Returns the absolute
279
index of the history element where @var{string} was found, or -1 otherwise.
280
@end deftypefun
281
 
282
@node Managing the History File
283
@subsection Managing the History File
284
 
285
The History library can read the history from and write it to a file.
286
This section documents the functions for managing a history file.
287
 
288
@deftypefun int read_history (char *filename)
289
Add the contents of @var{filename} to the history list, a line at a
290
time.  If @var{filename} is @code{NULL}, then read from
291
@file{~/.history}.  Returns 0 if successful, or errno if not.
292
@end deftypefun
293
 
294
@deftypefun int read_history_range (char *filename, int from, int to)
295
Read a range of lines from @var{filename}, adding them to the history list.
296
Start reading at line @var{from} and end at @var{to}.  If
297
@var{from} is zero, start at the beginning.  If @var{to} is less than
298
@var{from}, then read until the end of the file.  If @var{filename} is
299
@code{NULL}, then read from @file{~/.history}.  Returns 0 if successful,
300
or @code{errno} if not.
301
@end deftypefun
302
 
303
@deftypefun int write_history (char *filename)
304
Write the current history to @var{filename}, overwriting @var{filename}
305
if necessary.  If @var{filename} is
306
@code{NULL}, then write the history list to @file{~/.history}.  Values
307
returned are as in @code{read_history ()}.
308
@end deftypefun
309
 
310
@deftypefun int append_history (int nelements, char *filename)
311
Append the last @var{nelements} of the history list to @var{filename}.
312
@end deftypefun
313
 
314
@deftypefun int history_truncate_file (char *filename, int nlines)
315
Truncate the history file @var{filename}, leaving only the last
316
@var{nlines} lines.
317
@end deftypefun
318
 
319
@node History Expansion
320
@subsection History Expansion
321
 
322
These functions implement @code{csh}-like history expansion.
323
 
324
@deftypefun int history_expand (char *string, char **output)
325
Expand @var{string}, placing the result into @var{output}, a pointer
326
to a string (@pxref{History Interaction}).  Returns:
327
@table @code
328
@item 0
329
If no expansions took place (or, if the only change in
330
the text was the de-slashifying of the history expansion
331
character);
332
@item 1
333
if expansions did take place;
334
@item -1
335
if there was an error in expansion;
336
@item 2
337
if the returned line should only be displayed, but not executed,
338
as with the @code{:p} modifier (@pxref{Modifiers}).
339
@end table
340
 
341
If an error ocurred in expansion, then @var{output} contains a descriptive
342
error message.
343
@end deftypefun
344
 
345
@deftypefun {char *} history_arg_extract (int first, int last, char *string)
346
Extract a string segment consisting of the @var{first} through @var{last}
347
arguments present in @var{string}.  Arguments are broken up as in Bash.
348
@end deftypefun
349
 
350
@deftypefun {char *} get_history_event (char *string, int *cindex, int qchar)
351
Returns the text of the history event beginning at @var{string} +
352
@var{*cindex}.  @var{*cindex} is modified to point to after the event
353
specifier.  At function entry, @var{cindex} points to the index into
354
@var{string} where the history event specification begins.  @var{qchar}
355
is a character that is allowed to end the event specification in addition
356
to the ``normal'' terminating characters.
357
@end deftypefun
358
 
359
@deftypefun {char **} history_tokenize (char *string)
360
Return an array of tokens parsed out of @var{string}, much as the
361
shell might.  The tokens are split on white space and on the
362
characters @code{()<>;&|$}, and shell quoting conventions are
363
obeyed.
364
@end deftypefun
365
 
366
@node History Variables
367
@section History Variables
368
 
369
This section describes the externally visible variables exported by
370
the GNU History Library.
371
 
372
@deftypevar int history_base
373
The logical offset of the first entry in the history list.
374
@end deftypevar
375
 
376
@deftypevar int history_length
377
The number of entries currently stored in the history list.
378
@end deftypevar
379
 
380
@deftypevar int max_input_history
381
The maximum number of history entries.  This must be changed using
382
@code{stifle_history ()}.
383
@end deftypevar
384
 
385
@deftypevar char history_expansion_char
386
The character that starts a history event.  The default is @samp{!}.
387
@end deftypevar
388
 
389
@deftypevar char history_subst_char
390
The character that invokes word substitution if found at the start of
391
a line.  The default is @samp{^}.
392
@end deftypevar
393
 
394
@deftypevar char history_comment_char
395
During tokenization, if this character is seen as the first character
396
of a word, then it and all subsequent characters up to a newline are
397
ignored, suppressing history expansion for the remainder of the line.
398
This is disabled by default.
399
@end deftypevar
400
 
401
@deftypevar {char *} history_no_expand_chars
402
The list of characters which inhibit history expansion if found immediately
403
following @var{history_expansion_char}.  The default is whitespace and
404
@samp{=}.
405
@end deftypevar
406
 
407
@deftypevar {char *} history_search_delimiter_chars
408
The list of additional characters which can delimit a history search
409
string, in addition to whitespace, @samp{:} and @samp{?} in the case of
410
a substring search.  The default is empty.
411
@end deftypevar
412
 
413
@deftypevar int history_quotes_inhibit_expansion
414
If non-zero, single-quoted words are not scanned for the history expansion
415
character.  The default value is 0.
416
@end deftypevar
417
 
418
@deftypevar {Function *} history_inhibit_expansion_function
419
This should be set to the address of a function that takes two arguments:
420
a @code{char *} (@var{string}) and an integer index into that string (@var{i}).
421
It should return a non-zero value if the history expansion starting at
422
@var{string[i]} should not be performed; zero if the expansion should
423
be done.
424
It is intended for use by applications like Bash that use the history
425
expansion character for additional purposes.
426
By default, this variable is set to NULL.
427
@end deftypevar
428
 
429
@node History Programming Example
430
@section History Programming Example
431
 
432
The following program demonstrates simple use of the GNU History Library.
433
 
434
@smallexample
435
main ()
436
@{
437
  char line[1024], *t;
438
  int len, done = 0;
439
 
440
  line[0] = 0;
441
 
442
  using_history ();
443
  while (!done)
444
    @{
445
      printf ("history$ ");
446
      fflush (stdout);
447
      t = fgets (line, sizeof (line) - 1, stdin);
448
      if (t && *t)
449
        @{
450
          len = strlen (t);
451
          if (t[len - 1] == '\n')
452
            t[len - 1] = '\0';
453
        @}
454
 
455
      if (!t)
456
        strcpy (line, "quit");
457
 
458
      if (line[0])
459
        @{
460
          char *expansion;
461
          int result;
462
 
463
          result = history_expand (line, &expansion);
464
          if (result)
465
            fprintf (stderr, "%s\n", expansion);
466
 
467
          if (result < 0 || result == 2)
468
            @{
469
              free (expansion);
470
              continue;
471
            @}
472
 
473
          add_history (expansion);
474
          strncpy (line, expansion, sizeof (line) - 1);
475
          free (expansion);
476
        @}
477
 
478
      if (strcmp (line, "quit") == 0)
479
        done = 1;
480
      else if (strcmp (line, "save") == 0)
481
        write_history ("history_file");
482
      else if (strcmp (line, "read") == 0)
483
        read_history ("history_file");
484
      else if (strcmp (line, "list") == 0)
485
        @{
486
          register HIST_ENTRY **the_list;
487
          register int i;
488
 
489
          the_list = history_list ();
490
          if (the_list)
491
            for (i = 0; the_list[i]; i++)
492
              printf ("%d: %s\n", i + history_base, the_list[i]->line);
493
        @}
494
      else if (strncmp (line, "delete", 6) == 0)
495
        @{
496
          int which;
497
          if ((sscanf (line + 6, "%d", &which)) == 1)
498
            @{
499
              HIST_ENTRY *entry = remove_history (which);
500
              if (!entry)
501
                fprintf (stderr, "No such entry %d\n", which);
502
              else
503
                @{
504
                  free (entry->line);
505
                  free (entry);
506
                @}
507
            @}
508
          else
509
            @{
510
              fprintf (stderr, "non-numeric arg given to `delete'\n");
511
            @}
512
        @}
513
    @}
514
@}
515
@end smallexample

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.