You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
thegoofist dd377994bb
Update README.org
2 years ago
LICENSE initial commit 3 years ago
README.org Update README.org 2 years ago
package.lisp refactored interface and added character-input-replay-stream class 3 years ago
replay-streams.asd Updated version to 0.1.0, updated README 3 years ago
replay-streams.lisp log cleanup turned on 3 years ago

README.org

replay-streams

Replay streams let the programmer rewind to points in a stream that have already been read.

At the moment, replay streams only support character streams, but should someday support more exotic binary stream types.

NOTE: This is alpha quality software

The Replay Stream Types

The following clases are exported by the replay-streams package:

  • static-text-replay-stream : This is the most efficient of the replay-streams classes, and is analogous to make-string-input-stream in that it transforms a string into a stream.

  • character-input-replay-stream : This is used to transform a characer input stream into a replayable stream. Suitable for reading files or character network streams.

The Replay Stream Interface

Each class in the replay-streams package supports the following methods:

  • (checkpoint stream) : returns a "checkpoint" which you can use to rewind to a specific point in your input stream.

  • (rewind-to stream checkpoint) : is used to actually rewind a stream to a checkpoint.

  • (free-checkpoint stream checkpoint) : tells the stream that it no longer needs to support rewinds to the supplied checkpoint.

Some Notes

For static-text-replay-stream instances, free-checkpoint doesn't actually do anything, but a dummy implementation is included to permit general purpose code.

Support for rewinding streams is enabled by logging reads to the stream. As you might imagine, logging every read can begin to take its toll on the memory heap. Hence, freeing a checkpoint can signal to the stream that it may be acceptable to discard the log. Internally, the log is freed whenever there are no checkpoints remaining and when any playback on the log has been exhausted - i.e. whenever the system is certain that the log is no longer needed.

NOTE: As it stands right now, rewinding a stream to a checkpoint will also free that checkpoint and all checkpoints AFTER the rewind point.

Why?

This small library was created in order to support the parzival streaming parser-combinator DSL, which needs replayable streams for its implementation of the <<plus combinator.

[0/4] To Do

  1. Add a test suite.

  2. For character-input-replay-stream, support user control over initial log size.

  3. For character-input-replay-stream, support optional maximum log. size, along with an error condition if the log size is exceeded.

  4. Support binary streams.