1 /* history.h -- the names of functions that you can call in history. */ 2 3 /* Copyright (C) 1989-2009 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 26 extern "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__ 41 typedef void *histdata_t; 42 #else 43 typedef char *histdata_t; 44 #endif 45 46 /* The structure used to store a history entry. */ 47 typedef 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. */ 57 typedef 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. */ 72 extern void using_history PARAMS((void)); 73 74 /* Return the current HISTORY_STATE of the history. */ 75 extern HISTORY_STATE *history_get_history_state PARAMS((void)); 76 77 /* Set the state of the current history array to STATE. */ 78 extern 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. */ 84 extern void add_history PARAMS((const char *)); 85 86 /* Change the timestamp associated with the most recent history entry to 87 STRING. */ 88 extern 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. */ 93 extern HIST_ENTRY *remove_history PARAMS((int)); 94 95 /* Free the history entry H and return any application-specific data 96 associated with it. */ 97 extern histdata_t free_history_entry PARAMS((HIST_ENTRY *)); 98 99 /* Make the history entry at WHICH have LINE and DATA. This returns 100 the old entry so you can dispose of the data. In the case of an 101 invalid WHICH, a NULL pointer is returned. */ 102 extern HIST_ENTRY *replace_history_entry PARAMS((int, const char *, histdata_t)); 103 104 /* Clear the history list and start over. */ 105 extern void clear_history PARAMS((void)); 106 107 /* Stifle the history list, remembering only MAX number of entries. */ 108 extern void stifle_history PARAMS((int)); 109 110 /* Stop stifling the history. This returns the previous amount the 111 history was stifled by. The value is positive if the history was 112 stifled, negative if it wasn't. */ 113 extern int unstifle_history PARAMS((void)); 114 115 /* Return 1 if the history is stifled, 0 if it is not. */ 116 extern int history_is_stifled PARAMS((void)); 117 118 /* Information about the history list. */ 119 120 /* Return a NULL terminated array of HIST_ENTRY which is the current input 121 history. Element 0 of this list is the beginning of time. If there 122 is no history, return NULL. */ 123 extern HIST_ENTRY **history_list PARAMS((void)); 124 125 /* Returns the number which says what history element we are now 126 looking at. */ 127 extern int where_history PARAMS((void)); 128 129 /* Return the history entry at the current position, as determined by 130 history_offset. If there is no entry there, return a NULL pointer. */ 131 extern HIST_ENTRY *current_history PARAMS((void)); 132 133 /* Return the history entry which is logically at OFFSET in the history 134 array. OFFSET is relative to history_base. */ 135 extern HIST_ENTRY *history_get PARAMS((int)); 136 137 /* Return the timestamp associated with the HIST_ENTRY * passed as an 138 argument */ 139 extern time_t history_get_time PARAMS((HIST_ENTRY *)); 140 141 /* Return the number of bytes that the primary history entries are using. 142 This just adds up the lengths of the_history->lines. */ 143 extern int history_total_bytes PARAMS((void)); 144 145 /* Moving around the history list. */ 146 147 /* Set the position in the history list to POS. */ 148 extern int history_set_pos PARAMS((int)); 149 150 /* Back up history_offset to the previous history entry, and return 151 a pointer to that entry. If there is no previous entry, return 152 a NULL pointer. */ 153 extern HIST_ENTRY *previous_history PARAMS((void)); 154 155 /* Move history_offset forward to the next item in the input_history, 156 and return the a pointer to that entry. If there is no next entry, 157 return a NULL pointer. */ 158 extern HIST_ENTRY *next_history PARAMS((void)); 159 160 /* Searching the history list. */ 161 162 /* Search the history for STRING, starting at history_offset. 163 If DIRECTION < 0, then the search is through previous entries, 164 else through subsequent. If the string is found, then 165 current_history () is the history entry, and the value of this function 166 is the offset in the line of that history entry that the string was 167 found in. Otherwise, nothing is changed, and a -1 is returned. */ 168 extern int history_search PARAMS((const char *, int)); 169 170 /* Search the history for STRING, starting at history_offset. 171 The search is anchored: matching lines must begin with string. 172 DIRECTION is as in history_search(). */ 173 extern int history_search_prefix PARAMS((const char *, int)); 174 175 /* Search for STRING in the history list, starting at POS, an 176 absolute index into the list. DIR, if negative, says to search 177 backwards from POS, else forwards. 178 Returns the absolute index of the history element where STRING 179 was found, or -1 otherwise. */ 180 extern int history_search_pos PARAMS((const char *, int, int)); 181 182 /* Managing the history file. */ 183 184 /* Add the contents of FILENAME to the history list, a line at a time. 185 If FILENAME is NULL, then read from ~/.history. Returns 0 if 186 successful, or errno if not. */ 187 extern int read_history PARAMS((const char *)); 188 189 /* Read a range of lines from FILENAME, adding them to the history list. 190 Start reading at the FROM'th line and end at the TO'th. If FROM 191 is zero, start at the beginning. If TO is less than FROM, read 192 until the end of the file. If FILENAME is NULL, then read from 193 ~/.history. Returns 0 if successful, or errno if not. */ 194 extern int read_history_range PARAMS((const char *, int, int)); 195 196 /* Write the current history to FILENAME. If FILENAME is NULL, 197 then write the history list to ~/.history. Values returned 198 are as in read_history (). */ 199 extern int write_history PARAMS((const char *)); 200 201 /* Append NELEMENT entries to FILENAME. The entries appended are from 202 the end of the list minus NELEMENTs up to the end of the list. */ 203 extern int append_history PARAMS((int, const char *)); 204 205 /* Truncate the history file, leaving only the last NLINES lines. */ 206 extern int history_truncate_file PARAMS((const char *, int)); 207 208 /* History expansion. */ 209 210 /* Expand the string STRING, placing the result into OUTPUT, a pointer 211 to a string. Returns: 212 213 0) If no expansions took place (or, if the only change in 214 the text was the de-slashifying of the history expansion 215 character) 216 1) If expansions did take place 217 -1) If there was an error in expansion. 218 2) If the returned line should just be printed. 219 220 If an error occurred in expansion, then OUTPUT contains a descriptive 221 error message. */ 222 extern int history_expand PARAMS((char *, char **)); 223 224 /* Extract a string segment consisting of the FIRST through LAST 225 arguments present in STRING. Arguments are broken up as in 226 the shell. */ 227 extern char *history_arg_extract PARAMS((int, int, const char *)); 228 229 /* Return the text of the history event beginning at the current 230 offset into STRING. Pass STRING with *INDEX equal to the 231 history_expansion_char that begins this specification. 232 DELIMITING_QUOTE is a character that is allowed to end the string 233 specification for what to search for in addition to the normal 234 characters `:', ` ', `\t', `\n', and sometimes `?'. */ 235 extern char *get_history_event PARAMS((const char *, int *, int)); 236 237 /* Return an array of tokens, much as the shell might. The tokens are 238 parsed out of STRING. */ 239 extern char **history_tokenize PARAMS((const char *)); 240 241 /* Exported history variables. */ 242 extern int history_base; 243 extern int history_length; 244 extern int history_max_entries; 245 extern char history_expansion_char; 246 extern char history_subst_char; 247 extern char *history_word_delimiters; 248 extern char history_comment_char; 249 extern char *history_no_expand_chars; 250 extern char *history_search_delimiter_chars; 251 extern int history_quotes_inhibit_expansion; 252 253 extern int history_write_timestamps; 254 255 /* Backwards compatibility */ 256 extern int max_input_history; 257 258 /* If set, this function is called to decide whether or not a particular 259 history expansion should be treated as a special case for the calling 260 application and not expanded. */ 261 extern rl_linebuf_func_t *history_inhibit_expansion_function; 262 263 #ifdef __cplusplus 264 } 265 #endif 266 267 #endif /* !_HISTORY_H_ */ 268