Codec.CBOR

A library for working with CBOR.

Documentation

The cborg library is a low-level parsing and encoding library for the Compact Binary Object Representation (CBOR) defined in RFC 7049. CBOR is a language-agnostic, extensible, and size- and computation-efficient encoding for arbitrary data, with a well-defined bijection to the ubiquitous JSON format and a precisely specified canonical form.

Note, however, that cborg does not itself aim to be a serialisation library; it merely serves as the substrate on which such a library might be built. See the serialise library if you are looking for convenient serialisation of Haskell values.

Instead, cborg targets cases where precise control over the CBOR object structure is needed such as when working with externally-specified CBOR formats.

The library is split into a number of modules,

• Decoding

  • Codec.CBOR.Decoding defines the machinery for decoding primitive CBOR terms into Haskell values. In particular, the Decoder type and associated decoders,

   data Decoder s a
  
   -- for, e.g., safe in-place mutation during decoding
   liftST      :: ST s a -> Decoder s a
  
   -- primitive decoders
   decodeWord  :: Decoder s Word
   decodeBytes :: Decoder s ByteString
   -- et cetera
   

  • Codec.CBOR.Read defines the low-level wire-format decoder, e.g.

   deserialiseFromBytes :: Decoder a
                        -> ByteString
                        -> Either String (ByteString, a)
   

• Encoding

  • Codec.CBOR.Encoding defines the Encoding type, which is in essence difference-list of CBOR tokens and is used to construct CBOR encodings.

     data Encoding
     instance Monoid Encoding
  
     encodeWord  :: Word       -> Encoding
     encodeBytes :: ByteString -> Encoding
     -- et cetera
     

  • Codec.CBOR.Write defines the low-level wire-format encoder, e.g.

     toBuilder :: Encoding a -> Data.ByteString.Builder.Builder
     

• Capturing arbitrary terms

  • Codec.CBOR.Term provides the Term type, which provides a type for capturing arbitrary CBOR terms. Terms can be encoded and decoded with,

     data Term
       = TInt   Int
       | TBytes ByteString
       -- et cetera
  
     encodeTerm :: Term -> Encoding
     decodeTerm :: Decoder Term
     

• Debugging

  • Codec.CBOR.FlatTerm contains the FlatTerm type, which provides a concrete AST for capturing primitive CBOR wire encodings. This can be useful when testing decoders and encoders.