enumerator-0.4.8: src/compatibility.anansi

\section{Legacy compatibility}

Version 0.4.5 of this library introduced some substantial reorganization
and renamings; this section implements compatibility shims, so the API
remains stable.

\subsection{Obsolete functions}

These are functions which seemed like good ideas, or were defined by other
enumerator/iteratee libraries, but turned out to be basically useless. At
least, I've never figured out what they're good for.

:d compatibility: obsolete
|apidoc Data.Enumerator.liftTrans|
liftTrans :: (Monad m, MonadTrans t, Monad (t m)) =>
             Iteratee a m b -> Iteratee a (t m) b
liftTrans iter = Iteratee $ do
	step <- lift (runIteratee iter)
	return $ case step of
		Yield x cs -> Yield x cs
		Error err -> Error err
		Continue k -> Continue (liftTrans . k)
:

:d compatibility: obsolete
{-# DEPRECATED liftI "Use 'Data.Enumerator.continue' instead" #-}
|apidoc Data.Enumerator.liftI|
liftI :: Monad m => (Stream a -> Step a m b)
      -> Iteratee a m b
liftI k = continue (returnI . k)
:

:d compatibility: obsolete
|apidoc Data.Enumerator.peek|
peek :: Monad m => Iteratee a m (Maybe a)
peek = continue loop where
	loop (Chunks []) = continue loop
	loop chunk@(Chunks (x:_)) = yield (Just x) chunk
	loop EOF = yield Nothing EOF
:

:d compatibility: obsolete
|apidoc Data.Enumerator.last|
last :: Monad m => Iteratee a m (Maybe a)
last = continue (loop Nothing) where
	loop ret (Chunks xs) = continue . loop $ case xs of
		[] -> ret
		_ -> Just (Prelude.last xs)
	loop ret EOF = yield ret EOF
:

:d compatibility: obsolete
|apidoc Data.Enumerator.length|
length :: Monad m => Iteratee a m Integer
length = continue (loop 0) where
	len = genericLength
	loop n (Chunks xs) = continue (loop (n + len xs))
	loop n EOF = yield n EOF
:

\subsection{Aliases}

In previous library versions, several list-based iteratees were defined in
{\tt Data.Enumerator}. They are now defined in {\tt Data.Enumerator.List};
because these functions use core enumerator types, a bit of module
gymnastics is required to get everything compiling properly.

:f Data/Enumerator.hs-boot
module Data.Enumerator where
import qualified Control.Exception as Exc
data Stream a
data Step a m b
	= Continue (Stream a -> Iteratee a m b)
	| Yield b (Stream a)
	| Error Exc.SomeException
newtype Iteratee a m b = Iteratee
	{ runIteratee :: m (Step a m b)
	}
type Enumerator a m b = Step a m b -> Iteratee a m b
type Enumeratee ao ai m b = Step ai m b -> Iteratee ao m (Step ai m b)
:

:f Data/Enumerator/List.hs-boot
module Data.Enumerator.List where
import {-# SOURCE #-} Data.Enumerator
head :: Monad m => Iteratee a m (Maybe a)
drop :: Monad m => Integer -> Iteratee a m ()
dropWhile :: Monad m => (a -> Bool) -> Iteratee a m ()
takeWhile :: Monad m => (a -> Bool) -> Iteratee a m [a]
consume :: Monad m => Iteratee a m [a]
fold :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
foldM :: Monad m => (b -> a -> m b) -> b -> Iteratee a m b
iterate :: Monad m => (a -> a) -> a -> Enumerator a m b
iterateM :: Monad m => (a -> m a) -> a -> Enumerator a m b
repeat :: Monad m => a -> Enumerator a m b
repeatM :: Monad m => m a -> Enumerator a m b
replicateM :: Monad m => Integer -> m a -> Enumerator a m b
replicate :: Monad m => Integer -> a -> Enumerator a m b
generateM :: Monad m => m (Maybe a) -> Enumerator a m b
map :: Monad m => (ao -> ai) -> Enumeratee ao ai m b
mapM :: Monad m => (ao -> m ai) -> Enumeratee ao ai m b
concatMap :: Monad m => (ao -> [ai]) -> Enumeratee ao ai m b
concatMapM :: Monad m => (ao -> m [ai]) -> Enumeratee ao ai m b
filter :: Monad m => (a -> Bool) -> Enumeratee a a m b
filterM :: Monad m => (a -> m Bool) -> Enumeratee a a m b
:

These {\tt .hs-boot} files are enough for {\tt Data.Enumerator} to re-export
the list functions under old names, with appropriate deprecation warnings.

:d compatibility: aliases
{-# DEPRECATED head "Use 'Data.Enumerator.List.head' instead" #-}
|apidoc Data.Enumerator.head|
head :: Monad m => Iteratee a m (Maybe a)
head = EL.head

{-# DEPRECATED drop "Use 'Data.Enumerator.List.drop' instead" #-}
|apidoc Data.Enumerator.drop|
drop :: Monad m => Integer -> Iteratee a m ()
drop = EL.drop

{-# DEPRECATED dropWhile "Use 'Data.Enumerator.List.dropWhile' instead" #-}
|apidoc Data.Enumerator.dropWhile|
dropWhile :: Monad m => (a -> Bool) -> Iteratee a m ()
dropWhile = EL.dropWhile

{-# DEPRECATED span "Use 'Data.Enumerator.List.takeWhile' instead" #-}
|apidoc Data.Enumerator.span|
span :: Monad m => (a -> Bool) -> Iteratee a m [a]
span = EL.takeWhile

{-# DEPRECATED break "Use 'Data.Enumerator.List.takeWhile' instead" #-}
|apidoc Data.Enumerator.break|
break :: Monad m => (a -> Bool) -> Iteratee a m [a]
break p = EL.takeWhile (not . p)

{-# DEPRECATED consume "Use 'Data.Enumerator.List.consume' instead" #-}
|apidoc Data.Enumerator.consume|
consume :: Monad m => Iteratee a m [a]
consume = EL.consume

{-# DEPRECATED foldl "Use Data.Enumerator.List.fold instead" #-}
|apidoc Data.Enumerator.foldl|
foldl :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
foldl step = continue . loop where
	fold = Prelude.foldl step
	loop acc stream = case stream of
		Chunks [] -> continue (loop acc)
		Chunks xs -> continue (loop (fold acc xs))
		EOF -> yield acc EOF

{-# DEPRECATED foldl' "Use Data.Enumerator.List.fold instead" #-}
|apidoc Data.Enumerator.foldl'|
foldl' :: Monad m => (b -> a -> b) -> b -> Iteratee a m b
foldl' = EL.fold

{-# DEPRECATED foldM "Use Data.Enumerator.List.foldM instead" #-}
|apidoc Data.Enumerator.foldM|
foldM :: Monad m => (b -> a -> m b) -> b -> Iteratee a m b
foldM = EL.foldM

{-# DEPRECATED iterate "Use Data.Enumerator.List.iterate instead" #-}
|apidoc Data.Enumerator.iterate|
iterate :: Monad m => (a -> a) -> a -> Enumerator a m b
iterate = EL.iterate

{-# DEPRECATED iterateM "Use Data.Enumerator.List.iterateM instead" #-}
|apidoc Data.Enumerator.iterateM|
iterateM :: Monad m => (a -> m a) -> a -> Enumerator a m b
iterateM = EL.iterateM

{-# DEPRECATED repeat "Use Data.Enumerator.List.repeat instead" #-}
|apidoc Data.Enumerator.repeat|
repeat :: Monad m => a -> Enumerator a m b
repeat = EL.repeat

{-# DEPRECATED repeatM "Use Data.Enumerator.List.repeatM instead" #-}
|apidoc Data.Enumerator.repeatM|
repeatM :: Monad m => m a -> Enumerator a m b
repeatM = EL.repeatM

{-# DEPRECATED replicate "Use Data.Enumerator.List.replicate instead" #-}
|apidoc Data.Enumerator.replicate|
replicate :: Monad m => Integer -> a -> Enumerator a m b
replicate = EL.replicate

{-# DEPRECATED replicateM "Use Data.Enumerator.List.replicateM instead" #-}
|apidoc Data.Enumerator.replicateM|
replicateM :: Monad m => Integer -> m a -> Enumerator a m b
replicateM = EL.replicateM

{-# DEPRECATED generateM "Use Data.Enumerator.List.generateM instead" #-}
|apidoc Data.Enumerator.generateM|
generateM :: Monad m => m (Maybe a) -> Enumerator a m b
generateM = EL.generateM

{-# DEPRECATED map "Use Data.Enumerator.List.map instead" #-}
|apidoc Data.Enumerator.map|
map :: Monad m => (ao -> ai) -> Enumeratee ao ai m b
map = EL.map

{-# DEPRECATED mapM "Use Data.Enumerator.List.mapM instead" #-}
|apidoc Data.Enumerator.mapM|
mapM :: Monad m => (ao -> m ai) -> Enumeratee ao ai m b
mapM = EL.mapM

{-# DEPRECATED concatMap "Use Data.Enumerator.List.concatMap instead" #-}
|apidoc Data.Enumerator.concatMap|
concatMap :: Monad m => (ao -> [ai]) -> Enumeratee ao ai m b
concatMap = EL.concatMap

{-# DEPRECATED concatMapM "Use Data.Enumerator.List.concatMapM instead" #-}
|apidoc Data.Enumerator.concatMapM|
concatMapM :: Monad m => (ao -> m [ai]) -> Enumeratee ao ai m b
concatMapM = EL.concatMapM

{-# DEPRECATED filter "Use Data.Enumerator.List.filter instead" #-}
|apidoc Data.Enumerator.filter|
filter :: Monad m => (a -> Bool) -> Enumeratee a a m b
filter = EL.filter

{-# DEPRECATED filterM "Use Data.Enumerator.List.filterM instead" #-}
|apidoc Data.Enumerator.filterM|
filterM :: Monad m => (a -> m Bool) -> Enumeratee a a m b
filterM = EL.filterM
:

0.4.5 also saw the pure-fold enumerators renamed, to match other functions
based on {\tt Prelude} names.

:d compatibility: aliases
{-# DEPRECATED liftFoldL "Use Data.Enumerator.List.fold instead" #-}
|apidoc Data.Enumerator.liftFoldL|
liftFoldL :: Monad m => (b -> a -> b) -> b
          -> Iteratee a m b
liftFoldL = Data.Enumerator.foldl

{-# DEPRECATED liftFoldL' "Use Data.Enumerator.List.fold instead" #-}
|apidoc Data.Enumerator.liftFoldL'|
liftFoldL' :: Monad m => (b -> a -> b) -> b
           -> Iteratee a m b
liftFoldL' = EL.fold

{-# DEPRECATED liftFoldM "Use Data.Enumerator.List.foldM instead" #-}
|apidoc Data.Enumerator.liftFoldM|
liftFoldM :: Monad m => (b -> a -> m b) -> b
          -> Iteratee a m b
liftFoldM = EL.foldM
:

Finally, the {\tt Data.Enumerator.IO} module was moved to
{\tt Data.Enumerator.Binary}, and altered to include many more functions
related to binary and {\tt ByteString} processing.

:f Data/Enumerator/IO.hs
|Data.Enumerator.IO module header|
module Data.Enumerator.IO
	{-# DEPRECATED "Use 'Data.Enumerator.Binary' instead" #-}
	( enumHandle
	, enumFile
	, iterHandle
	) where
import qualified Data.Enumerator as E
import qualified Data.Enumerator.Binary as EB
import Control.Monad.IO.Class (MonadIO)
import qualified Data.ByteString as B
import qualified System.IO as IO

{-# DEPRECATED enumHandle "Use 'Data.Enumerator.Binary.enumHandle' instead" #-}
|apidoc Data.Enumerator.IO.enumHandle|
enumHandle :: MonadIO m
           => Integer
           -> IO.Handle
           -> E.Enumerator B.ByteString m b
enumHandle = EB.enumHandle

{-# DEPRECATED enumFile "Use 'Data.Enumerator.Binary.enumFile' instead" #-}
|apidoc Data.Enumerator.IO.enumFile|
enumFile :: FilePath -> E.Enumerator B.ByteString IO b
enumFile = EB.enumFile

{-# DEPRECATED iterHandle "Use 'Data.Enumerator.Binary.iterHandle' instead" #-}
|apidoc Data.Enumerator.IO.iterHandle|
iterHandle :: MonadIO m => IO.Handle
           -> E.Iteratee B.ByteString m ()
iterHandle = EB.iterHandle
: