-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A free monad transformer optimized for streaming applications.
--
@package streaming
@version 0.1.0.10
module Streaming.Internal
data Stream f m r
Step :: !(f (Stream f m r)) -> Stream f m r
Delay :: (m (Stream f m r)) -> Stream f m r
Return :: r -> Stream f m r
-- | Reflect a church-encoded stream; cp. GHC.Exts.build
construct :: (forall b. (f b -> b) -> (m b -> b) -> (r -> b) -> b) -> Stream f m r
-- | Build a Stream by unfolding steps starting from a seed. See
-- also the specialized unfoldr in the prelude.
--
--
-- unfold inspect = id -- modulo the quotient we work with
-- unfold Pipes.next :: Monad m => Producer a m r -> Stream ((,) a) m r
-- unfold (curry (:>) . Pipes.next) :: Monad m => Producer a m r -> Stream (Of a) m r
--
unfold :: (Monad m, Functor f) => (s -> m (Either r (f s))) -> s -> Stream f m r
-- | Repeat a functorial layer, command or instruct several times.
replicates :: (Monad m, Functor f) => Int -> f () -> Stream f m ()
-- | Repeat a functorial layer, command or instruction forever.
repeats :: (Monad m, Functor f) => f () -> Stream f m r
repeatsM :: (Monad m, Functor f) => m (f ()) -> Stream f m r
wrap :: (Monad m, Functor f) => m (Stream f m r) -> Stream f m r
step :: (Monad m, Functor f) => f (Stream f m r) -> Stream f m r
-- | Lift for items in the base functor. Makes a singleton or one-layer
-- succession.`
layer :: (Monad m, Functor f) => f r -> Stream f m r
-- | Interpolate a layer at each segment. This specializes to e.g.
--
--
-- intercalates :: (Monad m, Functor f) => Stream f m () -> Stream (Stream f m) m r -> Stream f m r
--
intercalates :: (Monad m, Monad (t m), MonadTrans t) => t m a -> Stream (t m) m b -> t m b
-- | Dissolves the segmentation into layers of Stream f m layers.
--
--
-- concats stream = destroy stream join (join . lift) return
--
--
--
-- >>> S.print $ concats $ maps (cons 1776) $ chunksOf 2 (each [1..5])
-- 1776
-- 1
-- 2
-- 1776
-- 3
-- 4
-- 1776
-- 5
--
concats :: (Monad m, Functor f) => Stream (Stream f m) m r -> Stream f m r
-- | Specialized fold
--
--
-- iterT alg stream = destroy stream alg join return
--
iterT :: (Functor f, Monad m) => (f (m a) -> m a) -> Stream f m a -> m a
-- | Specialized fold
--
--
-- iterTM alg stream = destroy stream alg (join . lift) return
--
iterTM :: (Functor f, Monad m, MonadTrans t, Monad (t m)) => (f (t m a) -> t m a) -> Stream f m a -> t m a
-- | Map a stream directly to its church encoding; compare
-- Data.List.foldr It permits distinctions that should be
-- hidden, as can be seen from e.g.
--
-- isPure stream = destroy_ (const True) (const False) (const True)
--
-- and similar nonsense. The crucial constraint is that the m x ->
-- x argument is an Eilenberg-Moore algebra. See Atkey
-- "Reasoning about Stream Processing with Effects"
--
-- The destroy exported by the safe modules is
--
-- destroy str = destroy (observe str)
destroy :: (Functor f, Monad m) => Stream f m r -> (f b -> b) -> (m b -> b) -> (r -> b) -> b
-- | destroyWith reorders the arguments of destroy to be more
-- akin to foldr It is more convenient to query in ghci to
-- figure out what kind of 'algebra' you need to write.
--
--
-- >>> :t destroyWith join return
-- (Monad m, Functor f) =>
-- (f (m a) -> m a) -> Stream f m a -> m a -- iterT
--
-- >>> :t destroyWith (join . lift) return
-- (Monad m, Monad (t m), Functor f, MonadTrans t) =>
-- (f (t m a) -> t m a) -> Stream f m a -> t m a -- iterTM
--
-- >>> :t destroyWith wrap return
-- (Monad m, Functor f, Functor f1) =>
-- (f (Stream f1 m r) -> Stream f1 m r) -> Stream f m r -> Stream f1 m r
--
-- >>> :t destroyWith wrap return (step . lazily)
-- Monad m =>
-- Stream (Of a) m r -> Stream ((,) a) m r
--
-- >>> :t destroyWith wrap return (step . strictly)
-- Monad m =>
-- Stream ((,) a) m r -> Stream (Of a) m r
--
-- >>> :t destroyWith Data.ByteString.Streaming.wrap return
-- (Monad m, Functor f) =>
-- (f (ByteString m r) -> ByteString m r) -> Stream f m r -> ByteString m r
--
-- >>> :t destroyWith Data.ByteString.Streaming.wrap return (\(a:>b) -> consChunk a b)
-- Monad m =>
-- Stream (Of B.ByteString) m r -> ByteString m r -- fromChunks
--
destroyWith :: (Functor f, Monad m) => (m b -> b) -> (r -> b) -> (f b -> b) -> Stream f m r -> b
-- | Inspect the first stage of a freely layered sequence. Compare
-- Pipes.next and the replica Streaming.Prelude.next.
-- This is the uncons for the general unfold.
--
--
-- unfold inspect = id
-- Streaming.Prelude.unfoldr StreamingPrelude.next = id
--
inspect :: (Functor f, Monad m) => Stream f m r -> m (Either r (f (Stream f m r)))
-- | Map layers of one functor to another with a transformation
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 transformation involving
-- the base monad
mapsM :: (Monad m, Functor f) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r
-- | Map each layer to an effect in the base monad, and run them all.
mapsM_ :: (Functor f, Monad m) => (forall x. f x -> m x) -> Stream f m r -> m r
-- | Run the effects in a stream that merely layers effects.
runEffect :: Monad m => Stream m m r -> m r
-- | Make it possible to 'run' the underlying transformed monad. A simple
-- minded example might be:
--
--
-- debugFibs = flip runStateT 1 $ distribute $ loop 1 where
-- loop n = do
-- S.yield n
-- s <- lift get
-- liftIO $ putStr "Current state is: " >> print s
-- lift $ put (s + n :: Int)
-- loop s
--
--
--
-- >>> S.print $ S.take 4 $ S.drop 4 $ debugFibs
-- Current state is: 1
-- Current state is: 2
-- Current state is: 3
-- Current state is: 5
-- 5
-- Current state is: 8
-- 8
-- Current state is: 13
-- 13
-- Current state is: 21
-- 21
--
distribute :: (Monad m, Functor f, MonadTrans t, MFunctor t, Monad (t (Stream f m))) => Stream f (t m) r -> t (Stream f m) r
-- | Break a stream into substreams each with n functorial layers.
--
--
-- >>> S.print $ maps' sum' $ chunksOf 2 $ each [1,1,1,1,1,1,1]
-- 2
-- 2
-- 2
-- 1
--
chunksOf :: (Monad m, Functor f) => Int -> Stream f m r -> Stream (Stream f m) m r
-- | Split a succession of layers after some number, returning a streaming
-- or effectful pair.
--
--
-- >>> rest <- S.print $ S.splitAt 1 $ each [1..3]
-- 1
--
-- >>> S.print rest
-- 2
-- 3
--
splitsAt :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Stream f m r)
takes :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m ()
zipsWith :: (Monad m, Functor h) => (forall x y. f x -> g y -> h (x, y)) -> Stream f m r -> Stream g m r -> Stream h m r
zips :: (Monad m, Functor f, Functor g) => Stream f m r -> Stream g m r -> Stream (Compose f g) m r
-- | Interleave functor layers, with the effects of the first preceding the
-- effects of the second.
--
--
-- interleaves = zipsWith (liftA2 (,))
--
--
--
-- >>> let paste = \a b -> interleaves (Q.lines a) (maps (Q.cons' '\t') (Q.lines b))
--
-- >>> Q.stdout $ Q.unlines $ paste "hello\nworld\n" "goodbye\nworld\n"
-- hello goodbye
-- world world
--
interleaves :: (Monad m, Applicative h) => Stream h m r -> Stream h m r -> Stream h m r
-- | This is akin to the observe of Pipes.Internal . It
-- rewraps the layering in instances of Stream f m r so that it
-- replicates that of FreeT.
unexposed :: (Functor f, Monad m) => Stream f m r -> Stream f m r
hoistExposed :: (Functor f, Monad m1) => (m1 (Stream f m r) -> m (Stream f m r)) -> Stream f m1 r -> Stream f m r
mapsExposed :: (Monad m, Functor f) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r
mapsMExposed :: (Functor f1, Monad m) => (f1 (Stream f m r) -> m (f (Stream f m r))) -> Stream f1 m r -> Stream f m r
destroyExposed :: (Functor f, Monad m) => Stream f m t -> (f b -> b) -> (m b -> b) -> (t -> b) -> b
instance (Eq r, Eq (m (Stream f m r)), Eq (f (Stream f m r))) => Eq (Stream f m r)
instance (Show r, Show (m (Stream f m r)), Show (f (Stream f m r))) => Show (Stream f m r)
instance (MonadIO m, Functor f) => MonadIO (Stream f m)
instance Functor f => MMonad (Stream f)
instance Functor f => MFunctor (Stream f)
instance Functor f => MonadTrans (Stream f)
instance (Functor f, Monad m) => Applicative (Stream f m)
instance (Functor f, Monad m) => Monad (Stream f m)
instance (Functor f, Monad m) => Functor (Stream f m)
-- | This module is very closely modeled on Pipes.Prelude; it attempts to
-- simplify and optimize the conception of Producer manipulation
-- contained in Pipes.Group, Pipes.Parse and the like. This is very
-- simple and unmysterious; it is independent of piping and conduiting,
-- and can be used with any rational "streaming IO" system.
--
-- Some interoperation incantations would be e.g.
--
--
-- Pipes.unfoldr Streaming.next :: Stream (Of a) m r -> Producer a m r
-- Streaming.unfoldr Pipes.next :: Producer a m r -> Stream (Of a) m r
-- Streaming.reread IOStreams.read :: InputStream a -> Stream (Of a) IO ()
-- IOStreams.unfoldM Streaming.uncons :: Stream (Of a) IO () -> IO (InputStream a)
-- Conduit.unfoldM Streaming.uncons :: Stream (Of a) m () -> Source m a
--
--
-- Import qualified thus:
--
--
-- import Streaming
-- import qualified Streaming.Prelude as S
--
--
-- For the examples below, one sometimes needs
--
--
-- import Streaming.Prelude (each, yield, stdoutLn, stdinLn)
-- import qualified Control.Foldl as L -- cabal install foldl
-- import qualified Pipes as P
-- import qualified Pipes.Prelude as P
-- import qualified System.IO as IO
--
module Streaming.Prelude
-- | A left-strict pair; the base functor for streams of individual
-- elements.
data Of a b
(:>) :: !a -> b -> Of a b
lazily :: Of a b -> (a, b)
strictly :: (a, b) -> Of a b
fst' :: Of a b -> a
snd' :: Of a b -> b
-- | A singleton stream
--
--
-- >>> stdoutLn $ yield "hello"
-- hello
--
--
--
-- >>> S.sum $ do {yield 1; yield 2}
-- 3
--
--
--
-- >>> S.sum $ do {yield 1; lift $ putStrLn "# 1 was yielded"; yield 2; lift $ putStrLn "# 2 was yielded"}
-- # 1 was yielded
-- # 2 was yielded
-- 3
--
--
--
-- >>> let prompt :: IO Int; prompt = putStrLn "Enter a number:" >> readLn
--
-- >>> S.sum $ do {lift prompt >>= yield ; lift prompt >>= yield ; lift prompt >>= yield}
-- Enter a number:
-- 3<Enter>
-- Enter a number:
-- 20<Enter>
-- Enter a number:
-- 100<Enter>
-- 123
--
yield :: Monad m => a -> Stream (Of a) m ()
-- | Stream the elements of a foldable container.
--
--
-- >>> S.print $ S.map (*100) $ each [1..3] >> yield 4
-- 0
-- 100
-- 200
-- 300
-- 400
--
--
--
-- >>> S.print $ S.map (*100) $ each [1..3] >> lift readLn >>= yield
-- 100
-- 200
-- 300
-- 4<Enter>
-- 400
--
each :: (Monad m, Foldable f) => f a -> Stream (Of a) m ()
layers :: (Monad m, Functor f) => Stream (Of a) m r -> (a -> f x) -> Stream f m r
-- | Build a Stream by unfolding steps starting from a seed.
--
-- The seed can of course be anything, but this is one natural way to
-- consume a pipes Producer. Consider:
--
--
-- >>> S.stdoutLn $ S.take 2 (S.unfoldr P.next P.stdinLn)
-- hello<Enter>
-- hello
-- goodbye<Enter>
-- goodbye
--
--
--
-- >>> S.stdoutLn $ S.unfoldr P.next (P.stdinLn P.>-> P.take 2)
-- hello<Enter>
-- hello
-- goodbye<Enter>
-- goodbye
--
--
--
-- >>> S.drain $ S.unfoldr P.next (P.stdinLn P.>-> P.take 2 P.>-> P.stdoutLn)
-- hello<Enter>
-- hello
-- goodbye<Enter>
-- goodbye
--
--
-- If the intended "coalgebra" is complicated it might be pleasant to
-- write it with the state monad:
--
--
-- \state seed -> S.unfoldr (runExceptT . runStateT state) seed :: Monad m => StateT s (ExceptT r m) a -> s -> P.Producer a m r
--
--
--
-- >>> let state = do {n <- get ; if n >= 3 then lift (throwE "Got to three"); else put (n+1); return n}
--
-- >>> S.print $ S.unfoldr (runExceptT . runStateT state) 0
-- 0
-- 1
-- 2
-- "Got to three"
--
unfoldr :: Monad m => (s -> m (Either r (a, s))) -> s -> Stream (Of a) m r
-- | repeatedly stream lines as String from stdin
--
--
-- >>> stdoutLn $ S.show (S.each [1..3])
-- 1
-- 2
-- 3
--
--
--
-- >>> stdoutLn stdinLn
-- hello<Enter>
-- hello
-- world<Enter>
-- world
-- ^CInterrupted.
--
--
--
-- >>> stdoutLn $ S.map reverse stdinLn
-- hello<Enter>
-- olleh
-- world<Enter>
-- dlrow
-- ^CInterrupted.
--
stdinLn :: MonadIO m => Stream (Of String) m ()
-- | Read values from stdin, ignoring failed parses
--
--
-- >>> S.sum $ S.take 2 S.readLn :: IO Int
-- 3<Enter>
-- #$%^&\^?<Enter>
-- 1000<Enter>
-- 1003
--
readLn :: (MonadIO m, Read a) => Stream (Of a) m ()
-- | Read Strings from a Handle using hGetLine
--
-- Terminates on end of input
--
--
-- >>> withFile "distribute.hs" ReadMode $ stdoutLn . S.take 3 . fromHandle
-- import Streaming
-- import qualified Streaming.Prelude as S
-- import Control.Monad.Trans.State.Strict
--
fromHandle :: MonadIO m => Handle -> Stream (Of String) m ()
-- | Iterate a pure function from a seed value, streaming the results
-- forever
iterate :: (a -> a) -> a -> Stream (Of a) m r
-- | Repeat an element ad inf. .
--
--
-- >>> S.print $ S.take 3 $ S.repeat 1
-- 1
-- 1
-- 1
--
repeat :: a -> Stream (Of a) m r
-- | Cycle repeatedly through the layers of a stream, ad inf. This
-- function is functor-general
--
--
-- cycle = forever
--
--
--
-- >>> rest <- S.print $ S.splitAt 3 $ S.cycle (yield True >> yield False)
-- True
-- False
-- True
--
-- >>> S.print $ S.take 3 rest
-- False
-- True
-- False
--
cycle :: (Monad m, Functor f) => Stream f m r -> Stream f m s
-- | Repeat a monadic action ad inf., streaming its results.
--
--
-- >>> S.toListM $ S.take 2 (repeatM getLine)
-- hello<Enter>
-- world<Enter>
-- ["hello","world"]
--
repeatM :: Monad m => m a -> Stream (Of a) m r
-- | Repeat an action several times, streaming the results.
--
--
-- >>> S.print $ S.replicateM 2 getCurrentTime
-- 2015-08-18 00:57:36.124508 UTC
-- 2015-08-18 00:57:36.124785 UTC
--
replicateM :: Monad m => Int -> m a -> Stream (Of a) m ()
enumFrom :: (Monad m, Enum n) => n -> Stream (Of n) m r
enumFromThen :: (Monad m, Enum a) => a -> a -> Stream (Of a) m r
-- | Write Strings to stdout using putStrLn;
-- terminates on a broken output pipe
--
--
-- >>> S.stdoutLn $ S.show (S.each [1..3])
-- 1
-- 2
-- 3
--
stdoutLn :: MonadIO m => Stream (Of String) m () -> m ()
-- | Write Strings to stdout using putStrLn
--
-- This does not handle a broken output pipe, but has a polymorphic
-- return value, which makes this possible:
--
--
-- >>> rest <- stdoutLn' $ S.splitAt 3 $ S.show (each [1..5])
-- 1
-- 2
-- 3
--
-- >>> stdoutLn' rest
-- 4
-- 5
--
--
-- Or indeed:
--
--
-- >>> rest <- stdoutLn' $ S.show $ S.splitAt 3 (each [1..5])
-- 1
-- 2
-- 3
--
-- >>> S.sum rest
-- 9
--
stdoutLn' :: MonadIO m => Stream (Of String) 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
--
mapM_ :: Monad m => (a -> m b) -> Stream (Of a) m r -> m r
print :: (MonadIO m, Show a) => Stream (Of a) m r -> m r
toHandle :: MonadIO m => Handle -> Stream (Of String) m r -> m r
-- | Reduce a stream, performing its actions but ignoring its elements.
--
--
-- >>> let stream = do {yield 1; lift (putStrLn "Effect!"); yield 2; lift (putStrLn "Effect!"); return (2^100)}
--
--
--
-- >>> S.drain stream
-- Effect!
-- Effect!
-- 1267650600228229401496703205376
--
--
--
-- >>> S.drain $ S.takeWhile (<2) stream
-- Effect!
--
drain :: Monad m => Stream (Of a) m r -> m r
-- | Standard map on the elements of a stream.
map :: Monad m => (a -> b) -> Stream (Of a) m r -> Stream (Of b) m r
-- | Replace each element of a stream with the result of a monadic action
mapM :: Monad m => (a -> m b) -> Stream (Of a) m r -> Stream (Of b) m r
-- | Map layers of one functor to another with a transformation
maps :: (Monad m, Functor f) => (forall x. f x -> g x) -> Stream f m r -> Stream g 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
--
sequence :: Monad m => Stream (Of (m a)) m r -> Stream (Of a) m r
-- | For each element of a stream, stream a foldable container of elements
-- instead
--
--
-- >>> S.print $ S.mapFoldable show $ yield 12
-- '1'
-- '2'
--
mapFoldable :: (Monad m, Foldable t) => (a -> t b) -> Stream (Of a) m r -> Stream (Of b) m r
-- | Skip elements of a stream that fail a predicate
filter :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m r
-- | Skip elements of a stream that fail a monadic test
filterM :: Monad m => (a -> m Bool) -> Stream (Of a) m r -> Stream (Of a) m r
-- | for replaces each element of a stream with an associated
-- stream. Note that the associated stream may layer any functor.
for :: (Monad m, Functor f) => Stream (Of a) m r -> (a -> Stream f m x) -> Stream f m r
-- | End a stream after n elements; the original return value is thus lost.
-- splitAt preserves this information. Note that, like
-- splitAt, this function is functor-general, so that, for
-- example, you can take not just a number of items from a
-- stream of elements, but a number of substreams and the like.
--
--
-- >>> S.print $ mapsM sum' $ S.take 2 $ chunksOf 3 $ each [1..]
-- 6 -- sum of first group of 3
-- 15 -- sum of second group of 3
--
-- >>> S.print $ mapsM S.sum' $ S.take 2 $ chunksOf 3 $ S.each [1..4] >> S.readLn
-- 6 -- sum of first group of 3, which is already in [1..4]
-- 100 -- user input
-- 10000 -- user input
-- 10104 -- sum of second group of 3
--
take :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m ()
-- | End stream when an element fails a condition; the original return
-- value is lost span preserves this information.
takeWhile :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m ()
-- | Ignore the first n elements of a stream, but carry out the actions
drop :: Monad m => Int -> Stream (Of a) m r -> Stream (Of a) m r
-- | Ignore elements of a stream until a test succeeds.
--
--
-- >>> IO.withFile "distribute.hs" IO.ReadMode $ S.stdoutLn . S.take 2 . S.dropWhile (isPrefixOf "import") . S.fromHandle
-- main :: IO ()
-- main = do
--
dropWhile :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m r
-- | Make a stream of traversable containers into a stream of their
-- separate elements
--
--
-- >>> S.print $ S.concat (each ["xy","z"])
-- 'x'
-- 'y'
-- 'z'
--
-- >>> S.print $ S.concat (S.each [Just 1, Nothing, Just 2])
-- 1
-- 2
--
-- >>> S.print $ S.concat (S.each [Right 1, Left "Error!", Right 2])
-- 1
-- 2
--
--
-- Not to be confused with the functor-general
--
--
-- concats :: (Monad m, Functor f) => Stream (Stream f m) m r -> Stream f m r -- specializing
--
--
--
-- >>> S.stdoutLn $ concats $ maps (<* yield "--\n--") $ chunksOf 2 $ S.show (each [1..5])
-- 1
-- 2
-- --
-- --
-- 3
-- 4
-- --
-- --
-- 5
-- --
-- --
--
concat :: (Monad m, Foldable f) => Stream (Of (f a)) m r -> Stream (Of a) 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
--
--
--
-- >>> S.print $ L.purely S.scan L.list $ each [3..5]
-- []
-- [3]
-- [3,4]
-- [3,4,5]
--
scan :: Monad m => (x -> a -> x) -> x -> (x -> 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
--
--
--
-- >>> let v = L.impurely scanM L.vector $ each [1..4::Int] :: Stream (Of (U.Vector Int)) IO ()
--
-- >>> S.print v
-- fromList []
-- fromList [1]
-- fromList [1,2]
-- fromList [1,2,3]
-- fromList [1,2,3,4]
--
scanM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Stream (Of a) m r -> Stream (Of b) m r
-- | Apply an action to all values flowing downstream
--
--
-- >>> S.product (chain print (S.each [2..4])) >>= print
-- 2
-- 3
-- 4
-- 24
--
chain :: Monad m => (a -> m ()) -> Stream (Of a) m r -> Stream (Of a) m r
-- | Make a stream of strings into a stream of parsed values, skipping bad
-- cases
read :: (Monad m, Read a) => Stream (Of String) m r -> Stream (Of a) m r
show :: (Monad m, Show a) => Stream (Of a) m r -> Stream (Of String) m r
-- | The natural cons for a Stream (Of a).
--
--
-- cons a stream = yield a >> stream
--
--
-- Useful for interoperation:
--
--
-- Data.Text.foldr S.cons (return ()) :: Text -> Stream (Of Char) m ()
-- Lazy.foldrChunks S.cons (return ()) :: Lazy.ByteString -> Stream (Of Strict.ByteString) m ()
--
--
-- and so on.
cons :: Monad m => a -> Stream (Of a) m r -> 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
next :: Monad m => Stream (Of a) m r -> m (Either r (a, Stream (Of a) m r))
-- | Inspect the first item in a stream of elements, without a return
-- value. uncons provides convenient exit into another streaming
-- type:
--
--
-- IOStreams.unfoldM uncons :: Stream (Of a) IO b -> IO (InputStream a)
-- Conduit.unfoldM uncons :: Stream (Of a) m r -> Conduit.Source m a
--
uncons :: Monad m => Stream (Of a) m () -> m (Maybe (a, Stream (Of a) m ()))
-- | Split a succession of layers after some number, returning a streaming
-- or -- effectful pair. This function is the same as the splitsAt
-- exported by the -- Streaming module, but since this module is
-- imported qualified, it can -- usurp a Prelude name. It specializes to:
--
--
-- splitAt :: (Monad m, Functor f) => Int -> Stream (Of a) m r -> Stream (Of a) m (Stream (Of a) m r)
--
splitAt :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Stream f m r)
-- | Break a sequence when a element falls under a predicate, keeping the
-- rest of the stream as the return value.
--
--
-- >>> rest <- S.print $ S.break even $ each [1,1,2,3]
-- 1
-- 1
--
-- >>> S.print rest
-- 2
-- 3
--
break :: 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.
span :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) m (Stream (Of a) m r)
group :: (Monad m, Eq a) => Stream (Of a) m r -> Stream (Stream (Of a) m) m r
groupBy :: Monad m => (a -> a -> Bool) -> Stream (Of a) m r -> Stream (Stream (Of a) m) m r
-- | 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 () -> m b
-- | Strict fold of a Stream of elements that preserves the return
-- value.
--
--
-- >>> S.sum' $ each [1..10]
-- 55 :> ()
--
--
--
-- >>> (n :> rest) <- sum' $ S.splitAt 3 (each [1..10])
--
-- >>> print n
-- 6
--
-- >>> (m :> rest') <- sum' $ S.splitAt 3 rest
--
-- >>> print m
-- 15
--
-- >>> S.print rest'
-- 7
-- 8
-- 9
--
--
-- The type provides for interoperation with the foldl library.
--
--
-- Control.Foldl.purely fold' :: Monad m => Fold a b -> Stream (Of a) m r -> m (Of b r)
--
--
-- Thus, specializing a bit:
--
--
-- L.purely fold' L.sum :: Stream (Of Int) Int r -> m (Of Int r)
-- maps (L.purely fold' L.sum) :: Stream (Stream (Of Int)) IO r -> Stream (Of Int) IO r
--
--
--
-- >>> S.print $ mapsM (L.purely S.fold' (liftA2 (,) L.list L.sum)) $ chunksOf 3 $ each [1..10]
-- ([1,2,3],6)
-- ([4,5,6],15)
-- ([7,8,9],24)
-- ([10],10)
--
fold' :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Stream (Of a) m r -> m (Of 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 () -> m b
--
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 r -> m (b, r)
--
foldM' :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Stream (Of a) m r -> m (Of b r)
-- | Fold a Stream of numbers into their sum
sum :: (Monad m, Num a) => Stream (Of a) m () -> m a
-- | Fold a Stream of numbers into their sum with the return value
--
--
-- maps' sum' :: Stream (Stream (Of Int)) m r -> Stream (Of Int) m r
--
sum' :: (Monad m, Num a) => Stream (Of a) m r -> m (Of a r)
-- | Fold a Stream of numbers into their product
product :: (Monad m, Num a) => Stream (Of a) m () -> m a
-- | Fold a Stream of numbers into their product with the return
-- value
--
--
-- maps' product' :: Stream (Stream (Of Int)) m r -> Stream (Of Int) m r
--
product' :: (Monad m, Num a) => Stream (Of a) m r -> m (Of a r)
length :: Monad m => Stream (Of a) m () -> m Int
length' :: Monad m => Stream (Of a) m r -> m (Of Int r)
-- | Convert a pure Stream (Of a) into a list of as
toList :: Stream (Of a) Identity () -> [a]
-- | Convert an effectful 'Stream (Of a)' into a list of as
--
-- Note: Needless to say this function does not stream properly. It is
-- basically the same as mapM which, like replicateM,
-- sequence and similar operations on traversable containers is a
-- leading cause of space leaks.
toListM :: Monad m => Stream (Of a) m () -> m [a]
-- | Convert an effectful Stream into a list alongside the return
-- value
--
--
-- maps' toListM' :: Stream (Stream (Of a)) m r -> Stream (Of [a]) m
--
toListM' :: Monad m => Stream (Of a) m r -> m (Of [a] 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
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 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
--
foldrT :: (Monad m, MonadTrans t, Monad (t m)) => (a -> t m r -> t m r) -> Stream (Of a) m r -> t m r
-- | Zip two Streamss
zip :: Monad m => (Stream (Of a) m r) -> (Stream (Of b) m r) -> (Stream (Of (a, b)) m r)
-- | Zip two Streamss using the provided combining function
zipWith :: Monad m => (a -> b -> c) -> (Stream (Of a) m r) -> (Stream (Of b) m r) -> (Stream (Of c) m r)
-- | Read an IORef (Maybe a) or a similar device until it reads
-- Nothing. reread provides convenient exit from the
-- io-streams library
--
--
-- reread readIORef :: IORef (Maybe a) -> Stream (Of a) IO ()
-- reread Streams.read :: System.IO.Streams.InputStream a -> Stream (Of a) IO ()
--
reread :: Monad m => (s -> m (Maybe a)) -> s -> Stream (Of a) m ()
data Stream f m r
instance Typeable Of
instance (Data a, Data b) => Data (Of a b)
instance (Eq a, Eq b) => Eq (Of a b)
instance Foldable (Of a)
instance Functor (Of a)
instance (Ord a, Ord b) => Ord (Of a b)
instance (Read a, Read b) => Read (Of a b)
instance (Show a, Show b) => Show (Of a b)
instance Traversable (Of a)
module Streaming
data Stream f m r
-- | Build a Stream by unfolding steps starting from a seed. See
-- also the specialized unfoldr in the prelude.
--
--
-- unfold inspect = id -- modulo the quotient we work with
-- unfold Pipes.next :: Monad m => Producer a m r -> Stream ((,) a) m r
-- unfold (curry (:>) . Pipes.next) :: Monad m => Producer a m r -> Stream (Of a) m r
--
unfold :: (Monad m, Functor f) => (s -> m (Either r (f s))) -> s -> Stream f m r
-- | Reflect a church-encoded stream; cp. GHC.Exts.build
construct :: (forall b. (f b -> b) -> (m b -> b) -> (r -> b) -> b) -> Stream f m r
-- | for replaces each element of a stream with an associated
-- stream. Note that the associated stream may layer any functor.
for :: (Monad m, Functor f) => Stream (Of a) m r -> (a -> Stream f m x) -> Stream f m r
-- | Lift for items in the base functor. Makes a singleton or one-layer
-- succession.`
layer :: (Monad m, Functor f) => f r -> Stream f m r
layers :: (Monad m, Functor f) => Stream (Of a) m r -> (a -> f x) -> Stream f m r
-- | Repeat a functorial layer, command or instruct several times.
replicates :: (Monad m, Functor f) => Int -> f () -> Stream f m ()
-- | Repeat a functorial layer, command or instruction forever.
repeats :: (Monad m, Functor f) => f () -> Stream f m r
repeatsM :: (Monad m, Functor f) => m (f ()) -> Stream f m r
wrap :: (Monad m, Functor f) => m (Stream f m r) -> Stream f m r
step :: (Monad m, Functor f) => f (Stream f m r) -> Stream f m r
-- | Map layers of one functor to another with a transformation
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 transformation involving
-- the base monad
mapsM :: (Monad m, Functor f) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r
-- | Make it possible to 'run' the underlying transformed monad. A simple
-- minded example might be:
--
--
-- debugFibs = flip runStateT 1 $ distribute $ loop 1 where
-- loop n = do
-- S.yield n
-- s <- lift get
-- liftIO $ putStr "Current state is: " >> print s
-- lift $ put (s + n :: Int)
-- loop s
--
--
--
-- >>> S.print $ S.take 4 $ S.drop 4 $ debugFibs
-- Current state is: 1
-- Current state is: 2
-- Current state is: 3
-- Current state is: 5
-- 5
-- Current state is: 8
-- 8
-- Current state is: 13
-- 13
-- Current state is: 21
-- 21
--
distribute :: (Monad m, Functor f, MonadTrans t, MFunctor t, Monad (t (Stream f m))) => Stream f (t m) r -> t (Stream f m) r
-- | Inspect the first stage of a freely layered sequence. Compare
-- Pipes.next and the replica Streaming.Prelude.next.
-- This is the uncons for the general unfold.
--
--
-- unfold inspect = id
-- Streaming.Prelude.unfoldr StreamingPrelude.next = id
--
inspect :: (Functor f, Monad m) => Stream f m r -> m (Either r (f (Stream f m r)))
zips :: (Monad m, Functor f, Functor g) => Stream f m r -> Stream g m r -> Stream (Compose f g) m r
zipsWith :: (Monad m, Functor h) => (forall x y. f x -> g y -> h (x, y)) -> Stream f m r -> Stream g m r -> Stream h m r
-- | Interleave functor layers, with the effects of the first preceding the
-- effects of the second.
--
--
-- interleaves = zipsWith (liftA2 (,))
--
--
--
-- >>> let paste = \a b -> interleaves (Q.lines a) (maps (Q.cons' '\t') (Q.lines b))
--
-- >>> Q.stdout $ Q.unlines $ paste "hello\nworld\n" "goodbye\nworld\n"
-- hello goodbye
-- world world
--
interleaves :: (Monad m, Applicative h) => Stream h m r -> Stream h m r -> Stream h m r
-- | Interpolate a layer at each segment. This specializes to e.g.
--
--
-- intercalates :: (Monad m, Functor f) => Stream f m () -> Stream (Stream f m) m r -> Stream f m r
--
intercalates :: (Monad m, Monad (t m), MonadTrans t) => t m a -> Stream (t m) m b -> t m b
-- | Dissolves the segmentation into layers of Stream f m layers.
--
--
-- concats stream = destroy stream join (join . lift) return
--
--
--
-- >>> S.print $ concats $ maps (cons 1776) $ chunksOf 2 (each [1..5])
-- 1776
-- 1
-- 2
-- 1776
-- 3
-- 4
-- 1776
-- 5
--
concats :: (Monad m, Functor f) => Stream (Stream f m) m r -> Stream f m r
-- | Specialized fold
--
--
-- iterTM alg stream = destroy stream alg (join . lift) return
--
iterTM :: (Functor f, Monad m, MonadTrans t, Monad (t m)) => (f (t m a) -> t m a) -> Stream f m a -> t m a
-- | Specialized fold
--
--
-- iterT alg stream = destroy stream alg join return
--
iterT :: (Functor f, Monad m) => (f (m a) -> m a) -> Stream f m a -> m a
-- | Map a stream directly to its church encoding; compare
-- Data.List.foldr It permits distinctions that should be
-- hidden, as can be seen from e.g.
--
-- isPure stream = destroy_ (const True) (const False) (const True)
--
-- and similar nonsense. The crucial constraint is that the m x ->
-- x argument is an Eilenberg-Moore algebra. See Atkey
-- "Reasoning about Stream Processing with Effects"
--
-- The destroy exported by the safe modules is
--
-- destroy str = destroy (observe str)
destroy :: (Functor f, Monad m) => Stream f m r -> (f b -> b) -> (m b -> b) -> (r -> b) -> b
-- | Map each layer to an effect in the base monad, and run them all.
mapsM_ :: (Functor f, Monad m) => (forall x. f x -> m x) -> Stream f m r -> m r
-- | Run the effects in a stream that merely layers effects.
runEffect :: Monad m => Stream m m r -> m r
-- | Split a succession of layers after some number, returning a streaming
-- or effectful pair.
--
--
-- >>> rest <- S.print $ S.splitAt 1 $ each [1..3]
-- 1
--
-- >>> S.print rest
-- 2
-- 3
--
splitsAt :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Stream f m r)
takes :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m ()
-- | Break a stream into substreams each with n functorial layers.
--
--
-- >>> S.print $ maps' sum' $ chunksOf 2 $ each [1,1,1,1,1,1,1]
-- 2
-- 2
-- 2
-- 1
--
chunksOf :: (Monad m, Functor f) => Int -> Stream f m r -> Stream (Stream f m) m r
-- | Dissolves the segmentation into layers of Stream f m layers.
--
--
-- concats stream = destroy stream join (join . lift) return
--
--
--
-- >>> S.print $ concats $ maps (cons 1776) $ chunksOf 2 (each [1..5])
-- 1776
-- 1
-- 2
-- 1776
-- 3
-- 4
-- 1776
-- 5
--
concats :: (Monad m, Functor f) => Stream (Stream f m) m r -> Stream f m r
-- | A left-strict pair; the base functor for streams of individual
-- elements.
data Of a b
(:>) :: !a -> b -> Of a b
lazily :: Of a b -> (a, b)
strictly :: (a, b) -> Of a b
-- | A functor in the category of monads, using hoist as the analog
-- of fmap:
--
--
-- hoist (f . g) = hoist f . hoist g
--
-- hoist id = id
--
class MFunctor (t :: (* -> *) -> * -> *)
hoist :: (MFunctor t, Monad m) => (forall a. m a -> n a) -> t m b -> t n b
-- | A monad in the category of monads, using lift from
-- MonadTrans as the analog of return and embed as
-- the analog of (=<<):
--
--
-- embed lift = id
--
-- embed f (lift m) = f m
--
-- embed g (embed f t) = embed (\m -> embed g (f m)) t
--
class (MFunctor t, MonadTrans t) => MMonad (t :: (* -> *) -> * -> *)
embed :: (MMonad t, Monad n) => (forall a. m a -> t n a) -> t m b -> t n b
-- | The class of monad transformers. Instances should satisfy the
-- following laws, which state that lift is a transformer of
-- monads:
--
--
class MonadTrans (t :: (* -> *) -> * -> *)
lift :: (MonadTrans t, Monad m) => m a -> t m a
-- | Monads in which IO computations may be embedded. Any monad
-- built by applying a sequence of monad transformers to the IO
-- monad will be an instance of this class.
--
-- Instances should satisfy the following laws, which state that
-- liftIO is a transformer of monads:
--
--
class Monad m => MonadIO (m :: * -> *)
liftIO :: MonadIO m => IO a -> m a
-- | Right-to-left composition of functors. The composition of applicative
-- functors is always applicative, but the composition of monads is not
-- always a monad.
newtype Compose (f :: * -> *) (g :: * -> *) a :: (* -> *) -> (* -> *) -> * -> *
Compose :: f (g a) -> Compose a
getCompose :: Compose a -> f (g a)
-- | The join function is the conventional monad join operator. It
-- is used to remove one level of monadic structure, projecting its bound
-- argument into the outer level.
join :: Monad m => m (m a) -> m a
-- | Lift a binary function to actions.
liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c
-- | Lift a ternary function to actions.
liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
-- | void value discards or ignores the result of
-- evaluation, such as the return value of an IO action.
void :: Functor f => f a -> f ()