-- 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.4


-- | <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.
--   
--   <pre>
--   <a>encode</a> :: (<a>Monad</a> m, <a>Binary</a> a) =&gt; a -&gt; <a>Producer'</a> <a>ByteString</a> m ()
--   </pre>
--   
--   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 -> Proxy x' x () ByteString m ()

-- | Like <a>encode</a>, except this uses an explicit <a>Put</a>.
--   
--   <pre>
--   <a>encodePut</a> :: (<a>Monad</a> m) =&gt; <a>Put</a> -&gt; <a>Producer'</a> <a>ByteString</a> m ()
--   </pre>
encodePut :: Monad m => Put -> Proxy x' x () 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;= f)  /= <a>zoom</a> <a>decoded</a> m &gt;&gt;= <a>zoom</a> <a>decoded</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

-- | A <a>Word</a> is an unsigned integral type, with the same size as
--   <a>Int</a>.
data Word

-- | The <a>Binary</a> class provides <a>put</a> and <a>get</a>, methods to
--   encode and decode a Haskell value to a lazy <a>ByteString</a>. It
--   mirrors the <a>Read</a> and <a>Show</a> classes for textual
--   representation of Haskell types, and is suitable for serialising
--   Haskell values to disk, over the network.
--   
--   For decoding and generating simple external binary formats (e.g. C
--   structures), Binary may be used, but in general is not suitable for
--   complex protocols. Instead use the <a>PutM</a> and <a>Get</a>
--   primitives directly.
--   
--   Instances of Binary should satisfy the following property:
--   
--   <pre>
--   decode . encode == id
--   </pre>
--   
--   That is, the <a>get</a> and <a>put</a> methods should be the inverse
--   of each other. A range of instances are provided for basic Haskell
--   types.
class Binary t

-- | Encode a value in the Put monad.
put :: Binary t => t -> Put

-- | Decode a value in the Get monad
get :: Binary t => Get t

-- | Encode a list of values in the Put monad. The default implementation
--   may be overridden to be more efficient but must still have the same
--   encoding format.
putList :: Binary t => [t] -> Put

-- | Put merely lifts Builder into a Writer monad, applied to ().
type Put = PutM ()
data Get a

-- | An offset, counted in bytes.
type ByteOffset = Int64
data Get a

-- | Put merely lifts Builder into a Writer monad, applied to ().
type Put = PutM ()

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A <a>ByteString</a> contains 8-bit bytes, or by using the operations
--   from <a>Data.ByteString.Char8</a> it can be interpreted as containing
--   8-bit characters.
data ByteString

-- | A <a>Parser</a> is an action that reads from and writes to a stored
--   <a>Producer</a>
type Parser a (m :: Type -> Type) r = forall x. () => StateT Producer a m x m r
instance GHC.Generics.Generic Pipes.Binary.DecodingError
instance Data.Data.Data Pipes.Binary.DecodingError
instance GHC.Classes.Eq Pipes.Binary.DecodingError
instance GHC.Read.Read Pipes.Binary.DecodingError
instance GHC.Show.Show Pipes.Binary.DecodingError
instance GHC.Exception.Type.Exception Pipes.Binary.DecodingError
instance Control.Monad.Trans.Error.Error Pipes.Binary.DecodingError