ffcb268 · streamly · git.iko.soy

git.iko.soy/streamly

Rename hoist/generally to morphInner/generalizeInner

Release morphInner, update docs

commitffcb268a4cc0222bf82c22d00fa895c7bf33ea5a authorHarendra Kumar <harendra@composewell.com> dateWed 7 Dec 2022, 18:45 (4 years ago) parent9ccaae1

9 files changed+52−40

compare with master

unifiedsplit

benchmark/Streamly/Benchmark/Data/Stream/Eliminate.hs+2−2 benchmark/Streamly/Benchmark/Data/Stream/Lift.hs+3−2 core/src/Streamly/Data/Array.hs+6−6 core/src/Streamly/Data/Fold.hs+3 core/src/Streamly/Data/Stream.hs+2−3 core/src/Streamly/Internal/Data/Fold.hs+2−2 core/src/Streamly/Internal/Data/Fold/Type.hs+12−11 core/src/Streamly/Internal/Data/Stream/Lift.hs+18−10 core/src/Streamly/Internal/Data/Stream/Transformer.hs+4−4

benchmark/Streamly/Benchmark/Data/Stream/Eliminate.hs+2−2

@@ -465,8 +465,8 @@ o_1_space_elimination_folds value =

465465

466466 -- deconstruction

467467 , benchIOSink value "uncons" uncons

468− , benchHoistSink value "length . generally"

469− (S.fold Fold.length . S.generally)

468+ , benchHoistSink value "length . generalizeInner"

469+ (S.fold Fold.length . S.generalizeInner)

470470#ifdef USE_PRELUDE

471471 , benchIOSink value "init" init

472472

benchmark/Streamly/Benchmark/Data/Stream/Lift.hs+3−2

@@ -76,8 +76,9 @@ o_1_space_hoisting value =

7676 [ bgroup "hoisting"

7777 [ benchIOSrc "evalState" (evalStateT value)

7878 , benchIOSrc "withState" (withState value)

79− , benchHoistSink value "generally"

80− ((\xs -> Stream.fold Fold.length xs :: IO Int) . Stream.generally)

79+ , benchHoistSink value "generalizeInner"

80+ ((\xs -> Stream.fold Fold.length xs :: IO Int)

81+ . Stream.generalizeInner)

8182 ]

8283 ]

8384

core/src/Streamly/Data/Array.hs+6−6

@@ -47,18 +47,18 @@

4747--

4848-- Array creation folds require 'MonadIO' because they need to sequence effects

4949-- in IO streams. To operate on streams in pure Monads like 'Identity' you can

50−-- hoist it to IO monad as follows:

50+-- morph it to IO monad as follows:

5151--

52−-- The 'MonadIO' based folds can be hoisted to 'Identity' stream folds:

52+-- The 'MonadIO' based folds can be morphed to 'Identity' stream folds:

5353--

54−-- >>> purely = Fold.hoist (Identity . unsafePerformIO)

54+-- >>> purely = Fold.morphInner (Identity . unsafePerformIO)

5555-- >>> Stream.fold (purely Array.write) $ Stream.fromList [1,2,3::Int]

5656-- Identity fromList [1,2,3]

5757--

5858-- Alternatively, 'Identity' streams can be generalized to IO streams:

5959--

6060-- >>> pure = Stream.fromList [1,2,3] :: Stream Identity Int

61−-- >>> generally = Stream.hoist (return . runIdentity)

61+-- >>> generally = Stream.morphInner (return . runIdentity)

6262-- >>> Stream.fold Array.write (generally pure :: Stream IO Int)

6363-- fromList [1,2,3]

6464--

@@ -146,9 +146,9 @@ import Prelude hiding (read)

146146-- >>> import System.IO.Unsafe (unsafePerformIO)

147147-- >>> import qualified Streamly.Data.Array as Array

148148-- >>> import qualified Streamly.Data.Fold as Fold

149−-- >>> import qualified Streamly.Internal.Data.Fold as Fold (hoist)

149+-- >>> import qualified Streamly.Internal.Data.Fold as Fold (morphInner)

150150-- >>> import qualified Streamly.Data.Stream as Stream

151−-- >>> import qualified Streamly.Internal.Data.Stream as Stream (hoist)

151+-- >>> import qualified Streamly.Internal.Data.Stream as Stream (morphInner)

152152

153153-- | Same as 'reader'

154154--

core/src/Streamly/Data/Fold.hs+3

@@ -298,6 +298,9 @@ module Streamly.Data.Fold

298298 -- ** Nesting

299299 , concatMap

300300

301+ -- * Transforming the Monad

302+ , morphInner

303+

301304 -- * Deprecated

302305 , foldr

303306 , drainBy

core/src/Streamly/Data/Stream.hs+2−3

@@ -448,10 +448,9 @@ module Streamly.Data.Stream

448448 , bracketIO

449449 , bracket3IO

450450

451− -- * Lifting Inner Monad

452− -- | See also: "Streamly.Internal.Data.Stream.Lift" for

453− -- @Pre-release@ functions.

451+ -- * Transforming Inner Monad

454452

453+ , morphInner

455454 , liftInner

456455 , runReaderT

457456 , runStateT

core/src/Streamly/Internal/Data/Fold.hs+2−2

@@ -172,8 +172,8 @@ module Streamly.Internal.Data.Fold

172172 , with

173173

174174 -- ** Transforming the Monad

175− , hoist

176− , generally

175+ , morphInner

176+ , generalizeInner

177177

178178 -- ** Mapping on output

179179 , rmapM

core/src/Streamly/Internal/Data/Fold/Type.hs+12−11

@@ -410,9 +410,9 @@ module Streamly.Internal.Data.Fold.Type

410410 , close

411411 , isClosed

412412

413− -- * Lifting inner monad

414− , hoist

415− , generally

413+ -- * Transforming inner monad

414+ , morphInner

415+ , generalizeInner

416416

417417 -- * Deprecated

418418 , foldr

@@ -440,6 +440,7 @@ import Prelude hiding (concatMap, filter, foldr, map, take)

440440-- $setup

441441-- >>> :m

442442-- >>> :set -XFlexibleContexts

443+-- >>> import Data.Functor.Identity (runIdentity)

443444-- >>> import Data.Maybe (fromJust, isJust)

444445-- >>> import Data.Monoid (Endo(..))

445446-- >>> import Streamly.Data.Fold (Fold)

@@ -1824,20 +1825,20 @@ refold (Refold step inject extract) f =

18241825 Fold step (extractM f >>= inject) extract

18251826

18261827------------------------------------------------------------------------------

1827−-- hoist

1828+-- morphInner

18281829------------------------------------------------------------------------------

18291830

1830−-- | Change the underlying monad of a fold

1831+-- | Change the underlying monad of a fold. Also known as hoist.

18311832--

18321833-- /Pre-release/

1833−hoist :: (forall x. m x -> n x) -> Fold m a b -> Fold n a b

1834−hoist f (Fold step initial extract) =

1834+morphInner :: (forall x. m x -> n x) -> Fold m a b -> Fold n a b

1835+morphInner f (Fold step initial extract) =

18351836 Fold (\x a -> f $ step x a) (f initial) (f . extract)

18361837

1837−-- | Adapt a pure fold to any monad

1838+-- | Adapt a pure fold to any monad.

18381839--

1839−-- >>> generally = Fold.hoist (return . runIdentity)

1840+-- >>> generalizeInner = Fold.morphInner (return . runIdentity)

18401841--

18411842-- /Pre-release/

1842−generally :: Monad m => Fold Identity a b -> Fold m a b

1843−generally = hoist (return . runIdentity)

1843+generalizeInner :: Monad m => Fold Identity a b -> Fold m a b

1844+generalizeInner = morphInner (return . runIdentity)

core/src/Streamly/Internal/Data/Stream/Lift.hs+18−10

@@ -9,8 +9,8 @@

99module Streamly.Internal.Data.Stream.Lift

1010 (

1111 -- * Generalize Inner Monad

12− hoist

13− , generally

12+ morphInner

13+ , generalizeInner

1414

1515 -- * Transform Inner Monad

1616 , liftInnerWith

@@ -28,6 +28,7 @@ import qualified Streamly.Internal.Data.Stream.StreamK as K

2828

2929-- $setup

3030-- >>> :m

31+-- >>> import Data.Functor.Identity (runIdentity)

3132-- >>> import Streamly.Internal.Data.Stream as Stream

3233

3334------------------------------------------------------------------------------

@@ -36,23 +37,30 @@ import qualified Streamly.Internal.Data.Stream.StreamK as K

3637

3738-- | Transform the inner monad of a stream using a natural transformation.

3839--

39−-- / Internal/

40+-- Example, generalize the inner monad from Identity to any other:

41+--

42+-- >>> generalizeInner = Stream.morphInner (return . runIdentity)

43+--

44+-- Also known as hoist.

4045--

4146-- /CPS/

42−{-# INLINE hoist #-}

43−hoist :: (Monad m, Monad n)

47+{-# INLINE morphInner #-}

48+morphInner :: (Monad m, Monad n)

4449 => (forall x. m x -> n x) -> Stream m a -> Stream n a

45−hoist f xs = fromStreamK $ K.hoist f (toStreamK xs)

50+morphInner f xs = fromStreamK $ K.hoist f (toStreamK xs)

4651

4752-- | Generalize the inner monad of the stream from 'Identity' to any monad.

4853--

49−-- / Internal/

54+-- Definition:

55+--

56+-- >>> generalizeInner = Stream.morphInner (return . runIdentity)

5057--

5158-- /CPS/

5259--

53−{-# INLINE generally #-}

54−generally :: Monad m => Stream Identity a -> Stream m a

55−generally xs = fromStreamK $ K.hoist (return . runIdentity) (toStreamK xs)

60+{-# INLINE generalizeInner #-}

61+generalizeInner :: Monad m => Stream Identity a -> Stream m a

62+generalizeInner = morphInner (return . runIdentity)

63+ -- fromStreamK $ K.hoist (return . runIdentity) (toStreamK xs)

5664

5765------------------------------------------------------------------------------

5866-- Add and remove a monad transformer

core/src/Streamly/Internal/Data/Stream/Transformer.hs+4−4

@@ -62,12 +62,12 @@ foldrT f z s = D.foldrT f z (toStreamD s)

6262-- Add and remove a monad transformer

6363------------------------------------------------------------------------------

6464

65−-- | Lift the inner monad @m@ of a stream @Stream m a@ to @tr m@ using the monad

66−-- transformer @tr@.

65+-- | Lift the inner monad @m@ of @Stream m a@ to @t m@ where @t@ is a monad

66+-- transformer.

6767--

6868{-# INLINE liftInner #-}

69−liftInner :: (Monad m, MonadTrans tr, Monad (tr m))

70− => Stream m a -> Stream (tr m) a

69+liftInner :: (Monad m, MonadTrans t, Monad (t m))

70+ => Stream m a -> Stream (t m) a

7171liftInner xs = fromStreamD $ D.liftInner (toStreamD xs)

7272

7373------------------------------------------------------------------------------