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


-- | Implementation of Oleg Kiselyov's left-fold enumerators
--   
--   Based on Oleg Kiselyov's IterateeM:
--   <a>http://okmij.org/ftp/Haskell/Iteratee/IterateeM.hs</a>
@package enumerator
@version 0.4.2


-- | An implementation of Oleg Kiselyov’s left-fold enumerators
module Data.Enumerator

-- | Not to be confused with types from the <tt>Stream</tt> or
--   <tt>stream-fusion</tt> packages, a <a>Stream</a> is a sequence of
--   chunks generated by an <a>Enumerator</a>. In contrast to Oleg’s
--   implementation, this stream does not support error handling -- errors
--   encountered while generating a stream are reported in the <a>Step</a>
--   type instead.
--   
--   <tt>(Chunks [])</tt> is used to indicate that a stream is still
--   active, but currently has no available data. Iteratees should ignore
--   empty chunks.
data Stream a
Chunks :: [a] -> Stream a
EOF :: Stream a
data Step a m b

-- | The <a>Iteratee</a> is capable of accepting more input. Note that more
--   input is not necessarily required; the <a>Iteratee</a> might be able
--   to generate a value immediately if it receives <a>EOF</a>.
Continue :: (Stream a -> Iteratee a m b) -> Step a m b

-- | The <a>Iteratee</a> has received enough input to generate a result.
--   Included in this value is left-over input, which can be passed to
--   composed <a>Iteratee</a>s.
Yield :: b -> (Stream a) -> Step a m b

-- | The <a>Iteratee</a> encountered an error which prevents it from
--   proceeding further.
Error :: SomeException -> Step a m b

-- | The primary data type for this library, which consumes input from a
--   <a>Stream</a> until it either generates a value or encounters an
--   error. Rather than requiring all input at once, an iteratee will
--   return <a>Continue</a> when it is capable of processing more data.
--   
--   In general, iteratees begin in the <a>Continue</a> state. As each
--   chunk is passed to the continuation, the iteratee returns the next
--   step: <a>Continue</a> for more data, <a>Yield</a> when it's finished,
--   or <a>Error</a> to abort processing.
newtype Iteratee a m b
Iteratee :: m (Step a m b) -> Iteratee a m b
runIteratee :: Iteratee a m b -> m (Step a m b)

-- | While <a>Iteratee</a>s consume data, enumerators generate it. Since
--   <tt><a>Iteratee</a></tt> is an alias for <tt>m (<a>Step</a> a m
--   b)</tt>, <a>Enumerator</a>s can be considered step transformers of
--   type <tt><a>Step</a> a m b -&gt; m (<a>Step</a> a m b)</tt>.
--   
--   <a>Enumerator</a>s typically read from an external source (parser,
--   handle, random generator, etc). They feed chunks into an
--   <a>Iteratee</a> until the source runs out of data (triggering
--   <a>EOF</a>) or the iteratee finishes processing (<a>Yield</a>s a
--   value).
type Enumerator a m b = Step a m b -> Iteratee a m b

-- | In cases where an enumerator acts as both a source and sink, the
--   resulting type is named an <a>Enumeratee</a>. Enumeratees have two
--   input types, “outer a” (<tt>aOut</tt>) and “inner a” (<tt>aIn</tt>).
type Enumeratee aOut aIn m b = Step aIn m b -> Iteratee aOut m (Step aIn m b)

-- | <pre>
--   returnI x = Iteratee (return x)
--   </pre>
returnI :: Monad m => Step a m b -> Iteratee a m b

-- | <pre>
--   yield x chunk = returnI (Yield x chunk)
--   </pre>
yield :: Monad m => b -> Stream a -> Iteratee a m b

-- | <pre>
--   continue k = returnI (Continue k)
--   </pre>
continue :: Monad m => (Stream a -> Iteratee a m b) -> Iteratee a m b

-- | <pre>
--   throwError err = returnI (Error err)
--   </pre>
throwError :: (Monad m, Exception e) => e -> Iteratee a m b
catchError :: Monad m => Iteratee a m b -> (SomeException -> Iteratee a m b) -> Iteratee a m b

-- | <pre>
--   liftI f = continue (returnI . f)
--   </pre>
liftI :: Monad m => (Stream a -> Step a m b) -> Iteratee a m b

-- | Equivalent to (&gt;&gt;=), but allows <a>Iteratee</a>s with different
--   input types to be composed.
(>>==) :: Monad m => Iteratee a m b -> (Step a m b -> Iteratee a' m b') -> Iteratee a' m b'

-- | <pre>
--   (==&lt;&lt;) = flip (&gt;&gt;==)
--   </pre>
(==<<) :: Monad m => (Step a m b -> Iteratee a' m b') -> Iteratee a m b -> Iteratee a' m b'

-- | <pre>
--   ($$) = (==&lt;&lt;)
--   </pre>
--   
--   This might be easier to read when passing a chain of iteratees to an
--   enumerator.
($$) :: Monad m => (Step a m b -> Iteratee a' m b') -> Iteratee a m b -> Iteratee a' m b'

-- | <pre>
--   (&gt;==&gt;) e1 e2 s = e1 s &gt;&gt;== e2
--   </pre>
(>==>) :: Monad m => Enumerator a m b -> (Step a m b -> Iteratee a' m b') -> Step a m b -> Iteratee a' m b'

-- | <pre>
--   (&lt;==&lt;) = flip (&gt;==&gt;)
--   </pre>
(<==<) :: Monad m => (Step a m b -> Iteratee a' m b') -> Enumerator a m b -> Step a m b -> Iteratee a' m b'

-- | Run an iteratee until it finishes, and return either the final value
--   (if it succeeded) or the error (if it failed).
run :: Monad m => Iteratee a m b -> m (Either SomeException b)
run_ :: Monad m => Iteratee a m b -> m b

-- | Consume all input until <a>EOF</a>, then return consumed input as a
--   list.
consume :: Monad m => Iteratee a m [a]

-- | Return <a>True</a> if the next <a>Stream</a> is <a>EOF</a>.
isEOF :: Monad m => Iteratee a m Bool

-- | Lift an <a>Iteratee</a> onto a monad transformer, re-wrapping the
--   <a>Iteratee</a>’s inner monadic values.
liftTrans :: (Monad m, MonadTrans t, Monad (t m)) => Iteratee a m b -> Iteratee a (t m) b

-- | Lifts a pure left fold into an iteratee.
liftFoldL :: Monad m => (b -> a -> b) -> b -> Iteratee a m b

-- | As <a>liftFoldL</a>, but strict in its accumulator.
liftFoldL' :: Monad m => (b -> a -> b) -> b -> Iteratee a m b

-- | Lifts a monadic left fold into an iteratee.
liftFoldM :: Monad m => (b -> a -> m b) -> b -> Iteratee a m b

-- | Print chunks as they're received from the enumerator, optionally
--   printing empty chunks.
printChunks :: (MonadIO m, Show a) => Bool -> Iteratee a m ()

-- | The most primitive enumerator; simply sends <a>EOF</a>. The iteratee
--   must either yield a value or throw an error continuing receiving
--   <a>EOF</a> will not terminate with any useful value.
enumEOF :: Monad m => Enumerator a m b

-- | Another small, useful enumerator separates an input list into chunks,
--   and sends them to the iteratee. This is useful for testing iteratees
--   in pure code.
enumList :: Monad m => Integer -> [a] -> Enumerator a m b

-- | Compose a list of <a>Enumerator</a>s using '(&gt;&gt;==)'
concatEnums :: Monad m => [Enumerator a m b] -> Enumerator a m b

-- | A common pattern in <a>Enumeratee</a> implementations is to check
--   whether the inner <a>Iteratee</a> has finished, and if so, to return
--   its output. <a>checkDone</a> passes its parameter a continuation if
--   the <a>Iteratee</a> can still consume input, or yields otherwise.
checkDone :: Monad m => ((Stream a -> Iteratee a m b) -> Iteratee a' m (Step a m b)) -> Enumeratee a' a m b
map :: Monad m => (ao -> ai) -> Enumeratee ao ai m b
sequence :: Monad m => Iteratee ao m ai -> Enumeratee ao ai m b

-- | <a>joinI</a> is used to “flatten” <a>Enumeratee</a>s into an
--   <a>Iteratee</a>.
joinI :: Monad m => Iteratee a m (Step a' m b) -> Iteratee a m b
head :: Monad m => Iteratee a m (Maybe a)
peek :: Monad m => Iteratee a m (Maybe a)
last :: Monad m => Iteratee a m (Maybe a)
length :: Monad m => Iteratee a m Integer
drop :: Monad m => Integer -> Iteratee a m ()
dropWhile :: Monad m => (a -> Bool) -> Iteratee a m ()
span :: Monad m => (a -> Bool) -> Iteratee a m [a]

-- | <pre>
--   break p = <a>span</a> (not . p)
--   </pre>
break :: Monad m => (a -> Bool) -> Iteratee a m [a]
instance Show a => Show (Stream a)
instance Eq a => Eq (Stream a)
instance MonadIO m => MonadIO (Iteratee a m)
instance MonadTrans (Iteratee a)
instance Monad m => Applicative (Iteratee a m)
instance Monad m => Functor (Iteratee a m)
instance Monad m => Monad (Iteratee a m)
instance Monad Stream
instance Functor Stream
instance Monoid (Stream a)


-- | Enumerator-based IO
module Data.Enumerator.IO

-- | Read bytes (in chunks of the given buffer size) from the handle, and
--   stream them to an <a>Iteratee</a>. If an exception occurs during file
--   IO, enumeration will stop and <a>Error</a> will be returned.
--   Exceptions from the iteratee are not caught.
--   
--   This enumerator blocks until at least one byte is available from the
--   handle, and might read less than the maximum buffer size in some
--   cases.
--   
--   The handle should be opened with no encoding, and in <a>ReadMode</a>
--   or <a>ReadWriteMode</a>.
enumHandle :: MonadIO m => Integer -> Handle -> Enumerator ByteString m b

-- | Opens a file path in binary mode, and passes the handle to
--   <a>enumHandle</a>. The file will be closed when the <a>Iteratee</a>
--   finishes.
enumFile :: FilePath -> Enumerator ByteString IO b

-- | Read bytes from a stream and write them to a handle. If an exception
--   occurs during file IO, enumeration will stop and <a>Error</a> will be
--   returned.
--   
--   The handle should be opened with no encoding, and in <a>WriteMode</a>
--   or <a>ReadWriteMode</a>.
iterHandle :: MonadIO m => Handle -> Iteratee ByteString m ()


-- | Enumerator-based text IO
module Data.Enumerator.Text

-- | Read lines of text from the handle, and stream them to an
--   <a>Iteratee</a>. If an exception occurs during file IO, enumeration
--   will stop and <a>Error</a> will be returned. Exceptions from the
--   iteratee are not caught.
--   
--   The handle should be opened with an appropriate text encoding, and in
--   <a>ReadMode</a> or <a>ReadWriteMode</a>.
enumHandle :: MonadIO m => Handle -> Enumerator Text m b

-- | Opens a file path in text mode, and passes the handle to
--   <a>enumHandle</a>. The file will be closed when the <a>Iteratee</a>
--   finishes.
enumFile :: FilePath -> Enumerator Text IO b

-- | Read text from a stream and write it to a handle. If an exception
--   occurs during file IO, enumeration will stop and <a>Error</a> will be
--   returned.
--   
--   The handle should be opened with an appropriate text encoding, and in
--   <a>WriteMode</a> or <a>ReadWriteMode</a>.
iterHandle :: MonadIO m => Handle -> Iteratee Text m ()
data Codec
encode :: Monad m => Codec -> Enumeratee Text ByteString m b
decode :: Monad m => Codec -> Enumeratee ByteString Text m b
utf8 :: Codec
utf16_le :: Codec
utf16_be :: Codec
utf32_le :: Codec
utf32_be :: Codec
ascii :: Codec
iso8859_1 :: Codec
instance Show Codec