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+), function-cache,
trivial-gray-streams, bordeaux-threads, and fiveam for testing. In addition, on
POSIX systems the mmap and osicat libraries are used for the parallel decoder.


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 &KEY (CACHE-CAPACITY 2048))
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, caching details, 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.