Return to history.h CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline

readline 6.3

    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_ */