cborg-0.2.9.0: Concise Binary Object Representation (CBOR)

Copyright | (c) Duncan Coutts 2015-2017
License | BSD3-style (see LICENSE.txt)
Maintainer | duncan@community.haskell.org
Stability | experimental
Portability | non-portable (GHC extensions)
Safe Haskell | Safe-Inferred
Language | Haskell2010

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

  - 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. `Term`s 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.