cborg-0.2.0.0: Concise Binary Object Representation

Copyright(c) Duncan Coutts 2015-2017
LicenseBSD3-style (see LICENSE.txt)
Maintainerduncan@community.haskell.org
Stabilityexperimental
Portabilitynon-portable (GHC extensions)
Safe HaskellNone
LanguageHaskell2010

Codec.CBOR

Description

A library for working with CBOR.

Synopsis

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
     
     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
       
       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.