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


-- | ByteString and Text streams for networking
--   
--   Provides bytestring and text streams which support both retry's and
--   invalidation for sending information before all information is known.
--   Includes support for enumerating over the chunks of bytes or chunks of
--   text sent.
@package network-stream
@version 0.1.0


-- | Network streams for use with lazy <a>ByteString</a>a.
--   
--   One can also send data in chunks, sending data whenever it is ready,
--   and the data will be collected transparently to the client interface.
--   
--   An enumerator version is also available in which an iteratee is given
--   each chunk of data invididually.
module Network.ByteString.Lazy.Stream

-- | Represents whether the stream transaction was a success or a failure;
--   nothing is done by the library with the attached value. If you do not
--   need to send back a value to the caller of <a>withStream</a>, you can
--   use a <a>Result</a> ().
data Result a
Success :: a -> Result a
Failure :: a -> Result a

-- | The core data type for a Stream. It can only be created using
--   <a>withStream</a>.
data Stream

-- | Doesn't fail, but tells the client that all the data sent by the
--   stream so far has been invalidated, and hence the queue of messages to
--   be sent is cleared.
invalidate :: Stream -> IO ()

-- | Opens a stream using the given handle and passes it to the function,
--   and then unwraps the result given and gives any user data that the
--   specific function wants to give back.
withStream :: Handle -> (Stream -> IO (Result a)) -> IO a

-- | Writes partial or full data over a <a>Stream</a>, placing it in the
--   queue of all of the partial data.
write :: Stream -> ByteString -> IO ()

-- | Serializes data and sends it over a newly created <a>Stream</a>.
send :: Binary a => Handle -> a -> IO ()

-- | Receives a <a>ByteString</a> sent via a <a>Stream</a>.
receive :: Handle -> IO (Maybe ByteString)

-- | Enumerator-based version of receive that allows the client to fold
--   over the data as it is being received. Each <a>ByteString</a> is a
--   single chunk sent from <a>write</a>. Keep in mind that any IO
--   performed is dangerous if you are possibly expected an Invalidation,
--   since then that IO could end up being incorrect. Hence, it is more
--   useful to simply use this in a pure manner to build up some result
--   data as the bytes are being streamed in.
receiveE :: MonadIO m => Handle -> Iteratee ByteString m b -> m (Maybe b)
instance Typeable StreamEnumException
instance Read StreamItem
instance Show StreamItem
instance Read a => Read (Result a)
instance Show a => Show (Result a)
instance Read StreamEnumException
instance Show StreamEnumException
instance Exception StreamEnumException
instance Binary StreamItem


-- | Streams using <a>Text</a> by encoding in Utf 8.
module Network.Text.Lazy.Stream

-- | Represents whether the stream transaction was a success or a failure;
--   nothing is done by the library with the attached value. If you do not
--   need to send back a value to the caller of <a>withStream</a>, you can
--   use a <a>Result</a> ().
data Result a
Success :: a -> Result a
Failure :: a -> Result a

-- | The core data type for a Stream. It can only be created using
--   <a>withStream</a>.
data Stream

-- | Doesn't fail, but tells the client that all the data sent by the
--   stream so far has been invalidated, and hence the queue of messages to
--   be sent is cleared.
invalidate :: Stream -> IO ()

-- | Opens a stream using the given handle and passes it to the function,
--   and then unwraps the result given and gives any user data that the
--   specific function wants to give back.
withStream :: Handle -> (Stream -> IO (Result a)) -> IO a

-- | Writes partial or full data over a <a>Stream</a>, placing it in the
--   queue of data to be sent. Encodes the <a>Text</a> with Utf8 into a
--   strict <tt>Data.ByteString.Lazy.ByteString</tt>.
write :: Stream -> Text -> IO ()
receive :: Handle -> IO (Maybe Text)

-- | Receives the entire data should the transfer over the stream be
--   successful. Returns <a>Nothing</a> on failure.
--   
--   Run an iteratee through an enumerator which supplies each block of
--   Text.
receiveE :: MonadIO m => Handle -> Iteratee Text m b -> m (Maybe b)


-- | Network streams for use with strict <a>ByteString</a>s. For lazy
--   ByteString's, see <tt>Network.ByteString.Lazy.Stream</tt>. Use this
--   module with <a>Serialize</a> to send data over a stream without
--   worrying about sending and receiving the lengths.
--   
--   One can also send data in chunks, sending data whenever it is ready,
--   and the data will be collected transparently to the client interface.
module Network.ByteString.Stream

-- | Represents whether the stream transaction was a success or a failure;
--   nothing is done by the library with the attached value. If you do not
--   need to send back a value to the caller of <a>withStream</a>, you can
--   use a <a>Result</a> ().
data Result a
Success :: a -> Result a
Failure :: a -> Result a

-- | The core data type for a Stream. It can only be created using
--   <a>withStream</a>.
data Stream

-- | Doesn't fail, but tells the client that all the data sent by the
--   stream so far has been invalidated, and hence the queue of messages to
--   be sent is cleared.
invalidate :: Stream -> IO ()

-- | Opens a stream using the given handle and passes it to the function,
--   and then unwraps the result given and gives any user data that the
--   specific function wants to give back.
withStream :: Handle -> (Stream -> IO (Result a)) -> IO a

-- | Writes partial or full data over a <a>Stream</a>, placing it in the
--   queue of all of the partial data.
write :: Stream -> ByteString -> IO ()

-- | Serializes data and sends it over a newly created <a>Stream</a>.
send :: Serialize a => Handle -> a -> IO ()

-- | Receives a ByteString sent via a <a>Stream</a>.
receive :: Handle -> IO (Maybe ByteString)

-- | Enumerator-based version of receive that allows the client to fold
--   over the data as it is being received. Each <a>ByteString</a> is a
--   single chunk sent from <a>write</a>. Keep in mind that any IO
--   performed is dangerous if you are possibly expected an Invalidation,
--   since then that IO could end up being incorrect. Hence, it is more
--   useful to simply use this in a pure manner to build up some result
--   data as the bytes are being streamed in.
receiveE :: MonadIO m => Handle -> Iteratee ByteString m b -> m (Maybe b)
instance Typeable StreamEnumException
instance Read StreamItem
instance Show StreamItem
instance Read a => Read (Result a)
instance Show a => Show (Result a)
instance Read StreamEnumException
instance Show StreamEnumException
instance Exception StreamEnumException
instance Serialize StreamItem


-- | Streams using <a>Text</a> by encoding in Utf 8.
module Network.Text.Stream

-- | Represents whether the stream transaction was a success or a failure;
--   nothing is done by the library with the attached value. If you do not
--   need to send back a value to the caller of <a>withStream</a>, you can
--   use a <a>Result</a> ().
data Result a
Success :: a -> Result a
Failure :: a -> Result a

-- | The core data type for a Stream. It can only be created using
--   <a>withStream</a>.
data Stream

-- | Doesn't fail, but tells the client that all the data sent by the
--   stream so far has been invalidated, and hence the queue of messages to
--   be sent is cleared.
invalidate :: Stream -> IO ()

-- | Opens a stream using the given handle and passes it to the function,
--   and then unwraps the result given and gives any user data that the
--   specific function wants to give back.
withStream :: Handle -> (Stream -> IO (Result a)) -> IO a

-- | Writes partial or full data over a <a>Stream</a>, placing it in the
--   queue of data to be sent. Encodes the <tt>Data.Text.Text</tt> with
--   Utf8 into a strict <tt>Data.ByteString.ByteString</tt>.
write :: Stream -> Text -> IO ()

-- | Receives the entire data should the transfer over the stream be
--   successful. Returns <a>Nothing</a> on failure.
receive :: Handle -> IO (Maybe Text)

-- | Run an iteratee through an enumerator which supplies each block of
--   Text.
receiveE :: MonadIO m => Handle -> Iteratee Text m b -> m (Maybe b)