Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Add documentation for PutbackPipe.

  • Loading branch information...
commit 907d8ed88c476b1381922e4eb2e777d1d9a9f453 1 parent 3f17c2b
@pcapriotti authored
Showing with 16 additions and 0 deletions.
  1. +16 −0 pipes-extra/Control/Pipe/PutbackPipe.hs
View
16 pipes-extra/Control/Pipe/PutbackPipe.hs
@@ -1,3 +1,12 @@
+-- | This module contains an alternative pipe implementation, 'PutbackPipe',
+-- providing an additional primitive 'putback', which allows data to be
+-- inserted into the input stream of the current pipe.
+--
+-- PutbackPipes can be used to implement pipes with left-over data, and can be
+-- composed vertically (using the Monad instance), but not horizontally.
+--
+-- To make use of a PutbackPipe within a 'Pipeline', you need to convert it to
+-- a regular 'Pipe' using 'runPutback'.
module Control.Pipe.PutbackPipe (
fromPipe,
putback,
@@ -15,6 +24,7 @@ import Control.Pipe ((>+>), Pipe)
import qualified Control.Pipe.Combinators as PC
import Control.Pipe.Monoidal
+-- | The 'PutbackPipe' data type.
newtype PutbackPipe a b m r = PutbackPipe {
unPutback :: Pipe (Either a a) (Either b a) m r
}
@@ -36,20 +46,26 @@ instance Monad m => Applicative (PutbackPipe a b m) where
instance MonadIO m => MonadIO (PutbackPipe a b m) where
liftIO a = PutbackPipe (liftIO a)
+-- | Create a 'PutbackPipe' from a regular pipe.
fromPipe :: Monad m => Pipe a b m r -> PutbackPipe a b m r
fromPipe p = PutbackPipe (joinP >+> p >+> P.pipe Left)
+-- | Put back an element into the input stream.
putback :: Monad m => a -> PutbackPipe a b m ()
putback = PutbackPipe . P.yield . Right
+-- | Same as 'P.yield' for regular pipes.
yield :: Monad m => b -> PutbackPipe a b m ()
yield = PutbackPipe . P.yield . Left
+-- | Same as 'P.await' for regular pipes.
await :: Monad m => PutbackPipe a b m a
await = PutbackPipe $ liftM (either id id) P.await
+-- | Same as 'PC.tryAwait' for regular pipes.
tryAwait :: Monad m => PutbackPipe a b m (Maybe a)
tryAwait = PutbackPipe $ liftM (fmap (either id id)) PC.tryAwait
+-- | Convert a 'PutbackPipe' to a regular pipe.
runPutback :: Monad m => PutbackPipe a b m r -> Pipe a b m r
runPutback = loopP . unPutback
Please sign in to comment.
Something went wrong with that request. Please try again.