CBOR.hs

{-# OPTIONS_GHC -fno-warn-unused-imports #-}

-- |
-- Module      : Codec.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)
--
-- A library for working with CBOR.
--
module Codec.CBOR
 ( -- $intro
   -- * Library Structure
   -- $structure
 ) where

-- used by Haddocks
import Codec.CBOR.Decoding (Decoder)
import Codec.CBOR.Encoding (Encoding)
import Codec.CBOR.FlatTerm (FlatTerm)
import Codec.CBOR.Term     (Term, encodeTerm, decodeTerm)

{- $intro

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](/package/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.

-}

{- $structure

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.

      @
      'Codec.CBOR.Read.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.

        @
        'Codec.CBOR.Write.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.

-}