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


-- | Encode and decode binary streams using the pipes and binary libraries.
--   
--   Encode and decode binary Pipes streams using the <tt>binary</tt>
--   library.
--   
--   See the <tt>NEWS</tt> file in the source distribution to learn about
--   any important changes between version.
@package pipes-binary
@version 0.2.0


-- | This module exports facilities that allow you to encode and decode
--   Pipes streams of binary values. It builds on top of the
--   <tt>binary</tt>, <tt>pipes</tt> and <tt>pipes-parse</tt> libraries,
--   and assumes you know how to use those libraries.
module Pipes.Binary

-- | Encodes the given <a>Binary</a> instance and sends it downstream in
--   <a>ByteString</a> chunks.
encode :: (Monad m, Binary x) => x -> Producer' ByteString m ()

-- | Try to decode leading output from the underlying <a>Producer</a> into
--   a <a>Binary</a> instance, returning either a <a>DecodingError</a> on
--   failure, or a pair with the decoded entity together with the number of
--   bytes consumed in order to produce it.
--   
--   <i>Do not</i> use this function if <a>isEndOfBytes</a> returns
--   <a>True</a>, otherwise you may get unexpected decoding errors.
decode :: (Monad m, Binary b) => StateT (Producer ByteString m r) m (Either DecodingError (ByteOffset, b))

-- | Continuously decode output from the given <a>Producer</a> into a
--   <a>Binary</a> instance, sending downstream pairs of each successfully
--   decoded entity together with the number of bytes consumed in order to
--   produce it.
--   
--   This <a>Producer</a> runs until it either runs out of input or a
--   decoding failure occurs, in which case it returns <a>Left</a> with a
--   <a>DecodingError</a> and a <a>Producer</a> with any leftovers. You can
--   use <a>errorP</a> to turn the <a>Either</a> return value into an
--   <a>ErrorT</a> monad transformer.
decodeMany :: (Monad m, Binary b) => Producer ByteString m r -> Producer' (ByteOffset, b) m (Either (DecodingError, Producer ByteString m r) r)

-- | Like <a>decode</a>, except it takes an explicit <a>Get</a> monad.
decodeGet :: Monad m => Get b -> StateT (Producer ByteString m r) m (Either DecodingError (ByteOffset, b))

-- | Like <a>decodeMany</a>, except it takes an explicit <a>Get</a> monad.
decodeGetMany :: Monad m => Get b -> Producer ByteString m r -> Producer' (ByteOffset, b) m (Either (DecodingError, Producer ByteString m r) r)

-- | Like <a>encode</a>, except it takes an explicit <a>Put</a> monad.
encodePut :: Monad m => Put -> Producer' ByteString m ()

-- | A <a>Get</a> decoding error, as provided by <a>Fail</a>.
data DecodingError
DecodingError :: ByteOffset -> String -> DecodingError

-- | Number of bytes consumed before the error.
peConsumed :: DecodingError -> ByteOffset

-- | Error message.
peMessage :: DecodingError -> String

-- | Checks if the underlying <a>Producer</a> has any bytes left. Leading
--   <a>empty</a> chunks are discarded.

-- | <i>Deprecated: Will be removed as soon as the `pipes-bytestring`
--   library exports it </i>
isEndOfBytes :: Monad m => StateT (Producer ByteString m r) m Bool