-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Yet Another Binary Serialisation Library (compatibility shim)
--   
--   This package is a shim around <tt>cborg</tt>, exposing an interface
--   compatible with the previous <tt>binary-serialise-cbor</tt>.
@package binary-serialise-cbor
@version 0.2.2.0


-- | Tools for reading values in a CBOR-encoded format back into ordinary
--   values.
module Data.Binary.Serialise.CBOR.Read

-- | Run a <a>Decoder</a> incrementally, returning a continuation
--   representing the result of the incremental decode.
deserialiseIncremental :: Decoder s a -> ST s (IDecode s a)

-- | Given a <a>Decoder</a> and some <a>ByteString</a> representing an
--   encoded CBOR value, return <a>Either</a> the decoded CBOR value or an
--   error. In addition to the decoded value return any remaining input
--   content and the number of bytes consumed.
deserialiseFromBytesWithSize :: (forall s. () => Decoder s a) -> ByteString -> Either DeserialiseFailure (ByteString, ByteOffset, a)

-- | An exception type that may be returned (by pure functions) or thrown
--   (by IO actions) that fail to deserialise a given input.
data DeserialiseFailure
DeserialiseFailure :: ByteOffset -> String -> DeserialiseFailure

-- | An Incremental decoder, used to represent the result of attempting to
--   run a decoder over a given input, and return a value of type
--   <tt>a</tt>.
data IDecode s a

-- | The decoder has consumed the available input and needs more to
--   continue. Provide <a>Just</a> if more input is available and
--   <a>Nothing</a> otherwise, and you will get a new <a>IDecode</a>.
Partial :: (Maybe ByteString -> ST s (IDecode s a)) -> IDecode s a

-- | The decoder has successfully finished. Except for the output value you
--   also get any unused input as well as the number of bytes consumed.
Done :: !ByteString -> {-# UNPACK #-} !ByteOffset -> a -> IDecode s a

-- | The decoder ran into an error. The decoder either used <a>fail</a> or
--   was not provided enough input. Contains any unconsumed input, the
--   number of bytes consumed, and a <a>DeserialiseFailure</a> exception
--   describing the reason why the failure occurred.
Fail :: !ByteString -> {-# UNPACK #-} !ByteOffset -> DeserialiseFailure -> IDecode s a

-- | A 0-based offset within the overall byte sequence that makes up the
--   input to the <a>Decoder</a>.
--   
--   This is an <a>Int64</a> since <a>Decoder</a> is incremental and can
--   decode more data than fits in memory at once. This is also compatible
--   with the result type of <a>length</a>.
type ByteOffset = Int64
deserialiseFromBytes :: (forall s. Decoder s a) -> ByteString -> Either DeserialiseFailure a