enumerator-0.4.5: src/compat.anansi

\section{Compatibility}

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

:d Data.Enumerator exports
-- * Compatibility
:

\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.

:f Data/Enumerator.hs
|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)
:

:f Data/Enumerator.hs
{-# 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)
:

:f Data/Enumerator.hs
|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
:

:f Data/Enumerator.hs
|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 Data.Enumerator imports
import Data.List (genericLength)
:

:f Data/Enumerator.hs
|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
:

:d Data.Enumerator exports
-- ** Obsolete functions
, liftTrans
, liftI
, peek
, Data.Enumerator.last
, Data.Enumerator.length
:

\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)
	}
:

: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]
:

:d Data.Enumerator imports
import {-# SOURCE #-} qualified Data.Enumerator.List as EL
:

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

:f Data/Enumerator.hs
{-# 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
:

:d Data.Enumerator exports
-- ** Deprecated aliases
, Data.Enumerator.head
, Data.Enumerator.drop
, Data.Enumerator.dropWhile
, Data.Enumerator.span
, Data.Enumerator.break
, Data.Enumerator.consume
:

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

:f Data/Enumerator.hs
{-# DEPRECATED liftFoldL
     "Use 'Data.Enumerator.foldl' 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.foldl' ' instead" #-}
|apidoc Data.Enumerator.liftFoldL'|
liftFoldL' :: Monad m => (b -> a -> b) -> b
           -> Iteratee a m b
liftFoldL' = Data.Enumerator.foldl'

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

:d Data.Enumerator exports
, liftFoldL
, liftFoldL'
, liftFoldM
:

\clearpage
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
: