# jhistory.tcl

## Introduction

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 2001.02.10.

## Usage

### 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.

## Credits and Copyright

### Author

Jay Sekora
`js@aq.org`
`http://www.aq.org/~js/`

### Copyright

The library is copyright © 1992-2001by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

## History Lists and History Files

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, `::jstools::history_up` and `::jstools::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 `::jstools::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.

## Overview

### Procedures

`::jstools::history_begin` - start using a particular history
`::jstools::history_up` - go back (up) in the history list
`::jstools::history_down` - go forward (down) in the history list
`::jstools::history_append` - add to the end of a particular history

### See Also

jprompts.tcl for an example of the use of this library

## ::jstools::history_begin

### Usage

`::jstools::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.

## ::jstools::history_up

### Usage

`::jstools::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 `::jstools::history_begin`), then the position is not changed and the oldest value is returned.

## ::jstools::history_down

### Usage

`::jstools::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.

## ::jstools::history_append

### Usage

`::jstools::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 `::jstools::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.`
`