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


-- | Enumerator tools for text-based network protocols
--   
--   Enumerator tools for text-based network protocols. This includes,
--   among other things, an enumeratee to split an incoming ByteString
--   stream to a length-limited line stream in a safe manner (i.e. in
--   constant space).
@package netlines
@version 0.4.3


-- | Enumerator tools for working with text-based network protocols.
module Data.Enumerator.NetLines

-- | Get the next nonempty line from the stream using <a>netLineEmpty</a>.
netLine :: Monad m => Int -> Iteratee ByteString m (Maybe ByteString)

-- | Get the next line from the stream, length-limited by the given
--   <a>Int</a>. This iteratee is error-tolerant by using LF as the line
--   terminator and simply ignoring all CR characters.
netLineEmpty :: Monad m => Int -> Iteratee ByteString m (Maybe ByteString)

-- | Get the next nonempty word from the stream with the given maximum
--   length. Based on <a>netWordEmpty</a>.
netWord :: Monad m => Int -> Iteratee ByteString m (Maybe ByteString)

-- | Get the next word from the stream with the given maximum length. This
--   iteratee is error-tolerant by using ASCII whitespace as splitting
--   characters.
netWordEmpty :: Monad m => Int -> Iteratee ByteString m (Maybe ByteString)

-- | Convert a raw byte stream to a stream of lines based on
--   <a>netLine</a>.
netLines :: Monad m => Int -> Enumeratee ByteString ByteString m b

-- | Convert a raw byte stream to a stream of lines based on
--   <a>netLineEmpty</a>.
netLinesEmpty :: Monad m => Int -> Enumeratee ByteString ByteString m b

-- | Split the raw byte stream into words based on <a>netWord</a>.
netWords :: Monad m => Int -> Enumeratee ByteString ByteString m b

-- | Split the raw byte stream into words based on <a>netWords</a>.
netWordsEmpty :: Monad m => Int -> Enumeratee ByteString ByteString m b

-- | Get the next token, where tokens are splitted by the first given
--   predicate and filtered by the second. Tokens are length-limited by the
--   given <a>Int</a> and are truncated safely in constant space.
netSplitBy :: Monad m => (Word8 -> Bool) -> (Word8 -> Bool) -> Int -> Iteratee ByteString m (Maybe ByteString)

-- | Split the stream using the supplied iteratee.
netSplitsBy :: Monad m => Iteratee ByteString m (Maybe ByteString) -> Enumeratee ByteString ByteString m b

-- | Exception for timed out IO operations.
newtype TimeoutError
TimeoutError :: String -> TimeoutError
timeoutErrorMessage :: TimeoutError -> String

-- | Enumerate from a handle with the given buffer size (first argument),
--   read timeout in milliseconds (second argument) and session timeout in
--   milliseconds (third argument). If either timeout is exceeded a
--   <a>TimeoutError</a> exception is thrown via <a>throwError</a>.
enumHandleSession :: MonadIO m => Int -> Int -> Int -> Handle -> Enumerator ByteString m b

-- | Enumerate from a handle with the given buffer size (first argument)
--   and timeout in milliseconds (second argument). If the timeout is
--   exceeded a <a>TimeoutError</a> exception is thrown via
--   <a>throwError</a>.
--   
--   Note that this timeout is not a timeout for the whole enumeration, but
--   for each individual read operation. In other words, this timeout
--   protects against dead/unresponsive peers, but not against (perhaps
--   intentionally) slowly sending peers.
enumHandleTimeout :: MonadIO m => Int -> Int -> Handle -> Enumerator ByteString m b

-- | Writes its inputs to the given handle. Times out after the given
--   number of milliseconds with a <a>TimeoutError</a> iteratee exception.
--   The handle should be unbuffered and in binary mode. See
--   <a>hSetBuffering</a> and <a>hSetBinaryMode</a>.
--   
--   Please note that only the write operations themselves are timed. Most
--   notably the operation of the data source enumerator is *not* timed.
--   Hence the operation may time out later than the given time margin, but
--   never earlier.
iterHandleTimeout :: MonadIO m => Int -> Handle -> Iteratee ByteString m ()
instance Typeable TimeoutError
instance Show TimeoutError
instance Exception TimeoutError