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