Streaming.Prelude

This module is very closely modeled on Pipes.Prelude

Types

data Stream f m r

Instances

Functor f => MFunctor (Stream f)

Functor f => MMonad (Stream f)

Functor f => MonadTrans (Stream f)

(Functor f, Monad m) => Monad (Stream f m)

(Functor f, Monad m) => Functor (Stream f m)

(Functor f, Monad m) => Applicative (Stream f m)

(MonadIO m, Functor f) => MonadIO (Stream f m)

(Eq r, Eq (m (Stream f m r)), Eq (f (Stream f m r))) => Eq (Stream f m r)

(Typeable (* -> *) f, Typeable (* -> *) m, Data r, Data (m (Stream f m r)), Data (f (Stream f m r))) => Data (Stream f m r)

(Show r, Show (m (Stream f m r)), Show (f (Stream f m r))) => Show (Stream f m r)

data Of a b

A left-strict pair; the base functor for streams of individual elements.

Constructors

!a :> b infixr 4

Instances

Functor (Of a)

Foldable (Of a)

Traversable (Of a)

(Eq a, Eq b) => Eq (Of a b)

(Data a, Data b) => Data (Of a b)

(Ord a, Ord b) => Ord (Of a b)

(Read a, Read b) => Read (Of a b)

(Show a, Show b) => Show (Of a b)

lazily :: Of a b -> (a, b)

strictly :: (a, b) -> Of a b

Introducing streams of elements

each :: (Monad m, Foldable f) => f a -> Stream (Of a) m ()

Stream the elements of a foldable container.

>>> S.print $ S.each [1..3]
1
2
3

yield :: Monad m => a -> Stream (Of a) m ()

A singleton stream

unfoldr :: Monad m => (s -> m (Either r (a, s))) -> s -> Stream (Of a) m r

Build a Stream by unfolding steps starting from a seed. This is one natural way to consume a Producer. The more general unfold would require dealing with the left-strict pair we are using.

unfoldr Pipes.next :: Monad m => Producer a m r -> Stream (Of a) m r
unfold (curry (:>) . Pipes.next) :: Monad m => Producer a m r -> Stream (Of a) m r

stdinLn :: MonadIO m => Stream (Of String) m ()

repeatedly stream lines as String from stdin

readLn :: (MonadIO m, Read a) => Stream (Of a) m ()

read values from stdin, ignoring failed parses

fromHandle :: MonadIO m => Handle -> Stream (Of String) m ()

Read Strings from a Handle using hGetLine

Terminates on end of input

repeatM :: Monad m => m a -> Stream (Of a) m r

replicateM :: Monad m => Int -> m a -> Stream (Of a) m ()

Repeat an action several times, streaming the results.

Consuming streams of elements

stdoutLn :: MonadIO m => Stream (Of String) m () -> m ()

Write Strings to stdout using putStrLn

Unlike toHandle, stdoutLn gracefully terminates on a broken output pipe

stdoutLn' :: MonadIO m => Stream (Of String) m r -> m r

Write Strings to stdout using putStrLn

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

mapM_ :: Monad m => (a -> m b) -> Stream (Of a) m r -> m r

Reduce a stream to its return value with a monadic action.

>>> mapM_ Prelude.print $ each [1..3] >> return True
1
2
3
True

print :: (MonadIO m, Show a) => Stream (Of a) m r -> m r

toHandle :: MonadIO m => Handle -> Stream (Of String) m r -> m r

drain :: Monad m => Stream (Of a) m r -> m r

Reduce a stream, performing its actions but ignoring its elements.

Stream transformers

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

Standard map on the elements of a stream.

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

Replace each element of a stream with the result of a monadic action

maps' :: (Monad m, Functor f) => (forall x. f x -> m (a, x)) -> Stream f m r -> Stream (Of a) m r

Map free layers of a functor to a corresponding stream of individual elements. This simplifies the use of folds marked with a ''' in Streaming.Prelude

maps' sum' :: (Monad m, Num a) => Stream (Stream (Of a) m) m r -> Stream (Of a) m r
maps' (Pipes.fold' (+) (0::Int) id) :: Monad m => Stream (Producer Int m) m r -> Stream (Of Int) m r

maps :: (Monad m, Functor f) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r

Map layers of one functor to another with a natural transformation

sequence :: Monad m => Stream (Of (m a)) m r -> Stream (Of a) m r

Like the sequence but streaming. The result type is a stream of a's, but is not accumulated; the effects of the elements of the original stream are interleaved in the resulting stream. Compare:

sequence :: Monad m =>       [m a]           -> m [a]
sequence :: Monad m => Stream (Of (m a)) m r -> Stream (Of a) m r

mapFoldable :: (Monad m, Foldable t) => (a -> t b) -> Stream (Of a) m r -> Stream (Of b) m r

For each element of a stream, stream a foldable container of elements instead

>>> D.print $ D.mapFoldable show $ D.yield 12
'1'
'2'

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

Skip elements of a stream that fail a predicate

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

Skip elements of a stream that fail a monadic test

for :: (Monad m, Functor f) => Stream (Of a) m r -> (a -> Stream f m x) -> Stream f m r

for replaces each element of a stream with an associated stream. Note that the associated stream may layer any functor.

take :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m ()

End stream after n elements; the original return value is lost. splitAt preserves this information. Note the function is functor-general.

takeWhile :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m ()

End stream when an element fails a condition; the original return value is lost span preserves this information.

drop :: Monad m => Int -> Stream (Of a) m r -> Stream (Of a) m r

Ignore the first n elements of a stream, but carry out the actions

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

Ignore elements of a stream until a test succeeds.

concat :: (Monad m, Foldable f) => Stream (Of (f a)) m r -> Stream (Of a) m r

Make a stream of traversable containers into a stream of their separate elements

>>> Streaming.print $ concat (each ["hi","ho"])
'h'
'i'
'h'
'o'

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

Strict left scan, streaming, e.g. successive partial results.

Control.Foldl.purely scan :: Monad m => Fold a b -> Stream (Of a) m r -> Stream (Of b) m r

>>> Streaming.print $ Foldl.purely Streaming.scan Foldl.list $ each [3..5]
[]
[3]
[3,4]
[3,4,5]

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

Strict, monadic left scan

Control.Foldl.impurely scanM :: Monad m => FoldM a m b -> Stream (Of a) m r -> Stream (Of b) m r

chain :: Monad m => (a -> m ()) -> Stream (Of a) m r -> Stream (Of a) m r

Apply an action to all values flowing downstream

>>> let debug str = chain print str
>>> S.product (debug (S.each [2..4])) >>= print
2
3
4
24

read :: (Monad m, Read a) => Stream (Of String) m r -> Stream (Of a) m r

Make a stream of strings into a stream of parsed values, skipping bad cases

show :: (Monad m, Show a) => Stream (Of a) m r -> Stream (Of String) m r

seq :: Monad m => Stream (Of a) m r -> Stream (Of a) m r

Evaluate all values flowing downstream to WHNF

Splitting and inspecting streams of elements

next :: Monad m => Stream (Of a) m r -> m (Either r (a, Stream (Of a) m r))

The standard way of inspecting the first item in a stream of elements, if the stream is still 'running'. The Right case contains a Haskell pair, where the more general inspect would return a left-strict pair. There is no reason to prefer inspect since, if the Right case is exposed, the first element in the pair will have been evaluated to whnf.

next :: Monad m => Stream (Of a) m r -> m (Either r (a, Stream (Of a) m r))
inspect :: Monad m => Stream (Of a) m r -> m (Either r (Of a (Stream (Of a) m r)))

Interoperate with pipes producers thus:

Pipes.unfoldr Stream.next :: Stream (Of a) m r -> Producer a m r
Stream.unfoldr Pipes.next :: Producer a m r -> Stream (Of a) m r 

Similarly:

IOStreams.unfoldM (liftM (either (const Nothing) Just) . next) :: Stream (Of a) IO b -> IO (InputStream a)
Conduit.unfoldM (liftM (either (const Nothing) Just) . next)   :: Stream (Of a) m r -> Source a m r

But see uncons

uncons :: Monad m => Stream (Of a) m () -> m (Maybe (a, Stream (Of a) m ()))

Inspect the first item in a stream of elements, without a return value. Useful for unfolding into another streaming type.

IOStreams.unfoldM uncons :: Stream (Of a) IO b -> IO (InputStream a)
Conduit.unfoldM uncons   :: Stream (Of o) m r -> Conduit.Source m o

split :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Stream f m r)

Split a succession of layers after some number, returning a streaming or effectful pair.

break :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m (Stream (Of a) m r)

span :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m (Stream (Of a) m r)

Stream elements until one fails the condition, return the rest.

Folds

Use these to fold the elements of a Stream. The general folds fold, fold'', foldM and 'foldM\'' are arranged for use with Foldl All functions marked with a final '\'' (e.g. 'fold\'', 'sum\') carry the stream's return value -- or, in the case of 'maps\'' are tailored to take such an operation as argument.

 maps' sum' :: (Monad m, Num n) => Stream (Stream (Of n)) m r -> Stream (Of n) m r
 maps' (fold' mappend mempty id) :: :: (Monad m, Num n) => Stream (Stream (Of n)) m r -> Stream (Of n) m r

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

Strict fold of a Stream of elements

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

fold' :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Stream (Of a) m r -> m (b, r)

Strict fold of a Stream of elements that preserves the return value

Control.Foldl.purely fold' :: Monad m => Fold a b -> Stream (Of a) m r -> m (b, r)

foldM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Stream (Of a) m () -> m b

Strict, monadic fold of the elements of a 'Stream (Of a)'

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

foldM' :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Stream (Of a) m r -> m (b, r)

Strict, monadic fold of the elements of a 'Stream (Of a)'

Control.Foldl.impurely foldM' :: Monad m => FoldM a b -> Stream (Of a) m r -> m (b, r)

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

Fold a Stream of numbers into their sum

sum' :: (Monad m, Num a) => Stream (Of a) m r -> m (a, r)

Fold a Stream of numbers into their sum with the return value

 mapsFold sum' :: Stream (Stream (Of Int)) m r -> Stream (Of Int) m r

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

Fold a Stream of numbers into their product

product' :: (Monad m, Num a) => Stream (Of a) m r -> m (a, r)

Fold a Stream of numbers into their product with the return value

 mapsFold product' :: Stream (Stream (Of Int)) m r -> Stream (Of Int) m r

toList :: Stream (Of a) Identity () -> [a]

Convert a pure 'Stream (Of a) into a list of a

toListM :: Monad m => Stream (Of a) m () -> m [a]

Convert an effectful 'Stream (Of a)' into a list of a

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.

toListM' :: Monad m => Stream (Of a) m r -> m ([a], r)

Convert an effectful Stream into a list alongside the return value

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

 mapsFold toListM' :: Stream (Stream (Of a)) m r -> Stream (Of [a]) m 

foldrM :: Monad m => (a -> m r -> m r) -> Stream (Of a) m r -> m r

A natural right fold for consuming a stream of elements. See also the more general iterT in the Streaming module and the still more general destroy

foldrT :: (Monad m, MonadTrans t, Monad (t m)) => (a -> t m r -> t m r) -> Stream (Of a) m r -> t m r

A natural right fold for consuming a stream of elements. See also the more general iterTM in the Streaming module and the still more general destroy

foldrT (\a p -> Pipes.yield a >> p) :: Monad m => Stream (Of a) m r -> Producer a m r
foldrT (\a p -> Conduit.yield a >> p) :: Monad m => Stream (Of a) m r -> Conduit a m r

Short circuiting folds

Zips

zip :: Monad m => Stream (Of a) m r -> Stream (Of b) m r -> Stream (Of (a, b)) m r

Zip two Streamss

zipWith :: Monad m => (a -> b -> c) -> Stream (Of a) m r -> Stream (Of b) m r -> Stream (Of c) m r

Zip two Streamss using the provided combining function