cborg-0.2.4.0: Concise Binary Object Representation (CBOR)

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.