jhistory.tcl
The
jhistory.tcl library is distributed as part of the
jstools package. It provides procedures to manage persistent history
lists similar to the command history provided by the
tcsh(1) and
bash(1) shells.
This document describes
jhistory.tcl version 1998.09.30.
Accessing the Library
In order to use the
jhistory.tcl library, it must be in your Tcl
auto_path, described in
tclvars(n). Information about how to arrange that, and other conventions
common to
the
jstools libraries, is in
the
Usage section of
The jstools Libraries.
Author
Jay Sekora
js@aq.org
http://www.aq.org/~js/
Copyright
The library is copyright © 1992-1998 by Jay Sekora, but may be
freely redistributed under the conditions at the top of the file.
The history lists managed by this library are identified by short
names. These names should be alphanumeric and short, because
they are used as file names when history information is written
out to disk. They should also be unique for a particular function.
For instance, if your application is a bibliographic database
and you want to provide your users with a history of the most
recent authors they've selected, `bdb_auth' might be a good choice for a history name, `history' would not. (Because history lists are stored persistently
on disk, you need to try to prevent your history list names conflicting
with those of other applications.)
In addition to the name (and directory) and the actual contents,
there are two other pieces of information associated with a history
list: its size and current position. The size is just the maximum
number of items it will hold; after that limit is reached, adding
new items will cause old ones to be forgotten. The current
position is simply a pointer into the list, where 0 represents
the most recently added item and increasing numbers represent
successively older items. The position can also be -1, which
represents a position past the bottom of the list (i.e., it can
roughly be thought of as representing the thing about to be added
to the history list).
There are two procedures,
j:history:up and
j:history:down, to move up and down in the history list and return the previous
or next value. (The -1th value is returned as the empty string.)
There's also a procedure
j:history:append to add an item to the end of the history list. This resets
the current position and causes the history list to be saved to
disk. A new value is only added if it is different from the
most recently added value before it.
Procedures
j:history:begin - start using a particular history
j:history:up - go back (up) in the history list
j:history:down - go forward (down) in the history list
j:history:append - add to the end of a particular history
See Also
jprompts.tcl for an example of the use of this library
Usage
j:history:begin
[options]
history
Options
-directory
dir
(default
~/.tk/history)
-size
size
(default 30)
-position
pos
(default -1)
Argument
history is the name of the history list (and the file it's stored in)
Description
This procedure prepares to use a new history list. (For any
given history list
history, this procedure must be called before any of the other procedures
in this library can be used.) If a stored history file for
the given history list exists, it is read in; otherwise it is
created (if possible) with an initially empty list.
The current position in the history list is initialised to
pos. This defaults to -1, representing the position just after
(below) the most recently added item in the history list. (You
probably won't normally want to change the default.)
The
size parameter is the intended maximum length of the given history
list, i.e., the number of items it should hold. It is used
by the other procedures in the library.
The history list will be stored in a file named
history in the directory
dir.
Usage
j:history:up
history
Argument
history is the name of the history list (and the file it's stored in)
Description
This procedure returns the value in
history imediately previous to (older than) the value at the current
position, and resets the position to point to that older value.
I.e., it moves one step back in history and returns the item
found there.
If the history's current position is already at the oldest value
it contains (i.e. if it matches the size specified by
j:history:begin), then the position is not changed and the oldest value is returned.
Usage
j:history:down
history
Argument
history is the name of the history list (and the file it's stored in)
Description
This procedure returns the value in
history imediately following (newer than) the value at the current
position, and resets the position to point to that newer value.
I.e., it moves one step forward in history and returns the
item found there.
If the history's current position is already at the the newest
value it contains (i.e. 0), or if it is -1, then the position
is set to -1 and the empty string is returned.
Usage
j:history:append
history
value
Arguments
history is the name of the history list (and the file it's stored in)
value is the value to append to the history list
Description
This procedure adds
value onto the end of the history list named
history, and writes the history list out to disk. If the history list
would be larger than the maximum size specified earlier by
j:history:begin, then the oldest value is discarded. The current position
is reset to -1.
Future Directions
I'd like to create a similar parallel mechanism in which values
are only added to the `history' list at the user's explicit request.
For instance, in a fileopen dialogue box, I may use lots of
file names only once, but I may also have a particular file name
that I know I'm going to be using again; I should be able to
add that name explicitly to this alternative `history' list.