-- 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>changelog.md</tt> file in the source distribution to learn
--   about any important changes between version.
@package pipes-binary
@version 0.4.0.2


-- | <tt>pipes</tt> utilities for encoding and decoding values as byte
--   streams
--   
--   The tutorial at the bottom of this module illustrates how to use this
--   library.
--   
--   In this module, the following type synonym compatible with the
--   <tt>lens</tt>, <tt>lens-family</tt> and <tt>lens-family-core</tt>
--   libraries is used but not exported:
--   
--   <pre>
--   type Lens' a b = forall f . <a>Functor</a> f =&gt; (b -&gt; f b) -&gt; (a -&gt; f a)
--   </pre>
module Pipes.Binary

-- | Convert a value to a byte stream.
--   
--   Keep in mind that a single encode value might be split into many
--   <a>ByteString</a> chunks, that is, the lenght of the obtained
--   <a>Producer</a> might be greater than 1.
--   
--   <i>Hint:</i> You can easily turn this <a>Producer'</a> into a
--   <a>Pipe</a> that encodes <a>Binary</a> instances as they flow
--   downstream using:
--   
--   <pre>
--   <a>for</a> <a>cat</a> <a>encode</a> :: (<a>Monad</a> m, <a>Binary</a> a) =&gt; <a>Pipe</a> a <a>ByteString</a> m r
--   </pre>
encode :: (Monad m, Binary a) => a -> Producer' ByteString m ()

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

-- | Parse a value from a byte stream.
decode :: (Monad m, Binary a) => Parser ByteString m (Either DecodingError a)

-- | <i>Improper lens</i> that turns a stream of bytes into a stream of
--   decoded values.
--   
--   By <i>improper lens</i> we mean that in practice you can't expect the
--   <i>Monad Morphism Laws</i> to be true when using <a>decoded</a> with
--   <a>zoom</a>.
--   
--   <pre>
--   <a>zoom</a> <a>decoded</a> (<a>return</a> r) /= <a>return</a> r
--   <a>zoom</a> <a>decoded</a> (m &gt;&gt;= k)  /= <a>zoom</a> m &gt;&gt;= <a>zoom</a> . f
--   </pre>
decoded :: (Monad m, Binary a) => Lens' (Producer ByteString m r) (Producer a m (Either (DecodingError, Producer ByteString m r) r))

-- | Like <a>decode</a>, but also returns the length of input consumed in
--   order to to decode the value.
decodeL :: (Monad m, Binary a) => Parser ByteString m (Either DecodingError (ByteOffset, a))

-- | Like <a>decoded</a>, except this tags each decoded value with the
--   length of input consumed in order to decode it.
decodedL :: (Monad m, Binary a) => Lens' (Producer ByteString m r) (Producer (ByteOffset, a) m (Either (DecodingError, Producer ByteString m r) r))

-- | Like <a>decode</a>, except this requires an explicit <a>Get</a>
--   instead of any <a>Binary</a> instance.
decodeGet :: Monad m => Get a -> Parser ByteString m (Either DecodingError a)

-- | Like <a>decodeL</a>, except this requires an explicit <a>Get</a>
--   instead of any <a>Binary</a> instance.
decodeGetL :: Monad m => Get a -> Parser ByteString m (Either DecodingError (ByteOffset, a))

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

-- | Number of bytes consumed before the error
deConsumed :: DecodingError -> {-# UNPACK #-} !ByteOffset

-- | Error message
deMessage :: DecodingError -> !String
instance Typeable DecodingError
instance Show DecodingError
instance Read DecodingError
instance Eq DecodingError
instance Data DecodingError
instance Generic DecodingError
instance Datatype D1DecodingError
instance Constructor C1_0DecodingError
instance Selector S1_0_0DecodingError
instance Selector S1_0_1DecodingError
instance Error DecodingError
instance Exception DecodingError