-- 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.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 e 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 e a m b) -> Step e 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 e a m b

-- | The <a>Iteratee</a> encountered an error which prevents it from
--   proceeding further. The type of error will depend on the
--   <a>Enumerator</a> and/or <a>Iteratee</a> -- common choices are
--   <a>String</a> and <a>SomeException</a>.
Error :: e -> Step e 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 e a m b
Iteratee :: m (Step e a m b) -> Iteratee e a m b
runIteratee :: Iteratee e a m b -> m (Step e 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> e a m
--   b)</tt>, <a>Enumerator</a>s can be considered step transformers of
--   type <tt><a>Step</a> e a m b -&gt; m (<a>Step</a> e 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 e a m b = Step e a m b -> Iteratee e 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 e aOut aIn m b = Step e aIn m b -> Iteratee e aOut m (Step e aIn m b)

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

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

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

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

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

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

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

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

-- | <pre>
--   (&lt;==&lt;) = flip (&gt;==&gt;)
--   </pre>
(<==<) :: (Monad m) => (Step e a m b -> Iteratee e a' m b') -> Enumerator e a m b -> Step e a m b -> Iteratee e 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 e a m b -> m (Either e b)

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

-- | Return <a>True</a> if the next <a>Stream</a> is <a>EOF</a>.
isEOF :: (Monad m) => Iteratee e 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 e a m b -> Iteratee e a (t m) b

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

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

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

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

-- | Compose a list of <a>Enumerator</a>s using '(&gt;&gt;==)'
concatEnums :: (Monad m) => [Enumerator e a m b] -> Enumerator e 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 e a m b) -> Iteratee e a' m (Step e a m b)) -> Enumeratee e a' a m b
map :: (Monad m) => (ao -> ai) -> Enumeratee e ao ai m b
sequence :: (Monad m) => Iteratee e ao m ai -> Enumeratee e ao ai m b

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

-- | <pre>
--   break p = <a>span</a> (not . p)
--   </pre>
break :: (Monad m) => (a -> Bool) -> Iteratee e a m [a]
instance (Show a) => Show (Stream a)
instance (Eq a) => Eq (Stream a)
instance (MonadIO m) => MonadIO (Iteratee e a m)
instance MonadTrans (Iteratee e a)
instance (Monad m) => Applicative (Iteratee e a m)
instance (Monad m) => Functor (Iteratee e a m)
instance (Monad m) => Monad (Iteratee e 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.
enumHandle :: Integer -> Handle -> Enumerator SomeException ByteString IO 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 SomeException ByteString IO b

-- | Opens a file path in binary mode, and passes the handle to
--   <a>iterHandle</a>. The file will be closed when the <a>Iteratee</a>
--   finishes.
iterFile :: FilePath -> Iteratee SomeException ByteString IO ()

-- | 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.
iterHandle :: Handle -> Iteratee SomeException ByteString IO ()


-- | 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.
enumHandle :: Handle -> Enumerator SomeException Text IO 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 SomeException 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.
iterHandle :: Handle -> Iteratee SomeException Text IO ()

-- | Opens a file path in text mode, and passes the handle to
--   <a>iterHandle</a>. The file will be closed when the <a>Iteratee</a>
--   finishes.
iterFile :: FilePath -> Iteratee SomeException Text IO ()
data Codec
encode :: (Monad m) => Codec -> Enumeratee SomeException Text ByteString m b
decode :: (Monad m) => Codec -> Enumeratee SomeException 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