-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | an elementary streaming prelude and general stream type.
--
-- Streaming.Prelude exports an elementary streaming prelude
-- focused on a simple "source" or "producer" type, namely Stream (Of
-- a) m r. This is a sort of effectful version of ([a],r)
-- in which monadic action is interleaved between successive elements.
-- The main module, Streaming, exports a much more general type,
-- Stream f m r, which can be used to stream successive distinct
-- steps characterized by any functor f, though we are
-- here interested only in a limited range of cases.
--
-- The streaming-IO libraries have various devices for dealing with
-- effectful variants of [a] or ([a],r). But it is only
-- with the general type Stream f m r, or some equivalent, that
-- one can envisage (for example) the connected streaming of their sorts
-- of stream -- as one makes lists of lists in the Haskell
-- Prelude and Data.List. One needs some such type if
-- we are to express properly streaming equivalents of e.g.
--
--
-- group :: Ord a => [a] -> [[a]]
-- chunksOf :: Int -> [a] -> [[a]]
-- lines :: [Char] -> [[Char]] -- but similarly with bytestring, etc.
--
--
-- to mention a few obviously desirable operations. But once one grasps
-- the iterable stream concept needed to express those functions - to
-- wit, Stream f m r or some equivalent - then one will also see
-- that, with it, one is already in possession of a complete elementary
-- streaming library - since one possesses Stream ((,) a) m r or
-- equivalently Stream (Of a) m r. This is the type of a
-- 'generator' or 'producer' or whatever you call an effectful stream of
-- items. The present Streaming.Prelude is thus the simplest
-- streaming library that can replicate anything like the API of the
-- Prelude and Data.List.
--
-- The emphasis of the library is on interoperation; for the rest its
-- advantages are: extreme simplicity and re-use of intuitions the user
-- has gathered from mastery of Prelude and Data.List.
-- The two conceptual pre-requisites are some comprehension of monad
-- transformers and some familiarity with 'rank 2 types'.
--
-- See the readme below for an explanation, including the examples
-- linked there. Elementary usage can be divined from the ghci examples
-- in Streaming.Prelude and perhaps from this rough beginning of
-- a tutorial. Note also the streaming bytestring and
-- streaming utils packages. Questions about usage can be put
-- raised on StackOverflow with the tag [haskell-streaming], or
-- as an issue on Github, or on the pipes list (the package
-- understands itself as part of the pipes 'ecosystem'.)
--
-- The simplest form of interoperation with pipes is accomplished
-- with this isomorphism:
--
--
-- 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
--
--
-- Interoperation with io-streams is thus:
--
--
-- Streaming.reread IOStreams.read :: InputStream a -> Stream (Of a) IO ()
-- IOStreams.unfoldM Streaming.uncons :: Stream (Of a) IO () -> IO (InputStream a)
--
--
-- With conduit one might use, e.g.:
--
--
-- Conduit.unfoldM Streaming.uncons :: Stream (Of a) m () -> Source m a
-- Streaming.mapM_ Conduit.yield . hoist lift :: Stream (Of o) m r -> ConduitM i o m r
-- ($$ Conduit.mapM_ Streaming.yield) . hoist lift :: Source m a -> Stream (Of a) m ()
--
--
-- These conversions should never be more expensive than a single
-- >-> or =$=.
--
-- Here is a simple example (conceptually it is a bit advanced, maybe)
-- that runs a single underlying stream with several streaming-io
-- libraries at once, superimposing their effects without any
-- accumulation:
--
--
-- module Main (main) where
-- import Streaming
-- import Pipes
-- import Data.Conduit
-- import qualified Streaming.Prelude as S
-- import qualified Data.Conduit.List as CL
-- import qualified Pipes.Prelude as P
-- import qualified System.IO.Streams as IOS
-- import Data.ByteString.Char8 (pack)
-- import Data.Function ((&))
--
-- mkConduit = CL.unfoldM S.uncons
-- mkPipe = P.unfoldr S.next
-- mkIOStream = IOS.unfoldM S.uncons
--
-- main = iostreamed where
-- urstream = S.take 3 S.readLn :: Stream (Of Int) IO ()
-- streamed = S.copy urstream & S.map (\n -> "streaming says: " ++ show n)
-- & S.stdoutLn
-- piped = runEffect $
-- mkPipe (S.copy streamed) >-> P.map (\n -> "pipes says: " ++ show n)
-- >-> P.stdoutLn
-- conduited =
-- mkConduit (S.copy piped) $$ CL.map (\n -> "conduit says: " ++ show n)
-- =$ CL.mapM_ (liftIO . putStrLn)
-- iostreamed = do
-- str0 <- mkIOStream conduited
-- str1 <- IOS.map (\n -> pack $ "io-streams says: " ++ show n ++ "\n") str0
-- IOS.supply str1 IOS.stdout
--
--
-- This program successively parses three Ints from standard
-- input, and simulaneously passes them to (here trivial)
-- stream-consuming processes from four different libraries, using the
-- copy function from Streaming.Prelude. I mark my own
-- input with <Enter> below:
--
--
-- >>> main
-- 1 <Enter>
-- streaming says: 1
-- pipes says: 1
-- conduit says: 1
-- io-streams says: 1
-- 2 <Enter>
-- streaming says: 2
-- pipes says: 2
-- conduit says: 2
-- io-streams says: 2
-- 3 <Enter>
-- streaming says: 3
-- pipes says: 3
-- conduit says: 3
-- io-streams says: 3
-- >>>
--
--
-- Of course, I could as well have passed the stream to several
-- independent conduits; and I might have derived the original stream
-- from a conduit Source or pipes Producer etc., using
-- one of the 'conversion' functions above. Further points of comparison
-- with the going streaming-IO libraries are discussed in the
-- readme below.
--
-- Here are the results of some microbenchmarks based on the
-- benchmarks included in the machines package:
--
--
-- Because these are microbenchmarks for individual functions, they
-- represent a sort of "worst case"; many other factors can influence the
-- speed of a complex program.
@package streaming
@version 0.1.4.1
module Streaming.Internal
data Stream f m r
Step :: !(f (Stream f m r)) -> Stream f m r
Effect :: (m (Stream f m r)) -> Stream f m r
Return :: r -> 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 instruction a fixed number of
-- times.
--
--
-- replicates n = takes n . repeats
--
replicates :: (Monad m, Functor f) => Int -> f () -> Stream f m ()
-- | Repeat a functorial layer (a "command" or "instruction") forever.
repeats :: (Monad m, Functor f) => f () -> Stream f m r
-- | Repeat an effect containing a functorial layer, command or instruction
-- forever.
repeatsM :: (Monad m, Functor f) => m (f ()) -> Stream f m r
-- | Wrap an effect that returns a stream
--
--
-- effect = join . lift
--
effect :: (Monad m, Functor f) => m (Stream f m r) -> Stream f m r
wrap :: (Monad m, Functor f) => f (Stream f m r) -> Stream f m r
-- | yields is like lift for items in the streamed
-- functor. It makes a singleton or one-layer succession.
--
--
-- lift :: (Monad m, Functor f) => m r -> Stream f m r
-- yields :: (Monad m, Functor f) => f r -> Stream f m r
--
--
-- Viewed in another light, it is like a functor-general version of
-- yield:
--
--
-- S.yield a = yields (a :> ())
--
yields :: (Monad m, Functor f) => f r -> Stream f m r
-- | Reflect a church-encoded stream; cp. GHC.Exts.build
--
--
-- streamFold return_ effect_ step_ (streamBuild psi) = psi return_ effect_ step_
--
streamBuild :: (forall b. (r -> b) -> (m b -> b) -> (f b -> b) -> b) -> Stream f m r
-- | Construct an infinite stream by cycling a finite one
--
--
-- cycles = forever
--
--
--
-- >>>
--
cycles :: (Monad m, Functor f) => Stream f m () -> Stream f m r
delays :: (MonadIO m, Applicative f) => Double -> Stream f m r
-- | never interleaves the pure applicative action with the return
-- of the monad forever. It is the empty of the Alternative
-- instance, thus
--
--
-- never <|> a = a
-- a <|> never = a
--
--
-- and so on. If w is a monoid then never :: Stream (Of w) m r
-- is the infinite sequence of mempty, and str1 <|>
-- str2 appends the elements monoidally until one of streams ends.
-- Thus we have, e.g.
--
--
-- >>> S.stdoutLn $ S.take 2 $ S.stdinLn <|> S.repeat " " <|> S.stdinLn <|> S.repeat " " <|> S.stdinLn
-- 1<Enter>
-- 2<Enter>
-- 3<Enter>
-- 1 2 3
-- 4<Enter>
-- 5<Enter>
-- 6<Enter>
-- 4 5 6
--
--
-- This is equivalent to
--
--
-- >>> S.stdoutLn $ S.take 2 $ foldr (<|>) never [S.stdinLn, S.repeat " ", S.stdinLn, S.repeat " ", S.stdinLn ]
--
--
-- Where f is a monad, (<|>) sequences the
-- conjoined streams stepwise. See the definition of paste
-- here, where the separate steps are bytestreams corresponding to
-- the lines of a file.
--
-- Given, say,
--
--
-- data Branch r = Branch r r deriving Functor -- add obvious applicative instance
--
--
-- then never :: Stream Branch Identity r is the pure infinite
-- binary tree with (inaccessible) rs in its leaves. Given two
-- binary trees, tree1 <|> tree2 intersects them,
-- preserving the leaves that came first, so tree1 <|> never =
-- tree1
--
-- Stream Identity m r is an action in m that is
-- indefinitely delayed. Such an action can be constructed with e.g.
-- untilJust.
--
--
-- untilJust :: (Monad m, Applicative f) => m (Maybe r) -> Stream f m r
--
--
-- Given two such items, <|> instance races them. It is
-- thus the iterative monad transformer specially defined in
-- Control.Monad.Trans.Iter
--
-- So, for example, we might write
--
--
-- >>> let justFour str = if length str == 4 then Just str else Nothing
--
-- >>> let four = untilJust (liftM justFour getLine)
--
-- >>> run four
-- one<Enter>
-- two<Enter>
-- three<Enter>
-- four<Enter>
-- "four"
--
--
-- The Alternative instance in Control.Monad.Trans.Free is
-- avowedly wrong, though no explanation is given for this.
never :: (Monad m, Applicative f) => Stream f m r
-- | Repeat a
untilJust :: (Monad m, Applicative f) => m (Maybe 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 x -> Stream (t m) m r -> t m r
-- | Dissolves the segmentation into layers of Stream f m layers.
concats :: (Monad m, Functor f) => Stream (Stream f m) m r -> Stream f m r
-- | Specialized fold following the usage of
-- Control.Monad.Trans.Free
--
--
-- iterT alg = streamFold return join alg
--
iterT :: (Functor f, Monad m) => (f (m a) -> m a) -> Stream f m a -> m a
-- | Specialized fold following the usage of
-- Control.Monad.Trans.Free
--
--
-- iterTM alg = streamFold return (join . lift)
--
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
destroy :: (Functor f, Monad m) => Stream f m r -> (f b -> b) -> (m b -> b) -> (r -> b) -> b
-- | streamFold 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 streamFold return join
-- (Monad m, Functor f) =>
-- (f (m a) -> m a) -> Stream f m a -> m a -- iterT
--
--
--
-- >>> :t streamFold return (join . lift)
-- (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 streamFold return effect
-- (Monad m, Functor f, Functor g) =>
-- (f (Stream g m r) -> Stream g m r) -> Stream f m r -> Stream g m r
--
--
--
-- >>> :t \f -> streamFold return effect (wrap . f)
-- (Monad m, Functor f, Functor g) =>
-- (f (Stream g m a) -> g (Stream g m a))
-- -> Stream f m a -> Stream g m a -- maps
--
--
--
-- >>> :t \f -> streamFold return effect (effect . liftM wrap . f)
-- (Monad m, Functor f, Functor g) =>
-- (f (Stream g m a) -> m (g (Stream g m a)))
-- -> Stream f m a -> Stream g m a -- mapped
--
streamFold :: (Functor f, Monad m) => (r -> b) -> (m b -> 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. Compare
-- hoist, which has a similar effect on the monadic parameter.
--
--
-- maps id = id
-- maps f . maps g = maps (f . g)
--
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 maps is more fundamental than mapsM,
-- which is best understood as a convenience for effecting this frequent
-- composition:
--
--
-- mapsM phi = decompose . maps (Compose . phi)
--
--
-- The streaming prelude exports the same function under the better name
-- mapped, which overlaps with the lens libraries.
mapsM :: (Monad m, Functor f) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r
-- | Rearrange a succession of layers of the form Compose m (f x).
--
-- we could as well define decompose by mapsM:
--
--
-- decompose = mapped getCompose
--
--
-- but mapped is best understood as:
--
--
-- mapped phi = decompose . maps (Compose . phi)
--
--
-- since maps and hoist are the really fundamental
-- operations that preserve the shape of the stream:
--
--
-- maps :: (Monad m, Functor f) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r
-- hoist :: (Monad m, Functor f) => (forall a. m a -> n a) -> Stream f m r -> Stream f n r
--
decompose :: (Monad m, Functor f) => Stream (Compose m f) m r -> Stream f m r
-- | Map each layer to an effect, 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.
run :: Monad m => Stream m m r -> m r
-- | Make it possible to 'run' the underlying transformed monad.
distribute :: (Monad m, Functor f, MonadTrans t, MFunctor t, Monad (t (Stream f m))) => Stream f (t m) r -> t (Stream f m) r
-- | Group layers in an alternating stream into adjoining sub-streams of
-- one type or another.
groups :: (Monad m, Functor f, Functor g) => Stream (Sum f g) m r -> Stream (Sum (Stream f m) (Stream g m)) m r
-- | Break a stream into substreams each with n functorial layers.
--
--
-- >>> S.print $ mapped S.sum $ chunksOf 2 $ each [1,1,1,1,1]
-- 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
--
--
--
-- splitAt 0 = return
-- splitAt n >=> splitAt m = splitAt (m+n)
--
--
-- Thus, e.g.
--
--
-- >>> rest <- S.print $ splitsAt 2 >=> splitsAt 2 $ each [1..5]
-- 1
-- 2
-- 3
-- 4
--
-- >>> S.print rest
-- 5
--
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 ()
cutoff :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Maybe 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
zips :: (Monad m, Functor f, Functor g) => Stream f m r -> Stream g m r -> Stream (Compose f g) m r
unzips :: (Monad m, Functor f, Functor g) => Stream (Compose f g) m r -> Stream f (Stream 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
-- | Given a stream on a sum of functors, make it a stream on the left
-- functor, with the streaming on the other functor as the governing
-- monad. This is useful for acting on one or the other functor with a
-- fold. It generalizes partitionEithers massively, but actually
-- streams properly.
--
--
-- >>> let odd_even = S.maps (S.distinguish even) $ S.each [1..10::Int]
--
-- >>> :t separate odd_even
-- separate odd_even
-- :: Monad m => Stream (Of Int) (Stream (Of Int) m) ()
--
--
-- Now, for example, it is convenient to fold on the left and right
-- values separately:
--
--
-- >>> S.toList $ S.toList $ separate odd_even
-- [2,4,6,8,10] :> ([1,3,5,7,9] :> ())
--
--
-- Or we can write them to separate files or whatever:
--
--
-- >>> runResourceT $ S.writeFile "even.txt" . S.show $ S.writeFile "odd.txt" . S.show $ S.separate odd_even
--
-- >>> :! cat even.txt
-- 2
-- 4
-- 6
-- 8
-- 10
--
-- >>> :! cat odd.txt
-- 1
-- 3
-- 5
-- 7
-- 9
--
--
-- Of course, in the special case of Stream (Of a) m r, we can
-- achieve the above effects more simply by using copy
--
--
-- >>> S.toList . S.filter even $ S.toList . S.filter odd $ S.copy $ each [1..10::Int]
-- [2,4,6,8,10] :> ([1,3,5,7,9] :> ())
--
--
-- But separate and unseparate are functor-general.
separate :: (Monad m, Functor f, Functor g) => Stream (Sum f g) m r -> Stream f (Stream g m) r
unseparate :: (Monad m, Functor f, Functor g) => Stream f (Stream g m) r -> Stream (Sum f g) m r
-- | Swap the order of functors in a sum of functors.
--
--
-- >>> S.toListM' $ S.print $ separate $ maps S.switch $ maps (S.distinguish (=='a')) $ S.each "banana"
-- 'a'
-- 'a'
-- 'a'
-- "bnn" :> ()
--
-- >>> S.toListM' $ S.print $ separate $ maps (S.distinguish (=='a')) $ S.each "banana"
-- 'b'
-- 'n'
-- 'n'
-- "aaa" :> ()
--
switch :: Sum f g r -> Sum g f r
bracketStream :: (Functor f, MonadResource m) => IO a -> (a -> IO ()) -> (a -> Stream f m b) -> Stream f m b
-- | This is akin to the observe of Pipes.Internal . It
-- reeffects 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 :: (Monad m1, Functor f) => (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 :: (Monad m, Functor f1) => (f1 (Stream f m r) -> m (f (Stream f m r))) -> Stream f1 m r -> Stream f m r
destroyExposed :: (Monad m, Functor f) => Stream f m t -> (f b -> b) -> (m b -> b) -> (t -> b) -> b
instance (GHC.Show.Show r, GHC.Show.Show (m (Streaming.Internal.Stream f m r)), GHC.Show.Show (f (Streaming.Internal.Stream f m r))) => GHC.Show.Show (Streaming.Internal.Stream f m r)
instance (GHC.Classes.Eq r, GHC.Classes.Eq (m (Streaming.Internal.Stream f m r)), GHC.Classes.Eq (f (Streaming.Internal.Stream f m r))) => GHC.Classes.Eq (Streaming.Internal.Stream f m r)
instance (Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable m, Data.Data.Data r, Data.Data.Data (m (Streaming.Internal.Stream f m r)), Data.Data.Data (f (Streaming.Internal.Stream f m r))) => Data.Data.Data (Streaming.Internal.Stream f m r)
instance (GHC.Base.Functor f, GHC.Base.Monad m) => GHC.Base.Functor (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, GHC.Base.Monad m) => GHC.Base.Monad (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, GHC.Base.Monad m) => GHC.Base.Applicative (Streaming.Internal.Stream f m)
instance (GHC.Base.Applicative f, GHC.Base.Monad m) => GHC.Base.Alternative (Streaming.Internal.Stream f m)
instance (GHC.Base.Applicative f, GHC.Base.Monad m) => GHC.Base.MonadPlus (Streaming.Internal.Stream f m)
instance GHC.Base.Functor f => Control.Monad.Trans.Class.MonadTrans (Streaming.Internal.Stream f)
instance GHC.Base.Functor f => Control.Monad.Morph.MFunctor (Streaming.Internal.Stream f)
instance GHC.Base.Functor f => Control.Monad.Morph.MMonad (Streaming.Internal.Stream f)
instance (Control.Monad.IO.Class.MonadIO m, GHC.Base.Functor f) => Control.Monad.IO.Class.MonadIO (Streaming.Internal.Stream f m)
instance (Control.Monad.Base.MonadBase b m, GHC.Base.Functor f) => Control.Monad.Base.MonadBase b (Streaming.Internal.Stream f m)
instance (Control.Monad.Catch.MonadThrow m, GHC.Base.Functor f) => Control.Monad.Catch.MonadThrow (Streaming.Internal.Stream f m)
instance (Control.Monad.Catch.MonadCatch m, GHC.Base.Functor f) => Control.Monad.Catch.MonadCatch (Streaming.Internal.Stream f m)
instance (Control.Monad.Trans.Resource.Internal.MonadResource m, GHC.Base.Functor f) => Control.Monad.Trans.Resource.Internal.MonadResource (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, Control.Monad.Reader.Class.MonadReader r m) => Control.Monad.Reader.Class.MonadReader r (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, Control.Monad.State.Class.MonadState s m) => Control.Monad.State.Class.MonadState s (Streaming.Internal.Stream f m)
instance (GHC.Base.Functor f, Control.Monad.Error.Class.MonadError e m) => Control.Monad.Error.Class.MonadError e (Streaming.Internal.Stream f m)
-- | This module is very closely modeled on Pipes.Prelude, Pipes.Group and
-- Pipes.Parse. It maybe said to give independent expression to the
-- conception of Producer manipulation articulated in the latter two
-- modules. Because we dispense with piping and conduiting, the
-- distinction between all of these modules collapses. The leading type
-- is chosen to permit an api that is as close as possible to that of
-- Data.List and the Prelude.
--
-- Import qualified thus:
--
--
-- import Streaming
-- import qualified Streaming.Prelude as S
--
--
-- For the examples below, one sometimes needs
--
--
-- import Streaming.Prelude (each, yield, next, mapped, stdoutLn, stdinLn)
-- import Data.Function ((&))
--
--
-- Other libraries that come up in passing are
--
--
-- 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
--
--
-- Here are some correspondences between the types employed here and
-- elsewhere:
--
--
-- streaming | pipes | conduit | io-streams
-- -------------------------------------------------------------------------------------------------------------------
-- Stream (Of a) m () | Producer a m () | Source m a | InputStream a
-- | ListT m a | ConduitM () o m () | Generator r ()
-- -------------------------------------------------------------------------------------------------------------------
-- Stream (Of a) m r | Producer a m r | ConduitM () o m r | Generator a r
-- -------------------------------------------------------------------------------------------------------------------
-- Stream (Of a) m (Stream (Of a) m r) | Producer a m (Producer a m r) |
-- --------------------------------------------------------------------------------------------------------------------
-- Stream (Stream (Of a) m) r | FreeT (Producer a m) m r |
-- --------------------------------------------------------------------------------------------------------------------
-- --------------------------------------------------------------------------------------------------------------------
-- ByteString m () | Producer ByteString m () | Source m ByteString | InputStream ByteString
-- --------------------------------------------------------------------------------------------------------------------
--
module Streaming.Prelude
-- | A left-strict pair; the base functor for streams of individual
-- elements.
data Of a b
(:>) :: !a -> b -> Of a b
-- | A singleton stream
--
--
-- >>> stdoutLn $ yield "hello"
-- hello
--
--
--
-- >>> S.sum $ do {yield 1; yield 2}
-- 3
--
--
--
-- >>> let prompt = putStrLn "Enter a number:"
--
-- >>> let number = lift (prompt >> readLn) >>= yield :: Stream (Of Int) IO ()
--
-- >>> S.toList $ do {number; number; number}
-- Enter a number:
-- 1
-- Enter a number:
-- 2
-- Enter a number:
-- 3
-- [1,2,3] :> ()
--
yield :: Monad m => a -> Stream (Of a) m ()
-- | Stream the elements of a pure, foldable container.
--
--
-- >>> S.print $ each [1..3]
-- 1
-- 2
-- 3
--
-- >>> S.print $ mapped S.toList $ chunksOf 3 $ S.replicateM 5 getLine
-- s<Enter>
-- t<Enter>
-- u<Enter>
-- ["s","t","u"]
-- v<Enter>
-- w<Enter>
-- ["v","w"]
--
each :: (Monad m, Foldable f) => f a -> Stream (Of a) m ()
each' :: (Monad m, Foldable f) => f a -> Stream (Of a) m ()
-- | 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.effects $ S.unfoldr P.next (P.stdinLn P.>-> P.take 2 P.>-> P.stdoutLn)
-- hello<Enter>
-- hello
-- goodbye<Enter>
-- goodbye
--
unfoldr :: Monad m => (s -> m (Either r (a, s))) -> s -> Stream (Of a) m r
-- | View standard input as a 'Stream (Of String) m r'. stdoutLn, by
-- contrast, renders a 'Stream (Of String) m r' to standard output. The
-- names follow Pipes.Prelude
--
--
-- >>> 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
-- 10<Enter>
-- 12<Enter>
-- 22
--
--
--
-- >>> S.toList $ S.take 3 (S.readLn :: Stream (Of Int) IO ())
-- 1<Enter>
-- 2<Enter>
-- 1@#$%^&*\<Enter>
-- 3<Enter>
-- [1,2,3] :> ()
--
readLn :: (MonadIO m, Read a) => Stream (Of a) m ()
-- | Read Strings from a Handle using hGetLine
--
-- Terminates on end of input
--
--
-- >>> IO.withFile "/usr/share/dict/words" IO.ReadMode $ S.stdoutLn . S.take 3 . S.drop 50000 . S.fromHandle
-- deflagrator
-- deflate
-- deflation
--
fromHandle :: MonadIO m => Handle -> Stream (Of String) m ()
-- | Read the lines of a file as Haskell Strings
--
--
-- >>> runResourceT $ S.writeFile "lines.txt" $ S.take 2 S.stdinLn
-- hello<Enter>
-- world<Enter>
--
-- >>> runResourceT $ S.print $ S.readFile "lines.txt"
-- "hello"
-- "world"
--
--
-- runResourceT, as it is used here, means something like
-- closing_all_handles. It makes it possible to write
-- convenient, fairly sensible versions of readFile,
-- writeFile and appendFile. IO.withFile IO.ReadMode
-- ... is more complicated but is generally to be preferred. Its use
-- is explained here.
readFile :: MonadResource m => FilePath -> Stream (Of String) m ()
-- | Iterate a pure function from a seed value, streaming the results
-- forever
iterate :: Monad m => (a -> a) -> a -> Stream (Of a) m r
-- | Iterate a monadic function from a seed value, streaming the results
-- forever
iterateM :: Monad m => (a -> m a) -> m a -> Stream (Of a) m r
-- | Repeat an element ad inf. .
--
--
-- >>> S.print $ S.take 3 $ S.repeat 1
-- 1
-- 1
-- 1
--
repeat :: Monad m => a -> Stream (Of a) m r
-- | Repeat a monadic action ad inf., streaming its results.
--
--
-- >>> S.toList $ S.take 2 $ repeatM getLine
-- one<Enter>
-- two<Enter>
-- ["one","two"]
--
repeatM :: Monad m => m a -> Stream (Of a) m r
-- | Repeat an element several times
replicate :: Monad m => Int -> a -> Stream (Of a) m ()
untilRight :: Monad m => m (Either a r) -> 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 0 >> yield 1)
-- 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 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 ()
-- | An infinite stream of enumerable values, starting from a given value.
-- It is the same as `S.iterate succ`. Because their return type is
-- polymorphic, enumFrom and enumFromThen (and
-- iterate are useful for example with zip and
-- zipWith, which require the same return type in the zipped
-- streams. With each [1..] the following bit of
-- connect-and-resume would be impossible:
--
--
-- >>> rest <- S.print $ S.zip (S.enumFrom 'a') $ S.splitAt 3 $ S.enumFrom 1
-- ('a',1)
-- ('b',2)
-- ('c',3)
--
-- >>> S.print $ S.take 3 rest
-- 4
-- 5
-- 6
--
enumFrom :: (Monad m, Enum n) => n -> Stream (Of n) m r
-- | An infinite sequence of enumerable values at a fixed distance,
-- determined by the first and second values. See the discussion of
-- enumFrom
--
--
-- >>> S.print $ S.take 3 $ S.enumFromThen 100 200
-- 100
-- 200
-- 300
--
enumFromThen :: (Monad m, Enum a) => a -> a -> Stream (Of a) m r
-- | Streams the number of seconds from the beginning of action
--
-- Thus, to mark times of user input we might write something like:
--
--
-- >>> S.toList $ S.take 3 $ S.zip S.seconds S.stdinLn
-- a<Enter>
-- b<Enter>
-- c<Enter>
-- [(0.0,"a"),(1.088711,"b"),(3.7289649999999996,"c")] :> ()
--
--
-- To restrict user input to some number of seconds, we might write:
--
--
-- >>> S.toList $ S.map fst $ S.zip S.stdinLn $ S.takeWhile (< 3) S.seconds
-- one<Enter>
-- two<Enter>
-- three<Enter>
-- four<Enter>
-- five<Enter>
-- ["one","two","three","four","five"] :> ()
--
--
-- This is of course does not interrupt an action that has already begun.
seconds :: Stream (Of Double) IO r
-- | Write Strings to stdout using putStrLn;
-- terminates on a broken output pipe (This operation is modelled on
-- stdoutLn).
--
--
-- >>> S.stdoutLn $ S.take 3 $ S.each $ words "one two three four five"
-- one
-- two
-- three
--
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 <- S.stdoutLn' $ S.show $ S.splitAt 3 (each [1..5])
-- 1
-- 2
-- 3
--
-- >>> S.print rest
-- 4
-- 5
--
stdoutLn' :: MonadIO m => Stream (Of String) m r -> m r
-- | Reduce a stream to its return value with a monadic action.
--
--
-- >>> S.mapM_ Prelude.print $ each [1..5]
-- 1
-- 2
-- 3
-- 4
-- 5
--
-- >>> rest <- S.mapM_ Prelude.print $ S.splitAt 3 $ each [1..10]
-- 1
-- 2
-- 3
--
-- >>> S.sum rest
-- 49 :> ()
--
mapM_ :: Monad m => (a -> m b) -> Stream (Of a) m r -> m r
-- | Print the elements of a stream as they arise.
--
--
-- >>> S.print $ S.take 2 S.stdinLn
-- hello
-- "hello"
-- world
-- "world"
--
-- >>>
--
print :: (MonadIO m, Show a) => Stream (Of a) m r -> m r
-- | Write a succession of strings to a handle as separate lines.
--
--
-- >>> S.toHandle IO.stdout $ each $ words "one two three"
-- one
-- two
-- three
--
toHandle :: MonadIO m => Handle -> Stream (Of String) m r -> m r
-- | Write a series of strings as lines to a file. The handle is crudely
-- managed with ResourceT:
--
--
-- >>> runResourceT $ S.writeFile "lines.txt" $ S.take 2 S.stdinLn
-- hello<Enter>
-- world<Enter>
--
-- >>> runResourceT $ S.print $ S.readFile "lines.txt"
-- "hello"
-- "world"
--
writeFile :: MonadResource m => FilePath -> Stream (Of String) m r -> m r
-- | Take either the first item in a stream or the return value, if it is
-- empty. The typical mark of an infinite stream is a polymorphic return
-- value; in that case, first is a sort of safeHead
--
-- To iterate an action returning a Maybe, until it succeeds.
first :: Monad m => Stream (Of r) m r -> m r
-- | Reduce a stream, performing its actions but ignoring its elements.
--
--
-- >>> rest <- S.effects $ S.splitAt 2 $ each [1..5]
--
-- >>> S.print rest
-- 3
-- 4
-- 5
-- 'effects' should be understood together with 'copy' and is subject to the rules
--
--
--
-- S.effects . S.copy = id
-- hoist S.effects . S.copy = id
--
--
-- The similar effects and copy operations in
-- Data.ByteString.Streaming obey the same rules.
effects :: Monad m => Stream (Of a) m r -> m r
-- | Remove the elements from a stream of values, retaining the structure
-- of layers.
erase :: Monad m => Stream (Of a) m r -> Stream Identity m r
-- | Where a transformer returns a stream, run the effects of the stream,
-- keeping the return value. This is usually used at the type
--
--
-- drained :: Monad m => Stream (Of a) m (Stream (Of b) m r) -> Stream (Of a) m r
-- drained = join . fmap (lift . effects)
--
--
-- Here, for example, we split a stream in two places and throw out the
-- middle segment:
--
--
-- >>> rest <- S.print $ S.drained $ S.splitAt 2 $ S.splitAt 5 $ each [1..7]
-- 1
-- 2
--
-- >>> S.print rest
-- 6
-- 7
--
--
-- In particular, we can define versions of take and
-- takeWhile which retrieve the return value of the rest of the
-- stream - and which can thus be used with maps:
--
--
-- take' n = S.drained . S.splitAt n
-- takeWhile' thus = S.drained . S.span thus
--
drained :: (Monad m, Monad (t m), Functor (t m), MonadTrans t) => t m (Stream (Of a) m r) -> t m r
-- | Standard map on the elements of a stream.
--
--
-- >>> S.stdoutLn $ S.map reverse $ each (words "alpha beta")
-- ahpla
-- ateb
--
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
--
--
-- >>> S.print $ S.mapM readIORef $ S.chain (\ior -> modifyIORef ior (*100)) $ S.mapM newIORef $ each [1..6]
-- 100
-- 200
-- 300
-- 400
-- 500
-- 600
--
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. Compare
-- hoist, which has a similar effect on the monadic parameter.
--
--
-- maps id = id
-- maps f . maps g = maps (f . g)
--
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. This could be trivial, e.g.
--
--
-- let noteBeginning text x = putStrLn text >> return text
--
--
-- this puts the is completely functor-general
--
-- maps and mapped obey these rules:
--
--
-- maps id = id
-- mapped return = id
-- maps f . maps g = maps (f . g)
-- mapped f . mapped g = mapped (f <=< g)
-- maps f . mapped g = mapped (liftM f . g)
-- mapped f . maps g = mapped (f <=< liftM g)
--
--
-- maps is more fundamental than mapped, which is best
-- understood as a convenience for effecting this frequent composition:
--
--
-- mapped phi = decompose . maps (Compose . phi)
--
mapped :: (Monad m, Functor f) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g 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
-- | Replace each element in a stream of individual Haskell values (a
-- Stream (Of a) m r) with an associated functorial
-- step.
--
--
-- for str f = concats (with str f)
-- with str f = for str (yields . f)
-- with str f = maps (\(a:>r) -> r <$ f a) str
-- with = flip subst
-- subst = flip with
--
--
--
-- >>> with (each [1..3]) (yield . show) & intercalates (yield "--") & S.stdoutLn
-- 1
-- --
-- 2
-- --
-- 3
--
with :: (Monad m, Functor f) => Stream (Of a) m r -> (a -> f x) -> Stream f m r
-- | Replace each element in a stream of individual values with a
-- functorial layer of any sort. subst = flip with and is more
-- convenient in a sequence of compositions that transform a stream.
--
--
-- with = flip subst
-- for str f = concats $ subst f str
-- subst f = maps (\(a:>r) -> r <$ f a)
-- S.concat = concats . subst each
--
subst :: (Monad m, Functor f) => (a -> f x) -> Stream (Of a) m r -> Stream f m r
-- | Duplicate the content of stream, so that it can be acted on twice in
-- different ways, but without breaking streaming. Thus, with each
-- [1,2] I might do:
--
--
-- >>> S.print $ each ["one","two"]
-- "one"
-- "two"
--
-- >>> S.stdoutLn $ each ["one","two"]
-- one
-- two
--
--
-- With copy, I can as well do:
--
--
-- >>> S.print $ S.stdoutLn $ S.copy $ each ["one","two"]
-- one
-- "one"
-- two
-- "two"
--
--
-- copy should be understood together with effects and is
-- subject to the rules
--
--
-- S.effects . S.copy = id
-- hoist S.effects . S.copy = id
--
--
-- The similar operations in Streaming obey the same rules.
--
-- Where the actions you are contemplating are each simple folds over the
-- elements, or a selection of elements, then the coupling of the folds
-- is often more straightforwardly effected with Foldl, e.g.
--
--
-- >>> L.purely S.fold (liftA2 (,) L.sum L.product) $ each [1..10]
-- (55,3628800) :> ()
--
--
-- rather than
--
--
-- >>> S.sum $ S.product . S.copy $ each [1..10]
-- 55 :> (3628800 :> ())
--
--
-- A Control.Foldl fold can be altered to act on a selection of
-- elements by using handles on an appropriate lens. Some such
-- manipulations are simpler and more List-like, using
-- copy:
--
--
-- >>> L.purely S.fold (liftA2 (,) (L.handles (filtered odd) L.sum) (L.handles (filtered even) L.product)) $ each [1..10]
-- (25,3840) :> ()
--
--
-- becomes
--
--
-- >>> S.sum $ S.filter odd $ S.product $ S.filter even $ S.copy $ each [1..10]
-- 25 :> (3840 :> ())
--
--
-- or using store
--
--
-- >>> S.sum $ S.filter odd $ S.store (S.product . S.filter even) $ each [1..10]
-- 25 :> (3840 :> ())
--
--
-- But anything that fold of a Stream (Of a) m r into e.g. an
-- m (Of b r) that has a constraint on m that is
-- carried over into Stream f m - e.g. Monad,
-- MonadIO, MonadResource, etc. can be used on the
-- stream. Thus, I can fold over different groupings of the original
-- stream:
--
--
-- >>> (S.toList . mapped S.toList . chunksOf 5) $ (S.toList . mapped S.toList . chunksOf 3) $ S.copy $ each [1..10]
-- [[1,2,3,4,5],[6,7,8,9,10]] :> ([[1,2,3],[4,5,6],[7,8,9],[10]] :> ())
--
--
-- The procedure can be iterated as one pleases, as one can see from this
-- (otherwise unadvisable!) example:
--
--
-- >>> (S.toList . mapped S.toList . chunksOf 4) $ (S.toList . mapped S.toList . chunksOf 3) $ S.copy $ (S.toList . mapped S.toList . chunksOf 2) $ S.copy $ each [1..12]
-- [[1,2,3,4],[5,6,7,8],[9,10,11,12]] :> ([[1,2,3],[4,5,6],[7,8,9],[10,11,12]] :> ([[1,2],[3,4],[5,6],[7,8],[9,10],[11,12]] :> ()))
--
copy :: Monad m => Stream (Of a) m r -> Stream (Of a) (Stream (Of a) m) r
-- | copy' is the same as copy but reverses the order of
-- interleaved effects. The difference should not be observable at all
-- for pure folds over the data.
copy' :: Monad m => Stream (Of a) m r -> Stream (Of a) (Stream (Of a) m) r
-- | Store the result of any suitable fold over a stream, keeping the
-- stream for further manipulation. store f = f . copy :
--
--
-- >>> S.print $ S.store S.product $ each [1..4]
-- 1
-- 2
-- 3
-- 4
-- 24 :> ()
--
--
--
-- >>> S.print $ S.store S.sum $ S.store S.product $ each [1..4]
-- 1
-- 2
-- 3
-- 4
-- 10 :> (24 :> ())
--
--
-- Here the sum (10) and the product (24) have been 'stored' for use when
-- finally we have traversed the stream with print . Needless to
-- say, a second pass is excluded conceptually, so the folds
-- that you apply successively with store are performed
-- simultaneously, and in constant memory -- as they would be if, say,
-- you linked them together with Control.Fold:
--
--
-- >>> L.impurely S.foldM (liftA3 (\a b c -> (b,c)) (L.sink print) (L.generalize L.sum) (L.generalize L.product)) $ each [1..4]
-- 1
-- 2
-- 3
-- 4
-- (10,24) :> ()
--
--
-- Fusing folds after the fashion of Control.Foldl will
-- generally be a bit faster than the corresponding succession of uses of
-- store, but by constant factor that will be completely dwarfed
-- when any IO is at issue.
--
-- But store copy is much/ more powerful, as you
-- can see by reflecting on uses like this:
--
--
-- >>> S.sum $ S.store (S.sum . mapped S.product . chunksOf 2) $ S.store (S.product . mapped S.sum . chunksOf 2 )$ each [1..6]
-- 21 :> (44 :> (231 :> ()))
--
--
-- It will be clear that this cannot be reproduced with any combination
-- of lenses, Control.Fold folds, or the like. (See also the
-- discussion of copy.)
--
-- It would conceivable be clearer to import a series of specializations
-- of store. It is intended to be used at types like these:
--
--
-- storeM :: (forall s m . Monad m => Stream (Of a) m s -> m (Of b s))
-- -> (Monad n => Stream (Of a) n r -> Stream (Of a) n (Of b r))
-- storeM = store
--
-- storeMIO :: (forall s m . MonadIO m => Stream (Of a) m s -> m (Of b s))
-- -> ( MonadIO n => Stream (Of a) n r -> Stream (Of a) n (Of b r)
-- storeMIO = store
--
--
-- It is clear from these types that we are just using the general
-- instances:
--
--
-- instance (Functor f, Monad m ) => Monad (Stream f m)
-- instance (Functor f, MonadIO m) => MonadIO (Stream f m)
--
--
-- We thus can't be touching the elements of the stream, or the final
-- return value. It it is the same with other constraints that Stream
-- (Of a) inherits, like MonadResource. Thus I can filter and
-- write to one file, but nub and write to another, or to a database or
-- the like:
--
--
-- >>> runResourceT $ (S.writeFile "hello2.txt" . S.nub) $ store (S.writeFile "hello.txt" . S.filter (/= "world")) $ each ["hello", "world", "goodbye", "world"]
--
-- >>> :! cat hello.txt
-- hello
-- goodbye
--
-- >>> :! cat hello2.txt
-- hello
-- world
-- goodbye
--
store :: Monad m => (Stream (Of a) (Stream (Of a) m) r -> t) -> Stream (Of a) m r -> t
-- | Apply an action to all values, re-yielding each
--
--
-- >>> S.product $ S.chain Prelude.print $ S.each [1..5]
-- 1
-- 2
-- 3
-- 4
-- 5
-- 120 :> ()
--
chain :: Monad m => (a -> m ()) -> Stream (Of 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
--
--
-- This obeys the rule
sequence :: Monad m => Stream (Of (m a)) m r -> Stream (Of a) 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
-- | Interpolate a delay of n seconds between yields.
delay :: MonadIO m => Double -> Stream (Of a) m r -> Stream (Of a) m r
intersperse :: Monad m => a -> Stream (Of a) m r -> Stream (Of a) 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.toList $ S.take 3 $ each "with"
-- "wit" :> ()
--
--
--
-- >>> runResourceT $ S.stdoutLn $ S.take 3 $ S.readFile "stream.hs"
-- import Streaming
-- import qualified Streaming.Prelude as S
-- import Streaming.Prelude (each, next, yield)
--
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. By contrast span preserves this information, and
-- is generally more desirable.
--
--
-- S.takeWhile thus = void . S.span thus
--
--
-- To preserve the information - but thus also force the rest of the
-- stream to be developed - write
--
--
-- S.drained . S.span thus
--
--
-- as dropWhile thus is
--
--
-- S.effects . S.span thus
--
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
--
--
-- >>> S.toList $ S.drop 2 $ S.replicateM 5 getLine
-- a<Enter>
-- b<Enter>
-- c<Enter>
-- d<Enter>
-- e<Enter>
-- ["c","d","e"] :> ()
--
--
-- Because it retains the final return value, drop n is a
-- suitable argument for maps:
--
--
-- >>> S.toList $ concats $ maps (S.drop 4) $ chunksOf 5 $ each [1..20]
-- [5,10,15,20] :> ()
--
drop :: (Monad m) => Int -> Stream (Of a) m r -> Stream (Of a) m r
-- | Ignore elements of a stream until a test succeeds, retaining the rest.
--
--
-- >>> S.print $ S.dropWhile ((< 5) . length) S.stdinLn
-- one<Enter>
-- two<Enter>
-- three<Enter>
-- "three"
-- four<Enter>
-- "four"
-- ^CInterrupted.
--
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. This is just
--
--
-- concat str = for str each
--
--
--
-- >>> S.print $ S.concat (each ["xy","z"])
-- 'x'
-- 'y'
-- 'z'
--
--
-- Note that it also has the effect of catMaybes, rights
-- 'map snd' and such-like operations.
--
--
-- >>> 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
--
-- >>> S.print $ S.concat $ S.each [('A',1), ('B',2)]
-- 1
-- 2
--
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.
--
--
-- >>> S.print $ S.scan (++) "" id $ each (words "a b c d")
-- ""
-- "a"
-- "ab"
-- "abc"
-- "abcd"
--
--
-- scan is fitted for use with Control.Foldl, thus:
--
--
-- >>> 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 left scan, accepting a monadic function. It can be used with
-- FoldMs from Control.Foldl using impurely.
-- Here we yield a succession of vectors each recording
--
--
-- >>> 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
scanned :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Stream (Of a) m r -> Stream (Of (a, b)) m r
-- | Make a stream of strings into a stream of parsed values, skipping bad
-- cases
--
--
-- >>> S.sum_ $ S.read $ S.takeWhile (/= "total") S.stdinLn :: IO Int
-- 1000<Enter>
-- 2000<Enter>
-- total<Enter>
-- 3000
--
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
duplicate :: Monad m => Stream (Of a) m r -> Stream (Of a) (Stream (Of a) m) r
duplicate' :: Monad m => Stream (Of a) m r -> Stream (Of 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, which is better fitted to these
-- unfoldMs
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)
-- | Split a stream of elements wherever a given element arises. The action
-- is like that of words.
--
--
-- >>> S.stdoutLn $ mapped S.toList $ S.split ' ' $ each "hello world "
-- hello
-- world
--
split :: (Eq a, Monad m) => a -> Stream (Of a) m r -> Stream (Stream (Of a) m) m r
-- | Break a sequence upon meeting element falls under a predicate, keeping
-- it and 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)
-- | Yield elements, using a fold to maintain state, until the accumulated
-- value satifies the supplied predicate. The fold will then be
-- short-circuited and the element that breaks it will be put after the
-- break. This function is easiest to use with purely
--
--
-- >>> rest <- each [1..10] & L.purely S.breakWhen L.sum (>10) & S.print
-- 1
-- 2
-- 3
-- 4
--
-- >>> S.print rest
-- 5
-- 6
-- 7
-- 8
-- 9
-- 10
--
breakWhen :: Monad m => (x -> a -> x) -> x -> (x -> b) -> (b -> 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 successive equal items together
--
--
-- >>> S.toList $ mapped S.toList $ S.group $ each "baaaaad"
-- ["b","aaaaa","d"] :> ()
--
--
--
-- >>> S.toList $ concats $ maps (S.drained . S.splitAt 1) $ S.group $ each "baaaaaaad"
-- "bad" :> ()
--
group :: (Monad m, Eq a) => Stream (Of a) m r -> Stream (Stream (Of a) m) m r
-- | Group elements of a stream in accordance with the supplied comparison.
--
--
-- >>> S.print $ mapped S.toList $ S.groupBy (>=) $ each [1,2,3,1,2,3,4,3,2,4,5,6,7,6,5]
-- [1]
-- [2]
-- [3,1,2,3]
-- [4,3,2,4]
-- [5]
-- [6]
-- [7,6,5]
--
groupBy :: Monad m => (a -> a -> Bool) -> Stream (Of a) m r -> Stream (Stream (Of a) m) m r
distinguish :: (a -> Bool) -> Of a r -> Sum (Of a) (Of a) r
-- | Swap the order of functors in a sum of functors.
--
--
-- >>> S.toListM' $ S.print $ separate $ maps S.switch $ maps (S.distinguish (=='a')) $ S.each "banana"
-- 'a'
-- 'a'
-- 'a'
-- "bnn" :> ()
--
-- >>> S.toListM' $ S.print $ separate $ maps (S.distinguish (=='a')) $ S.each "banana"
-- 'b'
-- 'n'
-- 'n'
-- "aaa" :> ()
--
switch :: Sum f g r -> Sum g f r
-- | Given a stream on a sum of functors, make it a stream on the left
-- functor, with the streaming on the other functor as the governing
-- monad. This is useful for acting on one or the other functor with a
-- fold. It generalizes partitionEithers massively, but actually
-- streams properly.
--
--
-- >>> let odd_even = S.maps (S.distinguish even) $ S.each [1..10::Int]
--
-- >>> :t separate odd_even
-- separate odd_even
-- :: Monad m => Stream (Of Int) (Stream (Of Int) m) ()
--
--
-- Now, for example, it is convenient to fold on the left and right
-- values separately:
--
--
-- >>> S.toList $ S.toList $ separate odd_even
-- [2,4,6,8,10] :> ([1,3,5,7,9] :> ())
--
--
-- Or we can write them to separate files or whatever:
--
--
-- >>> runResourceT $ S.writeFile "even.txt" . S.show $ S.writeFile "odd.txt" . S.show $ S.separate odd_even
--
-- >>> :! cat even.txt
-- 2
-- 4
-- 6
-- 8
-- 10
--
-- >>> :! cat odd.txt
-- 1
-- 3
-- 5
-- 7
-- 9
--
--
-- Of course, in the special case of Stream (Of a) m r, we can
-- achieve the above effects more simply by using copy
--
--
-- >>> S.toList . S.filter even $ S.toList . S.filter odd $ S.copy $ each [1..10::Int]
-- [2,4,6,8,10] :> ([1,3,5,7,9] :> ())
--
--
-- But separate and unseparate are functor-general.
separate :: (Monad m, Functor f, Functor g) => Stream (Sum f g) m r -> Stream f (Stream g m) r
unseparate :: (Monad m, Functor f, Functor g) => Stream f (Stream g m) r -> Stream (Sum f g) m r
eitherToSum :: Of (Either a b) r -> Sum (Of a) (Of b) r
sumToEither :: Sum (Of a) (Of b) r -> Of (Either a b) r
sumToCompose :: Sum f f r -> Compose (Of Bool) f r
composeToSum :: Compose (Of Bool) f r -> Sum f f r
-- | Strict fold of a Stream of elements that preserves the return
-- value. The third parameter will often be id where a fold is
-- written by hand:
--
--
-- >>> S.fold (+) 0 id $ each [1..10]
-- 55 :> ()
--
--
--
-- >>> S.fold (*) 1 id $ S.fold (+) 0 id $ S.copy $ each [1..10]
-- 3628800 :> (55 :> ())
--
--
-- It can be used to replace a standard Haskell type with one more suited
-- to writing a strict accumulation function. It is also crucial to the
-- Applicative instance for Control.Foldl.Fold We can apply such
-- a fold purely
--
--
-- Control.Foldl.purely S.fold :: Monad m => Fold a b -> Stream (Of a) m r -> m (Of b r)
--
--
-- Thus, specializing a bit:
--
--
-- L.purely S.fold L.sum :: Stream (Of Int) Int r -> m (Of Int r)
-- mapped (L.purely S.fold L.sum) :: Stream (Stream (Of Int)) IO r -> Stream (Of Int) IO r
--
--
-- Here we use the Applicative instance for Control.Foldl.Fold
-- to stream three-item segments of a stream together with their sums and
-- products.
--
--
-- >>> S.print $ mapped (L.purely S.fold (liftA3 (,,) L.list L.product L.sum)) $ chunksOf 3 $ each [1..10]
-- ([1,2,3],6,6)
-- ([4,5,6],120,15)
-- ([7,8,9],504,24)
-- ([10],10,10)
--
fold :: Monad m => (x -> a -> x) -> x -> (x -> b) -> Stream (Of a) m r -> m (Of b r)
-- | Strict fold of a Stream of elements, preserving only the result
-- of the fold, not the return value of the stream. The third parameter
-- will often be id where a fold is written by hand:
--
--
-- >>> S.fold_ (+) 0 id $ each [1..10]
-- 55
--
--
-- It can be used to replace a standard Haskell type with one more suited
-- to writing a strict accumulation function. It is also crucial to the
-- Applicative instance for Control.Foldl.Fold
--
--
-- 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
-- | 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)
--
--
-- Thus to accumulate the elements of a stream as a vector, together with
-- a random element we might write:
--
--
-- >>> L.impurely S.foldM (liftA2 (,) L.vector L.random) $ each [1..10::Int] :: IO (Of (U.Vector Int,Maybe Int) ())
-- ([1,2,3,4,5,6,7,8,9,10],Just 9) :> ()
--
foldM :: Monad m => (x -> a -> m x) -> m x -> (x -> m 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 r -> m b
all :: Monad m => (a -> Bool) -> Stream (Of a) m r -> m (Of Bool r)
all_ :: Monad m => (a -> Bool) -> Stream (Of a) m r -> m Bool
any :: Monad m => (a -> Bool) -> Stream (Of a) m r -> m (Of Bool r)
any_ :: Monad m => (a -> Bool) -> Stream (Of a) m r -> m Bool
-- | Fold a Stream of numbers into their sum with the return value
--
--
-- mapped S.sum :: Stream (Stream (Of Int)) m r -> Stream (Of Int) m r
--
--
--
-- >>> S.sum $ each [1..10]
-- 55 :> ()
--
--
--
-- >>> (n :> rest) <- S.sum $ S.splitAt 3 $ each [1..10]
--
-- >>> print n
-- 6
--
-- >>> (m :> rest') <- S.sum $ S.splitAt 3 rest
--
-- >>> print m
-- 15
--
-- >>> S.print rest'
-- 7
-- 8
-- 9
--
sum :: (Monad m, Num a) => Stream (Of a) m r -> m (Of a 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 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)
-- | Fold a Stream of numbers into their product
product_ :: (Monad m, Num a) => Stream (Of a) m () -> m a
head :: Monad m => Stream (Of a) m r -> m (Of (Maybe a) r)
head_ :: Monad m => Stream (Of a) m r -> m (Maybe a)
last :: Monad m => Stream (Of a) m r -> m (Of (Maybe a) r)
last_ :: Monad m => Stream (Of a) m r -> m (Maybe a)
-- | Exhaust a stream remembering only whether a was an element.
elem :: (Monad m, Eq a) => a -> Stream (Of a) m r -> m (Of Bool r)
elem_ :: (Monad m, Eq a) => a -> Stream (Of a) m r -> m Bool
-- | Exhaust a stream deciding whether a was an element.
notElem :: (Monad m, Eq a) => a -> Stream (Of a) m r -> m (Of Bool r)
notElem_ :: (Monad m, Eq a) => a -> Stream (Of a) m r -> m Bool
-- | Run a stream, keeping its length and its return value.
--
--
-- >>> S.print $ mapped S.length $ chunksOf 3 $ S.each [1..10]
-- 3
-- 3
-- 3
-- 1
--
length :: Monad m => Stream (Of a) m r -> m (Of Int r)
-- | Run a stream, remembering only its length:
--
--
-- >>> S.length $ S.each [1..10]
-- 10
--
length_ :: Monad m => Stream (Of a) m r -> m Int
-- | Convert an effectful Stream into a list alongside the return
-- value
--
--
-- mapped toList :: Stream (Stream (Of a)) m r -> Stream (Of [a]) m
--
--
-- Like toList_, it breaks streaming; unlike toList_ it
-- preserves the return value and thus is frequently useful with e.g.
-- mapped
--
--
-- >>> S.print $ mapped S.toList $ chunksOf 3 $ each [1..9]
-- [1,2,3]
-- [4,5,6]
-- [7,8,9]
--
toList :: Monad m => Stream (Of a) m r -> m (Of [a] r)
-- | 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 Prelude mapM which, like
-- replicateM, sequence and similar operations on
-- traversable containers is a leading cause of space leaks.
toList_ :: Monad m => Stream (Of a) m () -> m [a]
-- | Fold streamed items into their monoidal sum
--
--
-- >>> S.mconcat $ S.take 2 $ S.map (Data.Monoid.Last . Just) (S.stdinLn)
-- first<Enter>
-- last<Enter>
-- Last {getLast = Just "last"} :> ()
--
mconcat :: (Monad m, Monoid w) => Stream (Of w) m r -> m (Of w r)
mconcat_ :: (Monad m, Monoid w) => Stream (Of w) m r -> m w
minimum :: (Monad m, Ord a) => Stream (Of a) m r -> m (Of (Maybe a) r)
minimum_ :: (Monad m, Ord a) => Stream (Of a) m r -> m (Maybe a)
maximum :: (Monad m, Ord a) => Stream (Of a) m r -> m (Of (Maybe a) r)
maximum_ :: (Monad m, Ord a) => Stream (Of a) m r -> m (Maybe a)
-- | 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 -> Streaming.yield a >> p) = id
-- 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)
-- | Zip three streams together
zip3 :: Monad m => (Stream (Of a) m r) -> (Stream (Of b) m r) -> (Stream (Of c) m r) -> (Stream (Of (a, b, c)) m r)
-- | Zip three Streams with a combining function
zipWith3 :: Monad m => (a -> b -> c -> d) -> Stream (Of a) m r -> Stream (Of b) m r -> Stream (Of c) m r -> Stream (Of d) m r
-- | The type
--
--
-- Data.List.unzip :: [(a,b)] -> ([a],[b])
--
--
-- might lead us to expect
--
--
-- Streaming.unzip :: Stream (Of (a,b)) m r -> Stream (Of a) m (Stream (Of b) m r)
--
--
-- which would not stream, since it would have to accumulate the second
-- stream (of bs). Of course, Data.List unzip
-- doesn't stream either.
--
-- This unzip does stream, though of course you can spoil this
-- by using e.g. toList:
--
--
-- >>> let xs = map (\x-> (x,show x)) [1..5::Int]
--
--
--
-- >>> S.toList $ S.toList $ S.unzip (S.each xs)
-- ["1","2","3","4","5"] :> ([1,2,3,4,5] :> ())
--
--
--
-- >>> Prelude.unzip xs
-- ([1,2,3,4,5],["1","2","3","4","5"])
--
--
-- Note the difference of order in the results. It may be of some use to
-- think why. The first application of toList was applied to a
-- stream of integers:
--
--
-- >>> :t S.unzip $ S.each xs
-- S.unzip $ S.each xs :: Monad m => Stream (Of Int) (Stream (Of String) m) ()
--
--
-- Like any fold, toList takes no notice of the monad of effects.
--
--
-- toList :: Monad m => Stream (Of a) m r -> m (Of [a] r)
--
--
-- In the case at hand (since I am in ghci) m = Stream (Of
-- String) IO. So when I apply toList, I exhaust that stream
-- of integers, folding it into a list:
--
--
-- >>> :t S.toList $ S.unzip $ S.each xs
-- S.toList $ S.unzip $ S.each xs
-- :: Monad m => Stream (Of String) m (Of [Int] ())
--
--
-- When I apply toList to this, I reduce everything to an
-- ordinary action in IO, and return a list of strings:
--
--
-- >>> S.toList $ S.toList $ S.unzip (S.each xs)
-- ["1","2","3","4","5"] :> ([1,2,3,4,5] :> ())
--
unzip :: Monad m => Stream (Of (a, b)) m r -> Stream (Of a) (Stream (Of b) m) r
-- | Separate left and right values in distinct streams. (separate
-- is a more powerful, functor-general, equivalent using Sum in
-- place of Either). So, for example, to permit unlimited user
-- input of Ints on condition of only two errors, we might
-- write:
--
--
-- >>> S.toList $ S.print $ S.take 2 $ partitionEithers $ S.map readEither $ S.stdinLn :: IO (Of [Int] ())
-- 1<Enter>
-- 2<Enter>
-- qqqqqqqqqq<Enter>
-- "Prelude.read: no parse"
-- 3<Enter>
-- rrrrrrrrrr<Enter>
-- "Prelude.read: no parse"
-- [1,2,3] :> ()
--
--
--
-- partitionEithers = separate . maps S.eitherToSum
-- lefts = hoist S.effects . partitionEithers
-- rights = S.effects . partitionEithers
-- rights = S.concat
--
partitionEithers :: Monad m => Stream (Of (Either a b)) m r -> Stream (Of a) (Stream (Of b) m) r
-- |
-- filter p = hoist effects (partition p)
--
partition :: Monad m => (a -> Bool) -> Stream (Of a) m r -> Stream (Of a) (Stream (Of a) m) r
-- | The catMaybes function takes a Stream of Maybes
-- and returns a Stream of all of the Just values.
catMaybes :: Monad m => Stream (Of (Maybe a)) m r -> Stream (Of a) m r
-- | The mapMaybe function is a version of map which can
-- throw out elements. In particular, the functional argument returns
-- something of type Maybe b. If this is Nothing,
-- no element is added on to the result Stream. If it is
-- Just b, then b is included in the result
-- Stream.
mapMaybe :: Monad m => (a -> Maybe b) -> Stream (Of a) m r -> Stream (Of b) m r
-- | Note that lazily, strictly, fst', and
-- mapOf are all so-called natural transformations on the
-- primitive Of a functor If we write
--
--
-- type f ~~> g = forall x . f x -> g x
--
--
-- then we can restate some types as follows:
--
--
-- mapOf :: (a -> b) -> Of a ~~> Of b -- bifunctor lmap
-- lazily :: Of a ~~> (,) a
-- Identity . fst' :: Of a ~~> Identity a
--
--
-- Manipulation of a Stream f m r by mapping often turns on
-- recognizing natural transformations of f. Thus maps
-- is far more general the the map of the
-- Streaming.Prelude, which can be defined thus:
--
--
-- S.map :: (a -> b) -> Stream (Of a) m r -> Stream (Of b) m r
-- S.map f = maps (mapOf f)
--
--
-- i.e.
--
--
-- S.map f = maps (\(a :> x) -> (f a :> x))
--
--
-- This rests on recognizing that mapOf is a natural
-- transformation; note though that it results in such a transformation
-- as well:
--
--
-- S.map :: (a -> b) -> Stream (Of a) m ~> Stream (Of b) m
--
--
-- Thus we can maps it in turn
--
--
--
--
lazily :: Of a b -> (a, b)
strictly :: (a, b) -> Of a b
fst' :: Of a b -> a
snd' :: Of a b -> b
-- | 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 Data.Traversable.Traversable (Streaming.Prelude.Of a)
instance (GHC.Show.Show a, GHC.Show.Show b) => GHC.Show.Show (Streaming.Prelude.Of a b)
instance (GHC.Read.Read a, GHC.Read.Read b) => GHC.Read.Read (Streaming.Prelude.Of a b)
instance (GHC.Classes.Ord a, GHC.Classes.Ord b) => GHC.Classes.Ord (Streaming.Prelude.Of a b)
instance Data.Foldable.Foldable (Streaming.Prelude.Of a)
instance (GHC.Classes.Eq a, GHC.Classes.Eq b) => GHC.Classes.Eq (Streaming.Prelude.Of a b)
instance (Data.Data.Data a, Data.Data.Data b) => Data.Data.Data (Streaming.Prelude.Of a b)
instance (GHC.Base.Monoid a, GHC.Base.Monoid b) => GHC.Base.Monoid (Streaming.Prelude.Of a b)
instance GHC.Base.Functor (Streaming.Prelude.Of a)
instance GHC.Base.Monoid a => GHC.Base.Applicative (Streaming.Prelude.Of a)
instance GHC.Base.Monoid a => GHC.Base.Monad (Streaming.Prelude.Of a)
instance (r ~ (), GHC.Base.Monad m, f ~ Streaming.Prelude.Of GHC.Types.Char) => Data.String.IsString (Streaming.Internal.Stream f m r)
module Streaming
data Stream f m r
-- | yields is like lift for items in the streamed
-- functor. It makes a singleton or one-layer succession.
--
--
-- lift :: (Monad m, Functor f) => m r -> Stream f m r
-- yields :: (Monad m, Functor f) => f r -> Stream f m r
--
--
-- Viewed in another light, it is like a functor-general version of
-- yield:
--
--
-- S.yield a = yields (a :> ())
--
yields :: (Monad m, Functor f) => f r -> Stream f m r
-- | Wrap an effect that returns a stream
--
--
-- effect = join . lift
--
effect :: (Monad m, Functor f) => m (Stream f m r) -> Stream f m r
wrap :: (Monad m, Functor f) => f (Stream f m r) -> Stream f m r
-- | Repeat a functorial layer, command or instruction a fixed number of
-- times.
--
--
-- replicates n = takes n . repeats
--
replicates :: (Monad m, Functor f) => Int -> f () -> Stream f m ()
-- | Repeat a functorial layer (a "command" or "instruction") forever.
repeats :: (Monad m, Functor f) => f () -> Stream f m r
-- | Repeat an effect containing a functorial layer, command or instruction
-- forever.
repeatsM :: (Monad m, Functor f) => m (f ()) -> 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
-- | never interleaves the pure applicative action with the return
-- of the monad forever. It is the empty of the Alternative
-- instance, thus
--
--
-- never <|> a = a
-- a <|> never = a
--
--
-- and so on. If w is a monoid then never :: Stream (Of w) m r
-- is the infinite sequence of mempty, and str1 <|>
-- str2 appends the elements monoidally until one of streams ends.
-- Thus we have, e.g.
--
--
-- >>> S.stdoutLn $ S.take 2 $ S.stdinLn <|> S.repeat " " <|> S.stdinLn <|> S.repeat " " <|> S.stdinLn
-- 1<Enter>
-- 2<Enter>
-- 3<Enter>
-- 1 2 3
-- 4<Enter>
-- 5<Enter>
-- 6<Enter>
-- 4 5 6
--
--
-- This is equivalent to
--
--
-- >>> S.stdoutLn $ S.take 2 $ foldr (<|>) never [S.stdinLn, S.repeat " ", S.stdinLn, S.repeat " ", S.stdinLn ]
--
--
-- Where f is a monad, (<|>) sequences the
-- conjoined streams stepwise. See the definition of paste
-- here, where the separate steps are bytestreams corresponding to
-- the lines of a file.
--
-- Given, say,
--
--
-- data Branch r = Branch r r deriving Functor -- add obvious applicative instance
--
--
-- then never :: Stream Branch Identity r is the pure infinite
-- binary tree with (inaccessible) rs in its leaves. Given two
-- binary trees, tree1 <|> tree2 intersects them,
-- preserving the leaves that came first, so tree1 <|> never =
-- tree1
--
-- Stream Identity m r is an action in m that is
-- indefinitely delayed. Such an action can be constructed with e.g.
-- untilJust.
--
--
-- untilJust :: (Monad m, Applicative f) => m (Maybe r) -> Stream f m r
--
--
-- Given two such items, <|> instance races them. It is
-- thus the iterative monad transformer specially defined in
-- Control.Monad.Trans.Iter
--
-- So, for example, we might write
--
--
-- >>> let justFour str = if length str == 4 then Just str else Nothing
--
-- >>> let four = untilJust (liftM justFour getLine)
--
-- >>> run four
-- one<Enter>
-- two<Enter>
-- three<Enter>
-- four<Enter>
-- "four"
--
--
-- The Alternative instance in Control.Monad.Trans.Free is
-- avowedly wrong, though no explanation is given for this.
never :: (Monad m, Applicative f) => Stream f m r
-- | Repeat a
untilJust :: (Monad m, Applicative f) => m (Maybe r) -> Stream f m r
-- | Reflect a church-encoded stream; cp. GHC.Exts.build
--
--
-- streamFold return_ effect_ step_ (streamBuild psi) = psi return_ effect_ step_
--
streamBuild :: (forall b. (r -> b) -> (m b -> b) -> (f b -> b) -> b) -> Stream f m r
delays :: (MonadIO m, Applicative f) => Double -> Stream f m r
-- | Map layers of one functor to another with a transformation. Compare
-- hoist, which has a similar effect on the monadic parameter.
--
--
-- maps id = id
-- maps f . maps g = maps (f . g)
--
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 maps is more fundamental than mapsM,
-- which is best understood as a convenience for effecting this frequent
-- composition:
--
--
-- mapsM phi = decompose . maps (Compose . phi)
--
--
-- The streaming prelude exports the same function under the better name
-- mapped, which overlaps with the lens libraries.
mapsM :: (Monad m, Functor f) => (forall x. f x -> m (g x)) -> Stream f m r -> Stream g m r
-- | Map layers of one functor to another with a transformation involving
-- the base monad. This could be trivial, e.g.
--
--
-- let noteBeginning text x = putStrLn text >> return text
--
--
-- this puts the is completely functor-general
--
-- maps and mapped obey these rules:
--
--
-- maps id = id
-- mapped return = id
-- maps f . maps g = maps (f . g)
-- mapped f . mapped g = mapped (f <=< g)
-- maps f . mapped g = mapped (liftM f . g)
-- mapped f . maps g = mapped (f <=< liftM g)
--
--
-- maps is more fundamental than mapped, which is best
-- understood as a convenience for effecting this frequent composition:
--
--
-- mapped phi = decompose . maps (Compose . phi)
--
mapped :: (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.
distribute :: (Monad m, Functor f, MonadTrans t, MFunctor t, Monad (t (Stream f m))) => Stream f (t m) r -> t (Stream f m) r
-- | Group layers in an alternating stream into adjoining sub-streams of
-- one type or another.
groups :: (Monad m, Functor f, Functor g) => Stream (Sum f g) m r -> Stream (Sum (Stream f m) (Stream g m)) 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)))
-- | 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
--
--
--
-- splitAt 0 = return
-- splitAt n >=> splitAt m = splitAt (m+n)
--
--
-- Thus, e.g.
--
--
-- >>> rest <- S.print $ splitsAt 2 >=> splitsAt 2 $ each [1..5]
-- 1
-- 2
-- 3
-- 4
--
-- >>> S.print rest
-- 5
--
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 $ mapped S.sum $ chunksOf 2 $ each [1,1,1,1,1]
-- 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 :: (Monad m, Functor f) => Stream (Stream f m) m 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 x -> Stream (t m) m r -> t m r
cutoff :: (Monad m, Functor f) => Int -> Stream f m r -> Stream f m (Maybe 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
zips :: (Monad m, Functor f, Functor g) => Stream f m r -> Stream g m r -> Stream (Compose f g) m r
unzips :: (Monad m, Functor f, Functor g) => Stream (Compose f g) m r -> Stream f (Stream 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
-- | Given a stream on a sum of functors, make it a stream on the left
-- functor, with the streaming on the other functor as the governing
-- monad. This is useful for acting on one or the other functor with a
-- fold. It generalizes partitionEithers massively, but actually
-- streams properly.
--
--
-- >>> let odd_even = S.maps (S.distinguish even) $ S.each [1..10::Int]
--
-- >>> :t separate odd_even
-- separate odd_even
-- :: Monad m => Stream (Of Int) (Stream (Of Int) m) ()
--
--
-- Now, for example, it is convenient to fold on the left and right
-- values separately:
--
--
-- >>> S.toList $ S.toList $ separate odd_even
-- [2,4,6,8,10] :> ([1,3,5,7,9] :> ())
--
--
-- Or we can write them to separate files or whatever:
--
--
-- >>> runResourceT $ S.writeFile "even.txt" . S.show $ S.writeFile "odd.txt" . S.show $ S.separate odd_even
--
-- >>> :! cat even.txt
-- 2
-- 4
-- 6
-- 8
-- 10
--
-- >>> :! cat odd.txt
-- 1
-- 3
-- 5
-- 7
-- 9
--
--
-- Of course, in the special case of Stream (Of a) m r, we can
-- achieve the above effects more simply by using copy
--
--
-- >>> S.toList . S.filter even $ S.toList . S.filter odd $ S.copy $ each [1..10::Int]
-- [2,4,6,8,10] :> ([1,3,5,7,9] :> ())
--
--
-- But separate and unseparate are functor-general.
separate :: (Monad m, Functor f, Functor g) => Stream (Sum f g) m r -> Stream f (Stream g m) r
unseparate :: (Monad m, Functor f, Functor g) => Stream f (Stream g m) r -> Stream (Sum f g) m r
-- | Rearrange a succession of layers of the form Compose m (f x).
--
-- we could as well define decompose by mapsM:
--
--
-- decompose = mapped getCompose
--
--
-- but mapped is best understood as:
--
--
-- mapped phi = decompose . maps (Compose . phi)
--
--
-- since maps and hoist are the really fundamental
-- operations that preserve the shape of the stream:
--
--
-- maps :: (Monad m, Functor f) => (forall x. f x -> g x) -> Stream f m r -> Stream g m r
-- hoist :: (Monad m, Functor f) => (forall a. m a -> n a) -> Stream f m r -> Stream f n r
--
decompose :: (Monad m, Functor f) => Stream (Compose m f) m r -> Stream f m r
-- | Map each layer to an effect, 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.
run :: Monad m => Stream m m r -> m r
-- | streamFold 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 streamFold return join
-- (Monad m, Functor f) =>
-- (f (m a) -> m a) -> Stream f m a -> m a -- iterT
--
--
--
-- >>> :t streamFold return (join . lift)
-- (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 streamFold return effect
-- (Monad m, Functor f, Functor g) =>
-- (f (Stream g m r) -> Stream g m r) -> Stream f m r -> Stream g m r
--
--
--
-- >>> :t \f -> streamFold return effect (wrap . f)
-- (Monad m, Functor f, Functor g) =>
-- (f (Stream g m a) -> g (Stream g m a))
-- -> Stream f m a -> Stream g m a -- maps
--
--
--
-- >>> :t \f -> streamFold return effect (effect . liftM wrap . f)
-- (Monad m, Functor f, Functor g) =>
-- (f (Stream g m a) -> m (g (Stream g m a)))
-- -> Stream f m a -> Stream g m a -- mapped
--
streamFold :: (Functor f, Monad m) => (r -> b) -> (m b -> b) -> (f b -> b) -> Stream f m r -> b
-- | Specialized fold following the usage of
-- Control.Monad.Trans.Free
--
--
-- iterTM alg = streamFold return (join . lift)
--
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 following the usage of
-- Control.Monad.Trans.Free
--
--
-- iterT alg = streamFold return join alg
--
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
destroy :: (Functor f, Monad m) => Stream f m r -> (f b -> b) -> (m b -> b) -> (r -> b) -> b
-- | A left-strict pair; the base functor for streams of individual
-- elements.
data Of a b
(:>) :: !a -> b -> Of a b
-- | Note that lazily, strictly, fst', and
-- mapOf are all so-called natural transformations on the
-- primitive Of a functor If we write
--
--
-- type f ~~> g = forall x . f x -> g x
--
--
-- then we can restate some types as follows:
--
--
-- mapOf :: (a -> b) -> Of a ~~> Of b -- bifunctor lmap
-- lazily :: Of a ~~> (,) a
-- Identity . fst' :: Of a ~~> Identity a
--
--
-- Manipulation of a Stream f m r by mapping often turns on
-- recognizing natural transformations of f. Thus maps
-- is far more general the the map of the
-- Streaming.Prelude, which can be defined thus:
--
--
-- S.map :: (a -> b) -> Stream (Of a) m r -> Stream (Of b) m r
-- S.map f = maps (mapOf f)
--
--
-- i.e.
--
--
-- S.map f = maps (\(a :> x) -> (f a :> x))
--
--
-- This rests on recognizing that mapOf is a natural
-- transformation; note though that it results in such a transformation
-- as well:
--
--
-- S.map :: (a -> b) -> Stream (Of a) m ~> Stream (Of b) m
--
--
-- Thus we can maps it in turn
--
--
--
--
lazily :: Of a b -> (a, b)
strictly :: (a, b) -> Of a b
bracketStream :: (Functor f, MonadResource m) => IO a -> (a -> IO ()) -> (a -> Stream f m b) -> Stream f m 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 :: (* -> *) -> * -> *)
-- | Lift a monad morphism from m to n into a monad
-- morphism from (t m) to (t n)
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 a newly created MMonad layer within an existing layer
--
-- embed is analogous to (=<<)
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 monad
-- transformation:
--
--
class MonadTrans (t :: (* -> *) -> * -> *)
-- | Lift a computation from the argument monad to the constructed monad.
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 :: * -> *)
-- | Lift a computation from the IO monad.
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)
-- | Lifted sum of functors.
data Sum (f :: * -> *) (g :: * -> *) a :: (* -> *) -> (* -> *) -> * -> *
InL :: f a -> Sum a
InR :: g a -> Sum a
-- | Identity functor and monad. (a non-strict monad)
newtype Identity a :: * -> *
Identity :: a -> Identity a
[runIdentity] :: Identity a -> a
-- | A monoid on applicative functors.
--
-- If defined, some and many should be the least solutions
-- of the equations:
--
--
class Applicative f => Alternative (f :: * -> *)
-- | An associative binary operation
(<|>) :: Alternative f => f a -> f a -> f a
-- | A class for monads in which exceptions may be thrown.
--
-- Instances should obey the following law:
--
--
-- throwM e >> x = throwM e
--
--
-- In other words, throwing an exception short-circuits the rest of the
-- monadic computation.
class Monad m => MonadThrow (m :: * -> *)
-- | Throw an exception. Note that this throws when this action is run in
-- the monad m, not when it is applied. It is a generalization
-- of Control.Exception's throwIO.
--
-- Should satisfy the law:
--
--
-- throwM e >> f = throwM e
--
throwM :: (MonadThrow m, Exception e) => e -> m a
-- | A Monad which allows for safe resource allocation. In theory,
-- any monad transformer stack which includes a ResourceT can be
-- an instance of MonadResource.
--
-- Note: runResourceT has a requirement for a
-- MonadBaseControl IO m monad, which allows control operations
-- to be lifted. A MonadResource does not have this requirement.
-- This means that transformers such as ContT can be an instance
-- of MonadResource. However, the ContT wrapper will
-- need to be unwrapped before calling runResourceT.
--
-- Since 0.3.0
class (MonadThrow m, MonadIO m, Applicative m, MonadBase IO m) => MonadResource (m :: * -> *)
-- | Lift a ResourceT IO action into the current Monad.
--
-- Since 0.4.0
liftResourceT :: MonadResource m => ResourceT IO a -> m a
class (Applicative b, Applicative m, Monad b, Monad m) => MonadBase (b :: * -> *) (m :: * -> *) | m -> b
-- | Lift a computation from the base monad
liftBase :: MonadBase b m => b α -> m α
-- | The Resource transformer. This transformer keeps track of all
-- registered actions, and calls them upon exit (via
-- runResourceT). Actions may be registered via
-- register, or resources may be allocated atomically via
-- allocate. allocate corresponds closely to
-- bracket.
--
-- Releasing may be performed before exit via the release
-- function. This is a highly recommended optimization, as it will ensure
-- that scarce resources are freed early. Note that calling
-- release will deregister the action, so that a release action
-- will only ever be called once.
--
-- Since 0.3.0
data ResourceT (m :: * -> *) a :: (* -> *) -> * -> *
-- | Unwrap a ResourceT transformer, and call all registered release
-- actions.
--
-- Note that there is some reference counting involved due to
-- resourceForkIO. If multiple threads are sharing the same
-- collection of resources, only the last call to runResourceT
-- will deallocate the resources.
--
-- Since 0.3.0
runResourceT :: MonadBaseControl IO m => ResourceT m a -> m 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
-- | Promote a function to a monad.
liftM :: Monad m => (a1 -> r) -> m a1 -> m r
-- | Promote a function to a monad, scanning the monadic arguments from
-- left to right. For example,
--
--
-- liftM2 (+) [0,1] [0,2] = [0,2,1,3]
-- liftM2 (+) (Just 1) Nothing = Nothing
--
liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r
-- | 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.
--
-- Examples
--
-- Replace the contents of a Maybe Int with
-- unit:
--
--
-- >>> void Nothing
-- Nothing
--
-- >>> void (Just 3)
-- Just ()
--
--
-- Replace the contents of an Either Int
-- Int with unit, resulting in an Either
-- Int '()':
--
--
-- >>> void (Left 8675309)
-- Left 8675309
--
-- >>> void (Right 8675309)
-- Right ()
--
--
-- Replace every element of a list with unit:
--
--
-- >>> void [1,2,3]
-- [(),(),()]
--
--
-- Replace the second element of a pair with unit:
--
--
-- >>> void (1,2)
-- (1,())
--
--
-- Discard the result of an IO action:
--
--
-- >>> mapM print [1,2]
-- 1
-- 2
-- [(),()]
--
-- >>> void $ mapM print [1,2]
-- 1
-- 2
--
void :: Functor f => f a -> f ()
-- | An infix synonym for mappend.
(<>) :: Monoid m => m -> m -> m