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


-- | Translate pull-based stream folds into push-based iteratees.
--   
--   Translate pull-based folds from the "streaming" package into
--   push-based folds from the "foldl" package.
@package streaming-eversion
@version 0.1.0.0


-- | The pull-to-push transformations in this module require functions that
--   are polymorphic over a monad transformer.
--   
--   Because of this, some of the type signatures look scary, but actually
--   many (suitably polymorphic) operations on <a>Stream</a>s will unify
--   with them.
--   
--   To get "interruptible" operations that can exit early with an error,
--   put a <a>ExceptT</a> transformer just below the polymorphic monad
--   transformer. See <a>foldE</a>.
--   
--   Inspired by
--   <a>http://pchiusano.blogspot.com.es/2011/12/programmatic-translation-to-iteratees.html</a>
module Streaming.Eversion

-- | A stream-consuming function that can be turned into a pure, push-based
--   fold.
data Evertible a x
evertible :: (forall m r. Monad m => Stream (Of a) m r -> m (Of x r)) -> Evertible a x
evert :: Evertible a x -> Fold a x

-- | Like <a>Evertible</a>, but gives the stream-consuming function access
--   to a base monad.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let f stream = fmap ((:&gt;) ()) (lift (putStrLn "x") &gt;&gt; S.effects stream)
--       in  L.foldM (evertM (evertibleM f)) ["a","b","c"]
--       :}
--   x
--   </pre>
--   
--   Note however that control operations can't be lifted through the
--   transformer.
data EvertibleM m a x
evertibleM :: (forall t r. (MonadTrans t, Monad (t m)) => Stream (Of a) (t m) r -> t m (Of x r)) -> EvertibleM m a x
evertM :: Monad m => EvertibleM m a x -> FoldM m a x

-- | Like <a>EvertibleM</a>, but gives the stream-consuming function the
--   ability to use <a>liftIO</a>.
--   
--   <pre>
--   &gt;&gt;&gt; L.foldM (evertMIO (evertibleMIO (\stream -&gt; fmap ((:&gt;) ()) (S.print stream)))) ["a","b","c"]
--   "a"
--   "b"
--   "c"
--   </pre>
data EvertibleMIO m a x
evertibleMIO :: (forall t r. (MonadTrans t, MonadIO (t m)) => Stream (Of a) (t m) r -> t m (Of x r)) -> EvertibleMIO m a x
evertMIO :: MonadIO m => EvertibleMIO m a x -> FoldM m a x

-- | A stream-transforming function that can be turned into
--   fold-transforming function.
data Transvertible a b
transvertible :: (forall m r. Monad m => Stream (Of a) m r -> Stream (Of b) m r) -> Transvertible a b
transvert :: Transvertible b a -> (forall x. Fold a x -> Fold b x)

-- | Like <a>Transvertible</a>, but gives the stream-transforming function
--   access to a base monad.
--   
--   Note however that control operations can't be lifted through the
--   transformer.
data TransvertibleM m a b
transvertibleM :: (forall t r. (MonadTrans t, Monad (t m)) => Stream (Of a) (t m) r -> Stream (Of b) (t m) r) -> TransvertibleM m a b
transvertM :: Monad m => TransvertibleM m b a -> (forall x. FoldM m a x -> FoldM m b x)

-- | Like <a>TransvertibleM</a>, but gives the stream-consuming function
--   the ability to use <a>liftIO</a>.
data TransvertibleMIO m a b
transvertibleMIO :: (forall t r. (MonadTrans t, MonadIO (t m)) => Stream (Of a) (t m) r -> Stream (Of b) (t m) r) -> TransvertibleMIO m a b
transvertMIO :: (MonadIO m) => TransvertibleMIO m b a -> (forall x. FoldM m a x -> FoldM m b x)

-- | If your stream-folding computation can fail early returning a
--   <a>Left</a>, compose it with this function before passing it to
--   <a>evertibleM</a>.
--   
--   The result will be an <a>EvertibleM</a> that works on <a>ExceptT</a>.
--   
--   <pre>
--   &gt;&gt;&gt; runExceptT $ L.foldM (evertM (evertibleM (foldE . (\_ -&gt; return (Left ()))))) [1..10]
--   Left ()
--   </pre>
foldE :: (MonadTrans t, Monad m, Monad (t (ExceptT e m))) => t (ExceptT e m) (Either e r) -> t (ExceptT e m) r
instance GHC.Base.Functor (Streaming.Eversion.Evertible a)
instance Data.Profunctor.Unsafe.Profunctor Streaming.Eversion.Evertible
instance GHC.Base.Functor (Streaming.Eversion.EvertibleM m a)
instance Data.Profunctor.Unsafe.Profunctor (Streaming.Eversion.EvertibleM m)
instance GHC.Base.Functor (Streaming.Eversion.EvertibleMIO m a)
instance Data.Profunctor.Unsafe.Profunctor (Streaming.Eversion.EvertibleMIO m)
instance GHC.Base.Functor (Streaming.Eversion.Transvertible a)
instance Data.Profunctor.Unsafe.Profunctor Streaming.Eversion.Transvertible
instance GHC.Base.Functor (Streaming.Eversion.TransvertibleM m a)
instance Data.Profunctor.Unsafe.Profunctor (Streaming.Eversion.TransvertibleM m)
instance GHC.Base.Functor (Streaming.Eversion.TransvertibleMIO m a)
instance Data.Profunctor.Unsafe.Profunctor (Streaming.Eversion.TransvertibleMIO m)


-- | Like <a>Streaming.Eversion</a>, but for Producer folds and
--   transformations.
module Streaming.Eversion.Pipes
pipeEvertible :: (forall m r. Monad m => Producer a m r -> m (x, r)) -> Evertible a x
evert :: Evertible a x -> Fold a x
pipeEvertibleM :: (forall t r. (MonadTrans t, Monad (t m)) => Producer a (t m) r -> t m (x, r)) -> EvertibleM m a x
evertM :: Monad m => EvertibleM m a x -> FoldM m a x
pipeEvertibleMIO :: (forall t r. (MonadTrans t, MonadIO (t m)) => Producer a (t m) r -> t m (x, r)) -> EvertibleMIO m a x
evertMIO :: MonadIO m => EvertibleMIO m a x -> FoldM m a x
pipeTransvertible :: (forall m r. Monad m => Producer a m r -> Producer b m r) -> Transvertible a b
transvert :: Transvertible b a -> (forall x. Fold a x -> Fold b x)
pipeTransvertibleM :: (forall t r. (MonadTrans t, Monad (t m)) => Producer a (t m) r -> Producer b (t m) r) -> TransvertibleM m a b
transvertM :: Monad m => TransvertibleM m b a -> (forall x. FoldM m a x -> FoldM m b x)
pipeTransvertibleMIO :: (forall t r. (MonadTrans t, MonadIO (t m)) => Producer a (t m) r -> Producer b (t m) r) -> TransvertibleMIO m a b
transvertMIO :: (MonadIO m) => TransvertibleMIO m b a -> (forall x. FoldM m a x -> FoldM m b x)

-- | Allows you to plug any of the "non-lens decoding functions" from
--   <a>Pipes.Text.Encoding</a> into <a>pipeTransvertibleM</a>. Just
--   compose the decoder with this function before passing it to
--   <a>pipeTransvertibleM</a>.
--   
--   The result will be a <a>TransvertibleM</a> that works in
--   <a>ExceptT</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let adapted = transvertM (pipeTransvertibleM (pipeLeftoversE . TE.decodeUtf8)) (L.generalize L.mconcat) 
--       in  runExceptT $ L.foldM adapted ["decode","this"]
--       :}
--   Right "decodethis"
--   </pre>
--   
--   If any undecodable bytes are found, the computation halts with the
--   undecoded bytes as the error.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let adapted = transvertM (pipeTransvertibleM (pipeLeftoversE . TE.decodeUtf8)) (L.generalize L.mconcat) 
--       in  runExceptT $ L.foldM adapted ["invalid \xc3\x28","sequence"]
--       :}
--   Left "\195("
--   </pre>
pipeLeftoversE :: (MonadTrans t, Monad m, Monad (t (ExceptT bytes m))) => Producer text (t (ExceptT bytes m)) (Producer bytes (t (ExceptT bytes m)) r) -> Producer text (t (ExceptT bytes m)) r

-- | If your producer-transforming computation can fail early returning a
--   <a>Left</a>, compose it with this function before passing it to
--   <a>transvertibleM</a>.
--   
--   The result will be an <a>TransvertibleM</a> that works on
--   <a>ExceptT</a>.
pipeTransE :: (MonadTrans t, Monad m, Monad (t (ExceptT e m))) => Producer a (t (ExceptT e m)) (Either e r) -> Producer a (t (ExceptT e m)) r