`Data.Binary.Serialise.CBOR.Term` is confusing

[well-typed]

`Data.Binary.Serialise.CBOR.Term` is confusing

[thoughtpolice]

It's true, this is confusing. They seem similar - but they aren't similar at all. Carefully note the exported types we get:

-- Term
encodeTerm :: Term -> Encoding
decodeTerm :: Decoder Term

-- FlatTerm
toFlatTerm :: Encoding -> FlatTerm
fromFlatTerm :: Decoder a -> FlatTerm -> Either String a

Term is a Haskell ADT representation of any arbitrary CBOR value. This means there is a direct mapping between any arbitrary CBOR value and Term. You can use decodeTerm to decode any arbitrary CBOR value into a Haskell ADT, whether or not that thing was originally serialized in Haskell or Java or any number of languages. You simply decode any CBOR data using the decodeTerm :: Decoder Term and get back a general AST for traversing/analysis.

FlatTerm, however, is simply an alternative representation for encodings. Note that this package uses a "deep embedding". Whenever you create an Encoder out of the primitives in .Encoding module, you are really just building up a simplistic AST that lists the actions to perform. Once we have this Encoding, we can serialize it however we want. (This is the fundamental difference between this library and binary).

So if we have an AST, we can really have multiple 'backends'. We can take the Encoding and traverse the AST, and turn it into CBOR (this is what the .Write module does). Decoder is a similar type, which tells us what actions to perform when decoding (and what continuations to call, with the values we got back). So the .Read module takes a Decoder and some CBOR value and gives us back what the Decoder specified.

But .Read and .Write simply expose CBOR-based backends. FlatTerm is a completely different 'backend'. Instead we simply take some Encoding, and serialize it into a different, simpler Haskell data type. This type is FlatTerm, and it is a "blob" that is a degenerate list. Then, when we have a Decoder, and the given FlatTerm (which is really, again, a list), we just traverse the list one by one, feeding the decoder with the values it expects. Or we error. Look through the source for FlatTerm and you'll see what I mean.

With this decoupling of the backend from the actual encoders/decoders in mind, this module separation makes much more sense. FlatTerm is an alternative backend, while Term is almost like an alternative frontend, that's only built on top of our existing .Encoding and .Decoding modules.

Ultimately these are meant to serve different purposes. The FlatTerm module is purely a module for people who write instances, to create properties they can check - they want to make sure their encoders and decoders work properly (there's no real reason to do a full round-trip to CBOR just for that, since you're only specifying the logic of your encoders and decoders.) It gives a simpler backend that will make debugging bad instances easier.

The Term module is so we can read arbitrary CBOR and write arbitrary CBOR as needed in an easy way. You'd use it more for doing things like analysis, debugging or interoperability (like if you needed to encode some value slightly differently than the instance specifies, for interop - this would be an easy way to do it.)

[thoughtpolice]

(FWIW: someone should basically copy/paste something like this into the .Term module... ;) I've added appropriate labels for this so it's made clear.)

[michalt]

Oh I see, thanks for a nice explanation! :-)