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

    -}