1/* history.h -- the names of functions that you can call in history. */
2
3/* Copyright (C) 1989-2015 Free Software Foundation, Inc.
4
5 This file contains the GNU History Library (History), a set of
6 routines for managing the text of previously typed lines.
7
8 History is free software: you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation, either version 3 of the License, or
11 (at your option) any later version.
12
13 History is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
17
18 You should have received a copy of the GNU General Public License
19 along with History. If not, see <http://www.gnu.org/licenses/>.
20*/
21
22#ifndef _HISTORY_H_
23#define _HISTORY_H_
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29#include <time.h> /* XXX - for history timestamp code */
30
31#if defined READLINE_LIBRARY
32# include "rlstdc.h"
33# include "rltypedefs.h"
34#else
35# include <stdio.h>
36# include <readline/rlstdc.h>
37# include <readline/rltypedefs.h>
38#endif
39
40#ifdef __STDC__
41typedef void *histdata_t;
42#else
43typedef char *histdata_t;
44#endif
45
46/* The structure used to store a history entry. */
47typedef struct _hist_entry {
48 char *line;
49 char *timestamp; /* char * rather than time_t for read/write */
50 histdata_t data;
51} HIST_ENTRY;
52
53/* Size of the history-library-managed space in history entry HS. */
54#define HISTENT_BYTES(hs) (strlen ((hs)->line) + strlen ((hs)->timestamp))
55
56/* A structure used to pass the current state of the history stuff around. */
57typedef struct _hist_state {
58 HIST_ENTRY **entries; /* Pointer to the entries themselves. */
59 int offset; /* The location pointer within this array. */
60 int length; /* Number of elements within this array. */
61 int size; /* Number of slots allocated to this array. */
62 int flags;
63} HISTORY_STATE;
64
65/* Flag values for the `flags' member of HISTORY_STATE. */
66#define HS_STIFLED 0x01
67
68/* Initialization and state management. */
69
70/* Begin a session in which the history functions might be used. This
71 just initializes the interactive variables. */
72extern void using_history PARAMS((void));
73
74/* Return the current HISTORY_STATE of the history. */
75extern HISTORY_STATE *history_get_history_state PARAMS((void));
76
77/* Set the state of the current history array to STATE. */
78extern void history_set_history_state PARAMS((HISTORY_STATE *));
79
80/* Manage the history list. */
81
82/* Place STRING at the end of the history list.
83 The associated data field (if any) is set to NULL. */
84extern void add_history PARAMS((const char *));
85
86/* Change the timestamp associated with the most recent history entry to
87 STRING. */
88extern void add_history_time PARAMS((const char *));
89
90/* A reasonably useless function, only here for completeness. WHICH
91 is the magic number that tells us which element to delete. The
92 elements are numbered from 0. */
93extern HIST_ENTRY *remove_history PARAMS((int));
94
95/* Allocate a history entry consisting of STRING and TIMESTAMP and return
96 a pointer to it. */
97extern HIST_ENTRY *alloc_history_entry PARAMS((char *, char *));
98
99/* Copy the history entry H, but not the (opaque) data pointer */
100extern HIST_ENTRY *copy_history_entry PARAMS((HIST_ENTRY *));
101
102/* Free the history entry H and return any application-specific data
103 associated with it. */
104extern histdata_t free_history_entry PARAMS((HIST_ENTRY *));
105
106/* Make the history entry at WHICH have LINE and DATA. This returns
107 the old entry so you can dispose of the data. In the case of an
108 invalid WHICH, a NULL pointer is returned. */
109extern HIST_ENTRY *replace_history_entry PARAMS((int, const char *, histdata_t));
110
111/* Clear the history list and start over. */
112extern void clear_history PARAMS((void));
113
114/* Stifle the history list, remembering only MAX number of entries. */
115extern void stifle_history PARAMS((int));
116
117/* Stop stifling the history. This returns the previous amount the
118 history was stifled by. The value is positive if the history was
119 stifled, negative if it wasn't. */
120extern int unstifle_history PARAMS((void));
121
122/* Return 1 if the history is stifled, 0 if it is not. */
123extern int history_is_stifled PARAMS((void));
124
125/* Information about the history list. */
126
127/* Return a NULL terminated array of HIST_ENTRY which is the current input
128 history. Element 0 of this list is the beginning of time. If there
129 is no history, return NULL. */
130extern HIST_ENTRY **history_list PARAMS((void));
131
132/* Returns the number which says what history element we are now
133 looking at. */
134extern int where_history PARAMS((void));
135
136/* Return the history entry at the current position, as determined by
137 history_offset. If there is no entry there, return a NULL pointer. */
138extern HIST_ENTRY *current_history PARAMS((void));
139
140/* Return the history entry which is logically at OFFSET in the history
141 array. OFFSET is relative to history_base. */
142extern HIST_ENTRY *history_get PARAMS((int));
143
144/* Return the timestamp associated with the HIST_ENTRY * passed as an
145 argument */
146extern time_t history_get_time PARAMS((HIST_ENTRY *));
147
148/* Return the number of bytes that the primary history entries are using.
149 This just adds up the lengths of the_history->lines. */
150extern int history_total_bytes PARAMS((void));
151
152/* Moving around the history list. */
153
154/* Set the position in the history list to POS. */
155extern int history_set_pos PARAMS((int));
156
157/* Back up history_offset to the previous history entry, and return
158 a pointer to that entry. If there is no previous entry, return
159 a NULL pointer. */
160extern HIST_ENTRY *previous_history PARAMS((void));
161
162/* Move history_offset forward to the next item in the input_history,
163 and return the a pointer to that entry. If there is no next entry,
164 return a NULL pointer. */
165extern HIST_ENTRY *next_history PARAMS((void));
166
167/* Searching the history list. */
168
169/* Search the history for STRING, starting at history_offset.
170 If DIRECTION < 0, then the search is through previous entries,
171 else through subsequent. If the string is found, then
172 current_history () is the history entry, and the value of this function
173 is the offset in the line of that history entry that the string was
174 found in. Otherwise, nothing is changed, and a -1 is returned. */
175extern int history_search PARAMS((const char *, int));
176
177/* Search the history for STRING, starting at history_offset.
178 The search is anchored: matching lines must begin with string.
179 DIRECTION is as in history_search(). */
180extern int history_search_prefix PARAMS((const char *, int));
181
182/* Search for STRING in the history list, starting at POS, an
183 absolute index into the list. DIR, if negative, says to search
184 backwards from POS, else forwards.
185 Returns the absolute index of the history element where STRING
186 was found, or -1 otherwise. */
187extern int history_search_pos PARAMS((const char *, int, int));
188
189/* Managing the history file. */
190
191/* Add the contents of FILENAME to the history list, a line at a time.
192 If FILENAME is NULL, then read from ~/.history. Returns 0 if
193 successful, or errno if not. */
194extern int read_history PARAMS((const char *));
195
196/* Read a range of lines from FILENAME, adding them to the history list.
197 Start reading at the FROM'th line and end at the TO'th. If FROM
198 is zero, start at the beginning. If TO is less than FROM, read
199 until the end of the file. If FILENAME is NULL, then read from
200 ~/.history. Returns 0 if successful, or errno if not. */
201extern int read_history_range PARAMS((const char *, int, int));
202
203/* Write the current history to FILENAME. If FILENAME is NULL,
204 then write the history list to ~/.history. Values returned
205 are as in read_history (). */
206extern int write_history PARAMS((const char *));
207
208/* Append NELEMENT entries to FILENAME. The entries appended are from
209 the end of the list minus NELEMENTs up to the end of the list. */
210extern int append_history PARAMS((int, const char *));
211
212/* Truncate the history file, leaving only the last NLINES lines. */
213extern int history_truncate_file PARAMS((const char *, int));
214
215/* History expansion. */
216
217/* Expand the string STRING, placing the result into OUTPUT, a pointer
218 to a string. Returns:
219
220 0) If no expansions took place (or, if the only change in
221 the text was the de-slashifying of the history expansion
222 character)
223 1) If expansions did take place
224 -1) If there was an error in expansion.
225 2) If the returned line should just be printed.
226
227 If an error occurred in expansion, then OUTPUT contains a descriptive
228 error message. */
229extern int history_expand PARAMS((char *, char **));
230
231/* Extract a string segment consisting of the FIRST through LAST
232 arguments present in STRING. Arguments are broken up as in
233 the shell. */
234extern char *history_arg_extract PARAMS((int, int, const char *));
235
236/* Return the text of the history event beginning at the current
237 offset into STRING. Pass STRING with *INDEX equal to the
238 history_expansion_char that begins this specification.
239 DELIMITING_QUOTE is a character that is allowed to end the string
240 specification for what to search for in addition to the normal
241 characters `:', ` ', `\t', `\n', and sometimes `?'. */
242extern char *get_history_event PARAMS((const char *, int *, int));
243
244/* Return an array of tokens, much as the shell might. The tokens are
245 parsed out of STRING. */
246extern char **history_tokenize PARAMS((const char *));
247
248/* Exported history variables. */
249extern int history_base;
250extern int history_length;
251extern int history_max_entries;
252extern int history_offset;
253
254extern int history_lines_read_from_file;
255extern int history_lines_written_to_file;
256
257extern char history_expansion_char;
258extern char history_subst_char;
259extern char *history_word_delimiters;
260extern char history_comment_char;
261extern char *history_no_expand_chars;
262extern char *history_search_delimiter_chars;
263extern int history_quotes_inhibit_expansion;
264
265extern int history_write_timestamps;
266
267/* These two are undocumented; the second is reserved for future use */
268extern int history_multiline_entries;
269extern int history_file_version;
270
271/* Backwards compatibility */
272extern int max_input_history;
273
274/* If set, this function is called to decide whether or not a particular
275 history expansion should be treated as a special case for the calling
276 application and not expanded. */
277extern rl_linebuf_func_t *history_inhibit_expansion_function;
278
279#ifdef __cplusplus
280}
281#endif
282
283#endif /* !_HISTORY_H_ */
284