-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Reliable, high-performance processing with left-fold enumerators -- -- Typical buffer–based incremental I/O is based around a single loop, -- which reads data from some source (such as a socket or file), -- transforms it, and generates one or more outputs (such as a line -- count, HTTP responses, or modified file). Although efficient and safe, -- these loops are all single–purpose; it is difficult or impossible to -- compose buffer–based processing loops. -- -- Haskell’s concept of “lazy I/O” allows pure code to operate on data -- from an external source. However, lazy I/O has several shortcomings. -- Most notably, resources such as memory and file handles can be -- retained for arbitrarily long periods of time, causing unpredictable -- performance and error conditions. -- -- Enumerators are an efficient, predictable, and safe alternative to -- lazy I/O. Discovered by Oleg Kiselyov, they allow large datasets to be -- processed in near–constant space by pure code. Although somewhat more -- complex to write, using enumerators instead of lazy I/O produces more -- correct programs. -- -- This library contains an enumerator implementation for Haskell, -- designed to be both simple and efficient. Three core types are -- defined, along with numerous helper functions: -- -- @package enumerator @version 0.4.7 -- | Core enumerator types, and some useful primitives. -- -- This module is intended to be imported qualified: -- -- 
--   import qualified Data.Enumerator as E
--
module Data.Enumerator -- | A Stream is a sequence of chunks generated by an -- Enumerator. -- -- (Chunks []) 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 -- | The primary data type for this library, which consumes input from a -- Stream until it either generates a value or encounters an -- error. Rather than requiring all input at once, an iteratee will -- return Continue when it is capable of processing more data. -- -- In general, iteratees begin in the Continue state. As each -- chunk is passed to the continuation, the iteratee returns the next -- step: Continue for more data, Yield when it's finished, -- or Error 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) data Step a m b -- | The Iteratee is capable of accepting more input. Note that more -- input is not necessarily required; the Iteratee might be able -- to generate a value immediately if it receives EOF. Continue :: (Stream a -> Iteratee a m b) -> Step a m b -- | The Iteratee cannot receive any more input, and has generated a -- result. Included in this value is left-over input, which can be passed -- to composed Iteratees. Yield :: b -> (Stream a) -> Step a m b -- | The Iteratee encountered an error which prevents it from -- proceeding further. Error :: SomeException -> Step a m b -- | While Iteratees consume data, enumerators generate it. Since -- Iteratee is an alias for m (Step a m -- b), Enumerators can be considered step transformers of -- type Step a m b -> m (Step a m b). -- -- Enumerators typically read from an external source (parser, -- handle, random generator, etc). They feed chunks into an -- Iteratee until the source runs out of data (triggering -- EOF) or the iteratee finishes processing (Yields 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 Enumeratee. Enumeratees have two -- input types, “outer a” (aOut) and “inner a” (aIn). type Enumeratee ao ai m b = Step ai m b -> Iteratee ao m (Step ai m b) -- | 
--   returnI step = Iteratee (return step)
--
returnI :: Monad m => Step a m b -> Iteratee a m b -- | 
--   yield x extra = returnI (Yield x extra)
--
yield :: Monad m => b -> Stream a -> Iteratee a m b -- | 
--   continue k = returnI (Continue k)
--
continue :: Monad m => (Stream a -> Iteratee a m b) -> Iteratee a m b -- | Equivalent to '(>>=)' for m (Step a m b); allows -- Iteratees 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' -- | 
--   (==<<) = flip (>>==)
--
(==<<) :: Monad m => (Step a m b -> Iteratee a' m b') -> Iteratee a m b -> Iteratee a' m b' -- | 
--   ($$) = (==<<)
--
-- -- This might be easier to read when passing a chain of iteratees to an -- enumerator. -- -- Since: 0.1.1 ($$) :: Monad m => (Step a m b -> Iteratee a' m b') -> Iteratee a m b -> Iteratee a' m b' -- | 
--   (>==>) e1 e2 s = e1 s >>== e2
--
-- -- Since: 0.1.1 (>==>) :: Monad m => Enumerator a m b -> (Step a m b -> Iteratee a' m b') -> Step a m b -> Iteratee a' m b' -- | 
--   (<==<) = flip (>==>)
--
-- -- Since: 0.1.1 (<==<) :: Monad m => (Step a m b -> Iteratee a' m b') -> Enumerator a m b -> Step a m b -> Iteratee a' m b' -- | 
--   throwError exc = returnI (Error (toException exc))
--
throwError :: (Monad m, Exception e) => e -> Iteratee a m b -- | Runs the iteratee, and calls an exception handler if an Error -- is returned. By handling errors within the enumerator library, and -- requiring all errors to be represented by SomeException, -- libraries with varying error types can be easily composed. -- -- Since: 0.1.1 catchError :: Monad m => Iteratee a m b -> (SomeException -> Iteratee a m b) -> Iteratee a m b -- | Run the entire input stream through a pure left fold, yielding when -- there is no more input. -- -- Since: 0.4.5 foldl :: Monad m => (b -> a -> b) -> b -> Iteratee a m b -- | Run the entire input stream through a pure strict left fold, yielding -- when there is no more input. -- -- Since: 0.4.5 foldl' :: Monad m => (b -> a -> b) -> b -> Iteratee a m b -- | Run the entire input stream through a monadic left fold, yielding when -- there is no more input. -- -- Since: 0.4.5 foldM :: Monad m => (b -> a -> m b) -> b -> Iteratee a m b -- | iterate f x enumerates an infinite stream of repeated -- applications of f to x. -- -- Analogous to iterate. -- -- Since: 0.4.5 iterate :: Monad m => (a -> a) -> a -> Enumerator a m b -- | Similar to iterate, except the iteration function is monadic. -- -- Since: 0.4.5 iterateM :: Monad m => (a -> m a) -> a -> Enumerator a m b -- | Enumerates an infinite stream of the provided value. -- -- Analogous to repeat. -- -- Since: 0.4.5 repeat :: Monad m => a -> Enumerator a m b -- | Enumerates an infinite stream by running the provided computation and -- passing each result to the iteratee. -- -- Since: 0.4.5 repeatM :: Monad m => m a -> Enumerator a m b -- | 
--   replicate n x = replicateM n (return x)
--
-- -- Analogous to replicate. -- -- Since: 0.4.5 replicate :: Monad m => Integer -> a -> Enumerator a m b -- | replicateM n m_x enumerates a stream of n input -- elements; each element is generated by running the input computation -- m_x once. -- -- Since: 0.4.5 replicateM :: Monad m => Integer -> m a -> Enumerator a m b -- | Like repeatM, except the computation may terminate the stream -- by returning Nothing. -- -- Since: 0.4.5 generateM :: Monad m => m (Maybe a) -> Enumerator a m b -- | 
--   map f = concatMap (x -> map f [x])
--
map :: Monad m => (ao -> ai) -> Enumeratee ao ai m b -- | 
--   concatMap f = concatMapM (return . f)
--
-- -- Since: 0.4.3 concatMap :: Monad m => (ao -> [ai]) -> Enumeratee ao ai m b -- | 
--   filter p = concatMap (x -> filter p [x])
--
-- -- Since: 0.4.5 filter :: Monad m => (a -> Bool) -> Enumeratee a a m b -- | 
--   mapM f = concatMapM (x -> mapM f [x])
--
-- -- Since: 0.4.3 mapM :: Monad m => (ao -> m ai) -> Enumeratee ao ai m b -- | concatMapM f applies f to each input element and feeds -- the resulting outputs to the inner iteratee. -- -- Since: 0.4.5 concatMapM :: Monad m => (ao -> m [ai]) -> Enumeratee ao ai m b -- | 
--   filterM p = concatMapM (x -> filterM p [x])
--
-- -- Since: 0.4.5 filterM :: Monad m => (a -> m Bool) -> Enumeratee a 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 () -- | Compose a list of Enumerators using '(>>==)' concatEnums :: Monad m => [Enumerator a m b] -> Enumerator a m b -- | joinI is used to “flatten” Enumeratees into an -- Iteratee. joinI :: Monad m => Iteratee a m (Step a' m b) -> Iteratee a m b -- | Flatten an enumerator/enumeratee pair into a single enumerator. joinE :: Monad m => Enumerator ao m (Step ai m b) -> Enumeratee ao ai m b -> Enumerator ai m b -- | Feeds outer input elements into the provided iteratee until it yields -- an inner input, passes that to the inner iteratee, and then loops. sequence :: Monad m => Iteratee ao m ai -> Enumeratee ao ai m b -- | enumList n xs enumerates xs as a stream, passing -- n inputs per chunk. -- -- Primarily useful for testing and debugging. enumList :: Monad m => Integer -> [a] -> Enumerator a m b -- | docs TODO enumEOF :: Monad m => Enumerator 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) -- | Like run, except errors are converted to exceptions and thrown. -- Primarily useful for small scripts or other simple cases. -- -- Since: 0.4.1 run_ :: Monad m => Iteratee a m b -> m b -- | 
--   checkDone = checkDoneEx (Chunks [])
--
-- -- Use this for enumeratees which do not have an input buffer. checkDone :: Monad m => ((Stream a -> Iteratee a m b) -> Iteratee a' m (Step a m b)) -> Enumeratee a' a m b -- | A common pattern in Enumeratee implementations is to check -- whether the inner Iteratee has finished, and if so, to return -- its output. checkDone passes its parameter a continuation if -- the Iteratee can still consume input, or yields otherwise. -- -- Since: 0.4.3 checkDoneEx :: Monad m => Stream a' -> ((Stream a -> Iteratee a m b) -> Iteratee a' m (Step a m b)) -> Enumeratee a' a m b -- | docs TODO isEOF :: Monad m => Iteratee a m Bool -- | Lift an Iteratee onto a monad transformer, re-wrapping the -- Iteratee’s inner monadic values. -- -- Since: 0.1.1 liftTrans :: (Monad m, MonadTrans t, Monad (t m)) => Iteratee a m b -> Iteratee a (t m) b -- | Deprecated in 0.4.5: use continue instead liftI :: Monad m => (Stream a -> Step a m b) -> Iteratee a m b -- | Peek at the next element in the stream, or Nothing if the -- stream has ended. peek :: Monad m => Iteratee a m (Maybe a) -- | Get the last element in the stream, or Nothing if the stream -- has ended. -- -- Consumes the entire stream. last :: Monad m => Iteratee a m (Maybe a) -- | Get how many elements remained in the stream. -- -- Consumes the entire stream. length :: Monad m => Iteratee a m Integer -- | Deprecated in 0.4.5: use Data.Enumerator.List.head instead head :: Monad m => Iteratee a m (Maybe a) -- | Deprecated in 0.4.5: use Data.Enumerator.List.drop instead drop :: Monad m => Integer -> Iteratee a m () -- | Deprecated in 0.4.5: use Data.Enumerator.List.dropWhile -- instead dropWhile :: Monad m => (a -> Bool) -> Iteratee a m () -- | Deprecated in 0.4.5: use Data.Enumerator.List.takeWhile -- instead span :: Monad m => (a -> Bool) -> Iteratee a m [a] -- | Deprecated in 0.4.5: use Data.Enumerator.List.takeWhile -- instead break :: Monad m => (a -> Bool) -> Iteratee a m [a] -- | Deprecated in 0.4.5: use Data.Enumerator.List.consume instead consume :: Monad m => Iteratee a m [a] -- | Deprecated in 0.4.5: use foldl instead -- -- Since: 0.1.1 liftFoldL :: Monad m => (b -> a -> b) -> b -> Iteratee a m b -- | Deprecated in 0.4.5: use foldl' instead -- -- Since: 0.1.1 liftFoldL' :: Monad m => (b -> a -> b) -> b -> Iteratee a m b -- | Deprecated in 0.4.5: use foldM instead -- -- Since: 0.1.1 liftFoldM :: Monad m => (b -> a -> m b) -> b -> Iteratee a m b instance Show a => Show (Stream a) instance Eq a => Eq (Stream a) instance (Typeable a, Typeable1 m) => Typeable1 (Iteratee a m) instance Monad m => Applicative (Iteratee a m) instance Monad m => Functor (Iteratee a m) instance MonadIO m => MonadIO (Iteratee a m) instance MonadTrans (Iteratee a) instance Monad m => Monad (Iteratee a m) instance Monoid (Stream a) instance Applicative Stream instance Functor Stream instance Monad Stream -- | This module is intended to be imported qualified: -- -- 
--   import qualified Data.Enumerator.List as EL
--
-- -- Since: 0.4.5 module Data.Enumerator.List -- | Get the next element from the stream, or Nothing if the stream -- has ended. -- -- Since: 0.4.5 head :: Monad m => Iteratee a m (Maybe a) -- | drop n ignores n input elements from the stream. -- -- Since: 0.4.5 drop :: Monad m => Integer -> Iteratee a m () -- | dropWhile p ignores input from the stream until the first -- element which does not match the predicate. -- -- Since: 0.4.5 dropWhile :: Monad m => (a -> Bool) -> Iteratee a m () -- | take n extracts the next n elements from the stream, -- as a list. -- -- Since: 0.4.5 take :: Monad m => Integer -> Iteratee a m [a] -- | takeWhile p extracts input from the stream until the first -- element which does not match the predicate. -- -- Since: 0.4.5 takeWhile :: Monad m => (a -> Bool) -> Iteratee a m [a] -- | Read all remaining input elements from the stream, and return as a -- list. -- -- Since: 0.4.5 consume :: Monad m => Iteratee a m [a] -- | require n buffers input until at least n elements are -- available, or throws an error if the stream ends early. -- -- Since: 0.4.5 require :: Monad m => Integer -> Iteratee a m () -- | isolate n reads at most n elements from the stream, -- and passes them to its iteratee. If the iteratee finishes early, -- elements continue to be consumed from the outer stream until n -- have been consumed. -- -- Since: 0.4.5 isolate :: Monad m => Integer -> Enumeratee a a m b -- | This module is intended to be imported qualified: -- -- 
--   import qualified Data.Enumerator.Binary as EB
--
-- -- Since: 0.4.5 module Data.Enumerator.Binary -- | Read bytes (in chunks of the given buffer size) from the handle, and -- stream them to an Iteratee. If an exception occurs during file -- IO, enumeration will stop and Error 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 ReadMode -- or ReadWriteMode. enumHandle :: MonadIO m => Integer -> Handle -> Enumerator ByteString m b -- | Opens a file path in binary mode, and passes the handle to -- enumHandle. The file will be closed when the Iteratee -- 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 Error will be -- returned. -- -- The handle should be opened with no encoding, and in WriteMode -- or ReadWriteMode. iterHandle :: MonadIO m => Handle -> Iteratee ByteString m () -- | Get the next byte from the stream, or Nothing if the stream has -- ended. -- -- Since: 0.4.5 head :: Monad m => Iteratee ByteString m (Maybe Word8) -- | drop n ignores n bytes of input from the stream. -- -- Since: 0.4.5 drop :: Monad m => Integer -> Iteratee ByteString m () -- | dropWhile p ignores input from the stream until the first -- byte which does not match the predicate. -- -- Since: 0.4.5 dropWhile :: Monad m => (Word8 -> Bool) -> Iteratee ByteString m () -- | take n extracts the next n bytes from the stream, as a -- lazy ByteString. -- -- Since: 0.4.5 take :: Monad m => Integer -> Iteratee ByteString m ByteString -- | takeWhile p extracts input from the stream until the first -- byte which does not match the predicate. -- -- Since: 0.4.5 takeWhile :: Monad m => (Word8 -> Bool) -> Iteratee ByteString m ByteString -- | Read all remaining input from the stream, and return as a lazy -- ByteString. -- -- Since: 0.4.5 consume :: Monad m => Iteratee ByteString m ByteString -- | require n buffers input until at least n bytes are -- available, or throws an error if the stream ends early. -- -- Since: 0.4.5 require :: Monad m => Integer -> Iteratee ByteString m () -- | isolate n reads at most n bytes from the stream, and -- passes them to its iteratee. If the iteratee finishes early, bytes -- continue to be consumed from the outer stream until n have been -- consumed. -- -- Since: 0.4.5 isolate :: Monad m => Integer -> Enumeratee ByteString ByteString m b -- | This module is intended to be imported qualified: -- -- 
--   import qualified Data.Enumerator.Text as ET
--
-- -- Since: 0.2 module Data.Enumerator.Text -- | Read lines of text from the handle, and stream them to an -- Iteratee. If an exception occurs during file IO, enumeration -- will stop and Error will be returned. Exceptions from the -- iteratee are not caught. -- -- The handle should be opened with an appropriate text encoding, and in -- ReadMode or ReadWriteMode. -- -- Since: 0.2 enumHandle :: MonadIO m => Handle -> Enumerator Text m b -- | Opens a file path in text mode, and passes the handle to -- enumHandle. The file will be closed when the Iteratee -- finishes. -- -- Since: 0.2 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 Error will be -- returned. -- -- The handle should be opened with an appropriate text encoding, and in -- WriteMode or ReadWriteMode. -- -- Since: 0.2 iterHandle :: MonadIO m => Handle -> Iteratee Text m () -- | Get the next character from the stream, or Nothing if the -- stream has ended. -- -- Since: 0.4.5 head :: Monad m => Iteratee Text m (Maybe Char) -- | drop n ignores n characters of input from the stream. -- -- Since: 0.4.5 drop :: Monad m => Integer -> Iteratee Text m () -- | dropWhile p ignores input from the stream until the first -- character which does not match the predicate. -- -- Since: 0.4.5 dropWhile :: Monad m => (Char -> Bool) -> Iteratee Text m () -- | take n extracts the next n characters from the stream, -- as a lazy Text. -- -- Since: 0.4.5 take :: Monad m => Integer -> Iteratee Text m Text -- | takeWhile p extracts input from the stream until the first -- character which does not match the predicate. -- -- Since: 0.4.5 takeWhile :: Monad m => (Char -> Bool) -> Iteratee Text m Text -- | Read all remaining input from the stream, and return as a lazy Text. -- -- Since: 0.4.5 consume :: Monad m => Iteratee Text m Text -- | require n buffers input until at least n characters -- are available, or throws an error if the stream ends early. -- -- Since: 0.4.5 require :: Monad m => Integer -> Iteratee Text m () -- | isolate n reads at most n characters from the stream, -- and passes them to its iteratee. If the iteratee finishes early, -- characters continue to be consumed from the outer stream until -- n have been consumed. -- -- Since: 0.4.5 isolate :: Monad m => Integer -> Enumeratee Text Text m b data Codec -- | Convert text into bytes, using the provided codec. If the codec is not -- capable of representing an input character, an error will be thrown. -- -- Since: 0.2 encode :: Monad m => Codec -> Enumeratee Text ByteString m b -- | Convert bytes into text, using the provided codec. If the codec is not -- capable of decoding an input byte sequence, an error will be thrown. -- -- Since: 0.2 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 -- | Deprecated in 0.4.5: use Data.Enumerator.Binary instead module Data.Enumerator.IO -- | Deprecated in 0.4.5: use Data.Enumerator.Binary.enumHandle -- instead enumHandle :: MonadIO m => Integer -> Handle -> Enumerator ByteString m b -- | Deprecated in 0.4.5: use Data.Enumerator.Binary.enumFile -- instead enumFile :: FilePath -> Enumerator ByteString IO b -- | Deprecated in 0.4.5: use Data.Enumerator.Binary.iterHandle -- instead iterHandle :: MonadIO m => Handle -> Iteratee ByteString m ()