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.
A good example can be found in
ocaml-git. We use
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.
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,