This is a Common Lisp implementation of the Encoding for Robust Immutable
Storage specification (https://purl.org/eris). It implements the version 1.0 of
the specification.

The code is licensed under the LGPLv3 or any later version, unless specified
otherwise in a file.

Depends on Alexandria, Serapeum, Ironclad (version 0.58+), trivial-gray-streams,
lparallel, and fiveam for testing.


The public API is exported by the ERIS package.

There are the following functions for converting to and from ERIS
representations to eris-cl objects:

read-capability-to-urn
urn-to-read-capability
octets-to-read-capability
read-capability-to-octets
reference-to-block-urn
block-urn-to-reference


The eris-encode (INPUT BLOCK-SIZE OUTPUT-FUNCTION &KEY SECRET HASH-OUTPUT)
function can be used to encode a vector, stream or pathname into an ERIS
read-capability. 

The eris-decode (READ-CAPABILITY FETCH-FUNCTION)
function can be used to decode an ERIS read-capability. It returns a stream of
the class ERIS-DECODE-STREAM: this class implements the Gray streams protocol.

See the docstrings of the specific functions for more details. However, you
should only use these to write custom backends; otherwise, see below.

NOTES ON ERIS-DECODE-STREAM:

The implementation of all the methods behaves similarly to regular ones, except
for FILE-POSITION with two arguments. On SBCL and a few other CL
implementations, the implementation of the ordinary FILE-POSITION never fails.
However, per the spec, it could fail in some cases. As such, the (SETF
STREAM-FILE-POSITION) method on ERIS-DECODE-STREAM does fail if the index is
larger or equal to EOF.



A high-level API is provided for convenience in backend.lisp. The concept is
that a backend object is created, which holds information like output-function,
fetch-function, block-size, etc. and the {en/de}coding functions simply take the
backend as an argument.

This interface consists of two generic functions: store-data, for encoding data,
and fetch-data, for retrieving the contents from a read-capability object.

As an example, a file-based backend called file-backend is provided. It can be
used simply by making an instance of the 'file-backend class with a :directory
argument, which will point to the directory in which ERIS data is to be stored.

There is also hash-backend, which implements a simple hash-table backend. It is
primarily meant for testing, not actual usage.

The API contains the following symbols:

fetch-data (READ-CAPABILITY BACKEND &key)
store-data (INPUT BACKEND &key)

Classes:

encoding-backend
decoding-backend

An instance of file-backend can be instanced using (make-instance 'file-backend
:directory "my/dir/with/eris/chunks/").

There are also parallel equivalents, p/fetch-data and p/store-data. These can be
used on backends marked with p/encoding-backend; for example the file-backend.
In practice, any backend that allows concurrent writes should has
p/encoding-backend as a superclass.

For further information, see the docstrings.