# $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:=====
^Name^Action^
| 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:=====
^Name^Action^
|history|How many entries to hold in the history buffer.|
|history_circleq|When 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_dups|When 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_persistent|When ON, all history entries will be written to a file during shutdown.  When OFF, history entries are not saved.|
|history_save_file|This is the name of the file that history entries should be saved to on shutdown.|
|history_save_position|When 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_timestamp|When 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.

^Name^Action^
|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.|
|reset|Clear 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.