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.

Producers

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:

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

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

Read Strings from stdin using getLine

Terminates on end of input

readLn :: MonadIO m => Read a => Producer' a m ()

read values from stdin, ignoring failed parses

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

Read Strings from a Handle using hGetLine

Terminates on end of input

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

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

Consumers

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

>>> runEffect $ lift getLine >~ P.stdoutLn
Test<Enter>
Test
ABC<Enter>
ABC
...

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

Write Strings to stdout using putStrLn

Unlike toHandle, stdoutLn gracefully terminates on a broken output pipe

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

print values to stdout

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

Write Strings to a Handle using hPutStrLn

Pipes

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

>>> runEffect $ P.stdinLn >-> P.takeWhile (/= "quit") >-> P.stdoutLn
Test<Enter>
Test
ABC<Enter>
ABC
quit<Enter>
>>> 

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

Apply a function to all values flowing downstream

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

Apply a monadic function to all values flowing downstream

mapFoldable :: (Monad 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.

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

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

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

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

take :: Monad m => Int -> Pipe a a m ()

(take n) only allows n values to pass through

takeWhile :: Monad m => (a -> Bool) -> Pipe a a m ()

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

drop :: Monad m => Int -> Pipe a a m r

(drop n) discards n values going downstream

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

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

concat :: (Monad m, Foldable f) => Pipe (f a) a m r

Flatten all Foldable elements flowing downstream

elemIndices :: (Monad m, Eq a) => a -> Pipe a Int m r

Outputs the indices of all elements that match the given element

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

Outputs the indices of all elements that satisfied the predicate

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

Strict left scan

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

Strict, monadic left scan

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

Apply an action to all values flowing downstream

read :: (Monad m, Read a) => Pipe String a m r

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

show :: (Monad m, Show a) => Pipe a String m r

Convert Showable values to Strings

Folds

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:

>>> P.any null P.stdinLn
Test<Enter>
ABC<Enter>
<Enter>
True
>>> 

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

Strict fold of the elements of a Producer

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

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

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

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

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

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

Determines whether all elements are True

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

Determines whether any element is True

elem :: (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

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

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

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

Find the first element of a Producer that satisfies the predicate

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

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

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

Retrieve the first element from a Producer

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

Index into a Producer

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

Retrieve the last element from a Producer

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

Count the number of elements in a Producer

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

Find the maximum element of a Producer

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

Find the minimum element of a Producer

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

Determine if a Producer is empty

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

Compute the sum of the elements of a Producer

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

Compute the product of the elements of a Producer

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

Convert a pure Producer into a list

toListM :: 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.

Zips

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

Zip two Producers

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

Zip two Producers using the provided combining function

Utilities

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

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

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