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