Encore is a little library to provide an interface to generate an
Angstrom's decoder and a
internal encoder from a shared description. The goal is specifically for
ocaml-git to ensure isomorphism when
we decode and encode a Git object - and keep the same hash/identifier.

Examples

A good example can be found in
ocaml-git. We use encore to
describe Git objects, by this way, ensure to re-encode what we decoded without
noises - and keep the same hash.

Some notes about internal encoder

Internal encoder is a little encoder which takes care about the memory
consumption when you serialize an OCaml value with a description. We use a
bounded bigarray and when it's full, we explicitly ask to the user to flush it.

Internal encoder was built on a CPS mind like Angstrom and uses only pure
functional data structures. This is a big difference from
Faraday. So, obviously, this
encoder is slower than Faraday (3 times), however, we can not use Faraday in
this context, precisely about alteration.

In fact, when the encoder fails, we raise an exception to short-cut to the other
branch. With a mutable structure, it's little bit hard to rollback to the old
state of encoder and retry the other branch. With this encoder, we don't need to
trick to rollback because, at any step we make a new pure state.

Inspirations

This project is inspired by the finale
project which is focused on a pretty-printer at the end. Encore is close to
provide a low-level encoder like
Faraday than a generator of a
pretty-printer.

Improvements

This library was made specifically for ocaml-git. The API could be not
consistent for an usual user (and not easy to use). So feedbacks are really
welcomed to improve API. Finally, the big issue seems to be performance on
internal encoder - it could be interesting to improve it but it's little-bit
difficult to understand assumptions on encoding process - like immutability. So,
feel free!