Modulepipes-4.3.16Haskell2010

Pipes.Prelude

General purpose utilities

The names in this module clash heavily with the Haskell Prelude, so I recommend the following import scheme:

import Pipes
import qualified Pipes.Prelude as P  -- or use any other qualifier you prefer

Note that String-based IO is inefficient. The String-based utilities in this module exist only for simple demonstrations without incurring a dependency on the text package.

Also, stdinLn and stdoutLn remove and add newlines, respectively. This behavior is intended to simplify examples. The corresponding stdin and stdout utilities from pipes-bytestring and pipes-text preserve newlines.

63 values

Packagepipes-4.3.16
Exports63
LanguageHaskell2010
LicenceBSD-3-Clause
SourcePrelude.hs

Producers

6 declarations

Use for loops to iterate over Producers whenever you want to perform the same action for every element:

-- Echo all lines from standard input to standard output
runEffect $ for P.stdinLn $ \str -> do
    lift $ putStrLn str

... or more concisely:

Example1 expression

>>> runEffect $ for P.stdinLn (lift . putStrLn)Test<Enter>TestABC<Enter>ABC...

valuestdinLn :: MonadIO m => Producer' String m ()

Read Strings from stdin using getLine

Terminates on end of input

valuereadLn :: (MonadIO m, Read a) => Producer' a m ()

read values from stdin, ignoring failed parses

valuefromHandle :: MonadIO m => Handle -> Proxy x' x () String m ()

Read Strings from a Handle using hGetLine

Terminates on end of input

fromHandle :: MonadIO m => Handle -> Producer String m ()

valuerepeatM :: Monad m => m a -> Proxy x' x () a m r

Repeat a monadic action indefinitely, yielding each result

repeatM :: Monad m => m a -> Producer a m r

valuereplicateM :: Monad m => Int -> m a -> Proxy x' x () a m ()

Repeat a monadic action a fixed number of times, yielding each result

replicateM  0      x = return ()

replicateM (m + n) x = replicateM m x >> replicateM n x  -- 0 <= {m,n}

replicateM :: Monad m => Int -> m a -> Producer a m ()

valueunfoldr :: Monad m => (s -> m (Either r (a, s))) -> s -> Producer a m r

The natural unfold into a Producer with a step function and a seed

unfoldr next = id

Consumers

6 declarations

Feed a Consumer the same value repeatedly using (>~):

Example1 expression

>>> runEffect $ lift getLine >~ P.stdoutLnTest<Enter>TestABC<Enter>ABC...

valuestdoutLn :: MonadIO m => Consumer' String m ()

Write Strings to stdout using putStrLn

Unlike toHandle, stdoutLn gracefully terminates on a broken output pipe

valuestdoutLn' :: MonadIO m => Consumer' String m r

Write Strings to stdout using putStrLn

This does not handle a broken output pipe, but has a polymorphic return value

valuemapM_ :: Monad m => (a -> m ()) -> Consumer' a m r

Consume all values using a monadic function

valueprint :: (MonadIO m, Show a) => Consumer' a m r

print values to stdout

valuetoHandle :: MonadIO m => Handle -> Consumer' String m r

Write Strings to a Handle using hPutStrLn

valuedrain :: Functor m => Consumer' a m r

discard all incoming values

Pipes

22 declarations

Use (>->) to connect Producers, Pipes, and Consumers:

Example2 expressions

>>> runEffect $ P.stdinLn >-> P.takeWhile (/= "quit") >-> P.stdoutLnTest<Enter>TestABC<Enter>ABCquit<Enter>>>>

valuemap :: Functor m => (a -> b) -> Pipe a b m r

Apply a function to all values flowing downstream

map id = cat

map (g . f) = map f >-> map g

valuemapM :: Monad m => (a -> m b) -> Pipe a b m r

Apply a monadic function to all values flowing downstream

mapM return = cat

mapM (f >=> g) = mapM f >-> mapM g

valuesequence :: Monad m => Pipe (m a) a m r

Convert a stream of actions to a stream of values

valuemapFoldable :: (Functor m, Foldable t) => (a -> t b) -> Pipe a b m r

Apply a function to all values flowing downstream, and forward each element of the result.

valuefilter :: Functor m => (a -> Bool) -> Pipe a a m r

(filter predicate) only forwards values that satisfy the predicate.

filter (pure True) = cat

filter (liftA2 (&&) p1 p2) = filter p1 >-> filter p2

filter f = mapMaybe (\a -> a <$ guard (f a))

valuemapMaybe :: Functor m => (a -> Maybe b) -> Pipe a b m r

(mapMaybe f) yields Just results of f.

Basic laws:

mapMaybe (f >=> g) = mapMaybe f >-> mapMaybe g

mapMaybe (pure @Maybe . f) = mapMaybe (Just . f) = map f

mapMaybe (const Nothing) = drain

As a result of the second law,

mapMaybe return = mapMaybe Just = cat

valuefilterM :: Monad m => (a -> m Bool) -> Pipe a a m r

(filterM predicate) only forwards values that satisfy the monadic predicate

filterM (pure (pure True)) = cat

filterM (liftA2 (liftA2 (&&)) p1 p2) = filterM p1 >-> filterM p2

filterM f = wither (\a -> (\b -> a <$ guard b) <$> f a)

valuewither :: Monad m => (a -> m (Maybe b)) -> Pipe a b m r

(wither f) forwards Just values produced by the monadic action.

Basic laws:

wither (runMaybeT . (MaybeT . f >=> MaybeT . g)) = wither f >-> wither g

wither (runMaybeT . lift . f) = wither (fmap Just . f) = mapM f

wither (pure . f) = mapMaybe f

As a result of the second law,

wither (runMaybeT . return) = cat

As a result of the third law,

wither (pure . const Nothing) = wither (const (pure Nothing)) = drain

valuetake :: Functor m => Int -> Pipe a a m ()

(take n) only allows n values to pass through

take 0 = return ()

take (m + n) = take m >> take n

take <infinity> = cat

take (min m n) = take m >-> take n

valuetakeWhile :: Functor m => (a -> Bool) -> Pipe a a m ()

(takeWhile p) allows values to pass downstream so long as they satisfy the predicate p.

takeWhile (pure True) = cat

takeWhile (liftA2 (&&) p1 p2) = takeWhile p1 >-> takeWhile p2

valuetakeWhile' :: Functor m => (a -> Bool) -> Pipe a a m a

(takeWhile' p) is a version of takeWhile that returns the value failing the predicate.

takeWhile' (pure True) = cat

takeWhile' (liftA2 (&&) p1 p2) = takeWhile' p1 >-> takeWhile' p2

valuedrop :: Functor m => Int -> Pipe a a m r

(drop n) discards n values going downstream

drop 0 = cat

drop (m + n) = drop m >-> drop n

valuedropWhile :: Functor m => (a -> Bool) -> Pipe a a m r

(dropWhile p) discards values going downstream until one violates the predicate p.

dropWhile (pure False) = cat

dropWhile (liftA2 (||) p1 p2) = dropWhile p1 >-> dropWhile p2

valueconcat :: (Functor m, Foldable f) => Pipe (f a) a m r

Flatten all Foldable elements flowing downstream

valueelemIndices :: (Functor m, Eq a) => a -> Pipe a Int m r

Outputs the indices of all elements that match the given element

valuefindIndices :: Functor m => (a -> Bool) -> Pipe a Int m r

Outputs the indices of all elements that satisfied the predicate

valuescan :: Functor m => (x -> a -> x) -> x -> (x -> b) -> Pipe a b m r

Strict left scan

Control.Foldl.purely scan :: Monad m => Fold a b -> Pipe a b m r

valuescanM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Pipe a b m r

Strict, monadic left scan

Control.Foldl.impurely scanM :: Monad m => FoldM m a b -> Pipe a b m r

valuechain :: Monad m => (a -> m ()) -> Pipe a a m r

Apply an action to all values flowing downstream

chain (pure (return ())) = cat

chain (liftA2 (>>) m1 m2) = chain m1 >-> chain m2

valueread :: (Functor m, Read a) => Pipe String a m r

Parse Readable values, only forwarding the value if the parse succeeds

valueshow :: (Functor m, Show a) => Pipe a String m r

Convert Showable values to Strings

valueseq :: Functor m => Pipe a a m r

Evaluate all values flowing downstream to WHNF

ListT

1 declaration

valueloop :: Monad m => (a -> ListT m b) -> Pipe a b m r

Create a Pipe from a ListT transformation

loop (k1 >=> k2) = loop k1 >-> loop k2

loop return = cat

Folds

24 declarations

Use these to fold the output of a Producer. Many of these folds will stop drawing elements if they can compute their result early, like any:

Example2 expressions

>>> P.any Prelude.null P.stdinLnTest<Enter>ABC<Enter><Enter>True>>>

valuefold :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Producer a m () -> m b

Strict fold of the elements of a Producer

Control.Foldl.purely fold :: Monad m => Fold a b -> Producer a m () -> m b

valuefold'

:: Monad m
=> x -> a -> x
-> x
-> x -> b
-> Producer a m r
-> m (b, r)

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)

valuefoldM

:: Monad m
=> x -> a -> m x
-> m x
-> x -> m b
-> Producer a m ()
-> m b

Strict, monadic fold of the elements of a Producer

Control.Foldl.impurely foldM :: Monad m => FoldM a b -> Producer a m () -> m b

valuefoldM'

:: Monad m
=> x -> a -> m x
-> m x
-> x -> m b
-> Producer a m r
-> m (b, r)

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)

valueall :: Monad m => (a -> Bool) -> Producer a m () -> m Bool

(all predicate p) determines whether all the elements of p satisfy the predicate.

valueany :: Monad m => (a -> Bool) -> Producer a m () -> m Bool

(any predicate p) determines whether any element of p satisfies the predicate.

valueand :: Monad m => Producer Bool m () -> m Bool

Determines whether all elements are True

valueor :: Monad m => Producer Bool m () -> m Bool

Determines whether any element is True

valueelem :: (Monad m, Eq a) => a -> Producer a m () -> m Bool

(elem a p) returns True if p has an element equal to a, False otherwise

valuenotElem :: (Monad m, Eq a) => a -> Producer a m () -> m Bool

(notElem a) returns False if p has an element equal to a, True otherwise

valuefind :: Monad m => (a -> Bool) -> Producer a m () -> m (Maybe a)

Find the first element of a Producer that satisfies the predicate

valuefindIndex :: Monad m => (a -> Bool) -> Producer a m () -> m (Maybe Int)

Find the index of the first element of a Producer that satisfies the predicate

valuehead :: Monad m => Producer a m () -> m (Maybe a)

Retrieve the first element from a Producer

valueindex :: Monad m => Int -> Producer a m () -> m (Maybe a)

Index into a Producer

valuelast :: Monad m => Producer a m () -> m (Maybe a)

Retrieve the last element from a Producer

valuelength :: Monad m => Producer a m () -> m Int

Count the number of elements in a Producer

valuemaximum :: (Monad m, Ord a) => Producer a m () -> m (Maybe a)

Find the maximum element of a Producer

valueminimum :: (Monad m, Ord a) => Producer a m () -> m (Maybe a)

Find the minimum element of a Producer

valuenull :: Monad m => Producer a m () -> m Bool

Determine if a Producer is empty

valuesum :: (Monad m, Num a) => Producer a m () -> m a

Compute the sum of the elements of a Producer

valueproduct :: (Monad m, Num a) => Producer a m () -> m a

Compute the product of the elements of a Producer

valuetoList :: Producer a Identity () -> [a]

Convert a pure Producer into a list

valuetoListM :: Monad m => Producer a m () -> m [a]

Convert an effectful Producer into a list

Note: toListM is not an idiomatic use of pipes, but I provide it for simple testing purposes. Idiomatic pipes style consumes the elements immediately as they are generated instead of loading all elements into memory.

valuetoListM' :: Monad m => Producer a m r -> m ([a], r)

Convert an effectful Producer into a list alongside the return value

Note: toListM' is not an idiomatic use of pipes, but I provide it for simple testing purposes. Idiomatic pipes style consumes the elements immediately as they are generated instead of loading all elements into memory.

Zips

2 declarations

valuezip

:: Monad m
=> Producer a m r
-> Producer b m r
-> Proxy x' x () (a, b) m r

Zip two Producers

valuezipWith

:: Monad m
=> a -> b -> c
-> Producer a m r
-> Producer b m r
-> Proxy x' x () c m r

Zip two Producers using the provided combining function

Utilities

2 declarations

valuetee :: Monad m => Consumer a m r -> Pipe a a m r

Transform a Consumer to a Pipe that reforwards all values further downstream

valuegeneralize :: Monad m => Pipe a b m r -> x -> Proxy x a x b m r

Transform a unidirectional Pipe to a bidirectional Proxy

generalize (f >-> g) = generalize f >+> generalize g

generalize cat = pull