Table of Contents

# $EPIC: history.txt,v 1.4 2007/03/16 22:57:17 jnelson Exp $

Synopsis:

/load history
/bind <sequence> BACKWARD_HISTORY
/bind <sequence> ERASE_HISTORY
/bind <sequence> FORWARD_HISTORY
/bind <sequence> SHOVE_TO_HISTORY
/set history <number>
/set history_circleq [ON|OFF|TOGGLE]
/set history_persistent [ON|OFF|TOGGLE]
/set history_remove_dupes [ON|OFF|TOGGLE]
/set history_save_file <filename>
/set history_save_position [ON|OFF|TOGGLE]
/set history_timestamp [ON|OFF|TOGGLE]
/history <index-number>
/!<index-number|pattern>
$historyctl(add <text>)
$historyctl(delete <indexnum>)
$historyctl(get <indexnum>)
$historyctl(index <indexnum>)
$historyctl(read <filename>)
$historyctl(reset)
$historyctl(save <filename>)
$historyctl(set <number>)

Description:

This script implements input line history retention and recall. It is far more featureful than the built in history recall ever was.

It is helpful to note that there are two modes: “browsing” mode, and “non-browsing” mode.

Any time you use SEND_LINE (ie, the <enter> key), the contents of the input line are added to the history. You can then later use keybindings to go back and recall these entries. SEND_LINE always cancels browsing mode.

Keybindings:

NameAction
BACKWARD_HISTORY Go back (older) one entry in the history buffer.
ERASE_HISTORY Delete the input line and exit browsing mode.
FORWARD_HISTORY Go forward (newer) one entry in the history buffer.
SHOVE_TO_HISTORY Add the input buffer to history, but don't run it.

For backwards compatability, BACKWARD_HISTORY and FORWARD_HISTORY will save the current contents of the input line in the history (as SHOVE_TO_HISTORY does) if you are in non-browsing mode. If you are in browsing mode, it does not save it again, even if you've made changes.

Sets:

NameAction
historyHow many entries to hold in the history buffer.
history_circleqWhen ON, BACKWARD_HISTORY and FORWARD_HISTORY “wrap around” the ends of the history buffer. When OFF, they stop when they reach the ends.
history_remove_dupsWhen ON, if a new entry is exactly the same as any old entry, all the old entries are deleted. When OFF, duplicate entries are fine.
history_persistentWhen ON, all history entries will be written to a file during shutdown. When OFF, history entries are not saved.
history_save_fileThis is the name of the file that history entries should be saved to on shutdown.
history_save_positionWhen ON, doing a history search (with /!) puts you in browsing mode. When OFF, doing a history search merely retrieves the entry but does not put you in browsing mode.
history_timestampWhen ON, the history command will show the timestamp of each entry in the history buffer. When OFF, no timestamps will be shown.

Commands:

/HISTORY Show all entries in the history buffer.
/HISTORY <number> Show the last <number> entries in the history buffer.
/!<string> Find the next most recent history item that contains <string> and put it in the input buffer.
/!<number> Put the <number>th most recent entry in the input line.

Historyctl function:

You can perform low level operations on the history buffer by using the historyctl function.

NameAction
add <text>Add <text> as an entry to the history buffer.
delete <indexnum>Delete the <indexnum>th entry in the history buffer.
get <indexnum>Return the <indexnum>th entry in the history buffer.
index <indexnum>Returns 1 if <indexnum> is a valid entry index number, and 0 if it is not.
read <filename>Read the contents of <filename> and put them into the history buffer.
resetClear the history buffer.
save <filename>Save the contents of the history buffer to <filename> so it can be later recovered with read.
set <number> <string>Change the <number>th history entry to <string>.

History:

The history script first appeared in epic5-0.0.5.