Crate weave

Weave deltas, inspired by SCCS.

The SCCS revision control system is one of the oldest source code management systems (1973). Although many of its concepts are quite dated in these days of git, the underlying “weave” delta format it used turns out to be a good way of representing multiple versions of data that differ only in parts.

This package implements a weave-based storage of “plain text”, where plain text consists of lines of UTF-8 printable characters separated by a newline.

The format is similar to SCCS, but with no constraints to keep what are relatively poor design decisions from SCCS, such as putting a checksum at the top of the file, and using limited-sized field for values such as the number of lines in a file, or the use of 2-digit years. However, the main body of the weaved file, that which describes inserts and deletes is the same, and allows us to test this version by comparing with the storage of sccs.

Weave files are written using NewWeave, which works like a regular file writer. The file itself has a small amount of surrounding metadata, but is otherwise mostly just the contents of the initial file.

Adding a delta to a weave file is done with the DeltaWriter. This is also written to, as a regular file, and then DeltaWriter::close method will extract a base revision and use the diff command to write a new version of the weave. The close method will make several temporary files in the process.

The weave data is stored using a NamingConvention, a trait that manages a related collection of files, and temp files. SimpleNaming is a basic representation of this that has a base name, a backup file, and some temporary files. The data in the file can be compressed.

Structs

DeltaInfo

Information about a single delta.

DeltaWriter

A DeltaWriter is used to write a new delta. Data should be written to the writer, and then the close method called to update the weave file with the new delta.

Header

The header placed at the beginning of the each weave file. The deltas correspond with the deltas checked in. Note that the value passed to crate::PullParser::new should be the number field of DeltaInfo and not the index in the deltas vec.

NewWeave

A builder for a new weave file. The data should be written as a writer. Closing the weaver will finish up the write and move the new file into place. If the weaver is just dropped, the file will not be moved into place.

Parser

A Parser is used to process a weave file. This is a wrapper around the pull parser that invokes a push parser.

PullParser

The pull parser is the intended way of reading from weave files. After opening a particular delta with PullParser::new, the parser can be used as an iterator, to return Entry values. In particular, the entries for Entry::Plain where keep is true will be the lines of the weave that comprise the expected delta.

SimpleNaming

The SimpleNaming is a NamingConvention that has a basename, with the main file having a specified extension, the backup file having a “.bak” extension, and the temp files using a numbered extension starting with “.0”. If the names are intended to be compressed, a “.gz” suffix can also be added.

WriterInfo

Something we can write into, that remembers its name. The writer is boxed because the writer may be compressed.

Enums

Entry

The PullParser returns the entries as nodes. These are equivalent to the values in Sink.

Error

Traits

NamingConvention

A naming convention provides utilities needed to find the involved files, and construct temporary files as part of writing the new weave. The underlying object should keep the path and base name.

Sink

A Sink is a place that a parsed weave can be sent to. The insert/delete/end commands match those in the weave file, and plain are the lines of data. With each plain is a flag indicating if that line should be included in the output (all lines are called, so that updates can use this same code). All methods return a result, with the Err value stopping the parse. Note that the default implementations just return success, and ignore the result.

Functions

get_last_delta

Retrieve the last delta in the weave file. Will panic if the weave file is malformed and contains no revisions.

read_header

Read the header from a weave file.

Type Aliases

Result