pipes 4.1.2 → 4.1.3

raw patch · 5 files changed

+73/−7 lines, 5 filesdep ~mtlPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: mtl

API changes (from Hackage documentation)

Files

• pipes.cabal +5/−5
• src/Pipes.hs +25/−1
• src/Pipes/Core.hs +1/−1
• src/Pipes/Prelude.hs +38/−0
• src/Pipes/Tutorial.hs +4/−0

@@ -1,5 +1,5 @@ Name: pipes
-Version: 4.1.2
+Version: 4.1.3
 Cabal-Version: >= 1.10
 Build-Type: Simple
 License: BSD3
@@ -46,7 +46,7 @@         base         >= 4       && < 5  ,
         transformers >= 0.2.0.0 && < 0.5,
         mmorph       >= 1.0.0   && < 1.1,
-        mtl          >= 2.0.1.0 && < 2.3
+        mtl          >= 2.1     && < 2.3
 
     Exposed-Modules:
         Pipes,
@@ -67,7 +67,7 @@     Build-Depends:
         base      >= 4       && < 5  ,
         criterion >= 0.6.2.1 && < 0.9,
-        mtl       >= 2.0.1.0 && < 2.3,
+        mtl       >= 2.1     && < 2.3,
         pipes     >= 4.0.0   && < 4.2
 
 test-suite tests
@@ -81,7 +81,7 @@         base                       >= 4       && < 5   ,
         pipes                      >= 4.0.0   && < 4.2 ,
         QuickCheck                 >= 2.4     && < 3   ,
-        mtl                        >= 2.0.1   && < 2.3 ,
+        mtl                        >= 2.1     && < 2.3 ,
         test-framework             >= 0.4     && < 1   ,
         test-framework-quickcheck2 >= 0.2.0   && < 0.4 ,
         transformers               >= 0.2.0.0 && < 0.5
@@ -97,6 +97,6 @@         base         >= 4       && < 5  ,
         criterion    >= 0.6.2.1 && < 0.9,
         deepseq                         ,
-        mtl          >= 2.0.1.0 && < 2.3,
+        mtl          >= 2.1     && < 2.3,
         pipes        >= 4.0.0   && < 4.2,
         transformers >= 0.2.0.0 && < 0.5

@@ -57,6 +57,7 @@ 
     -- * Re-exports
     -- $reexports
+    , module Control.Monad
     , module Control.Monad.IO.Class
     , module Control.Monad.Trans.Class
     , module Control.Monad.Morph
@@ -64,6 +65,7 @@     ) where
 
 import Control.Applicative (Applicative(pure, (<*>)), Alternative(empty, (<|>)))
+import Control.Monad (void)
 import Control.Monad.Error (MonadError(..))
 import Control.Monad.IO.Class (MonadIO(liftIO))
 import Control.Monad (MonadPlus(mzero, mplus))
@@ -412,13 +414,33 @@ 
     catchError l k = Select (catchError (enumerate l) (\e -> enumerate (k e)))
 
--- | Run a self-contained `ListT` computation
+{-| Run a self-contained 'ListT' computation
+
+    Note: 'runListT` only accepts empty 'ListT's, to prevent accidentally
+    discarding values.  You can explicitly confirm that you want to discard the
+    value using 'mempty' or 'mzero':
+
+> example :: ListT m ()  -- `()` will not type-check as `X`
+>
+> main = runListT $ do
+>     example
+>     mzero  -- `mzero`'s return value will type-check as `X`
+-}
 runListT :: Monad m => ListT m X -> m ()
 runListT l = runEffect (enumerate l)
 {-# INLINABLE runListT #-}
 
 {-| 'Enumerable' generalizes 'Data.Foldable.Foldable', converting effectful
     containers to 'ListT's.
+
+    Instances of 'Enumerable' must satisfy these two laws:
+
+> toListT (return r) = return r
+>
+> toListT $ do x <- m  =  do x <- toListT m
+>              f x           toListT (f x)
+
+    In other words, 'toListT' is monad morphism.
 -}
 class Enumerable t where
     toListT :: Monad m => t m a -> ListT m a
@@ -494,6 +516,8 @@ {-# INLINABLE (<-<) #-}
 
 {- $reexports
+    "Control.Monad" re-exports 'void'
+
     "Control.Monad.IO.Class" re-exports 'MonadIO'.
 
     "Control.Monad.Trans.Class" re-exports 'MonadTrans'.

@@ -237,7 +237,7 @@ ('/>/') :: 'Monad' m
       => (a -> 'Proxy' x' x b' b m a')
       -> (b -> 'Proxy' x' x c' c m b')
-      -> (a -> 'Proxy' x' x b' b m a')
+      -> (a -> 'Proxy' x' x c' c m a')
 
 \          a                   /===> b                      a
           |                  /      |                      |

@@ -59,7 +59,9 @@     -- * Folds
     -- $folds
     , fold
+    , fold'
     , foldM
+    , foldM'
     , all
     , any
     , and
@@ -557,6 +559,20 @@         Pure    _     -> return (done x)
 {-# INLINABLE fold #-}
 
+{-| Strict fold of the elements of a 'Producer' that preserves the return value
+
+> Control.Foldl.purely fold' :: Monad m => Fold a b -> Producer a m r -> m (b, r)
+-}
+fold' :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Producer a m r -> m (b, r)
+fold' step begin done p0 = loop p0 begin
+  where
+    loop p x = case p of
+        Request v  _  -> closed v
+        Respond a  fu -> loop (fu ()) $! step x a
+        M          m  -> m >>= \p' -> loop p' x
+        Pure    r     -> return (done x, r)
+{-# INLINABLE fold' #-}
+
 {-| Strict, monadic fold of the elements of a 'Producer'
 
 > Control.Foldl.impurely foldM :: Monad m => FoldM a b -> Producer a m () -> m b
@@ -576,6 +592,28 @@         M          m  -> m >>= \p' -> loop p' x
         Pure    _     -> done x
 {-# INLINABLE foldM #-}
+
+{-| Strict, monadic fold of the elements of a 'Producer'
+
+> Control.Foldl.impurely foldM' :: Monad m => FoldM a b -> Producer a m r -> m (b, r)
+-}
+foldM'
+    :: Monad m
+    => (x -> a -> m x) -> m x -> (x -> m b) -> Producer a m r -> m (b, r)
+foldM' step begin done p0 = do
+    x0 <- begin
+    loop p0 x0
+  where
+    loop p x = case p of
+        Request v  _  -> closed v
+        Respond a  fu -> do
+            x' <- step x a
+            loop (fu ()) $! x'
+        M          m  -> m >>= \p' -> loop p' x
+        Pure    r     -> do
+            b <- done x
+            return (b, r)
+{-# INLINABLE foldM' #-}
 
 {-| @(all predicate p)@ determines whether all the elements of @p@ satisfy the
     predicate.

@@ -1076,11 +1076,15 @@ 
     * @pipes-safe@: Resource management and exception safety for @pipes@
 
+    * @pipes-group@: Grouping streams in constant space
+
     These libraries provide functionality specialized to common streaming
     domains.  Additionally, there are several libraries on Hackage that provide
     even higher-level functionality, which you can find by searching under the
     \"Pipes\" category or by looking for packages with a @pipes-@ prefix in
     their name.  Current examples include:
+
+    * @pipes-extras@: Miscellaneous utilities
 
     * @pipes-network@/@pipes-network-tls@: Networking