git.iko.soy/effectful
on master help sign in
Add haddock to shared variants of State and Writer
7600133Andrzej Rybczak
effectful-core/src/Effectful/State/Shared.hs+27
compare with master
unifiedsplit
@@ -29,44 +29,66 @@ import Effectful.Monad
29newtype State s :: Effect where
29newtype State s :: Effect where
30 State :: MVar s -> State s m r
30 State :: MVar s -> State s m r
31
31
32+-- | Run a 'State' effect with the given initial state and return the final
33+-- value along with the final state.
32runState :: s -> Eff (State s : es) a -> Eff es (a, s)
34runState :: s -> Eff (State s : es) a -> Eff es (a, s)
33runState s m = do
35runState s m = do
34 v <- unsafeEff_ $ newMVar s
36 v <- unsafeEff_ $ newMVar s
35 a <- evalEffect (IdE (State v)) m
37 a <- evalEffect (IdE (State v)) m
36 (a, ) <$> unsafeEff_ (readMVar v)
38 (a, ) <$> unsafeEff_ (readMVar v)
37
39
40+-- | Run a 'State' effect with the given initial state and return the final
41+-- value, discarding the final state.
38evalState :: s -> Eff (State s : es) a -> Eff es a
42evalState :: s -> Eff (State s : es) a -> Eff es a
39evalState s m = do
43evalState s m = do
40 v <- unsafeEff_ $ newMVar s
44 v <- unsafeEff_ $ newMVar s
41 evalEffect (IdE (State v)) m
45 evalEffect (IdE (State v)) m
42
46
47+-- | Run a 'State' effect with the given initial state and return the final
48+-- state, discarding the final value.
43execState :: s -> Eff (State s : es) a -> Eff es s
49execState :: s -> Eff (State s : es) a -> Eff es s
44execState s m = do
50execState s m = do
45 v <- unsafeEff_ $ newMVar s
51 v <- unsafeEff_ $ newMVar s
46 _ <- evalEffect (IdE (State v)) m
52 _ <- evalEffect (IdE (State v)) m
47 unsafeEff_ $ readMVar v
53 unsafeEff_ $ readMVar v
48
54
55+-- | Fetch the current value of the state.
49get :: State s :> es => Eff es s
56get :: State s :> es => Eff es s
50get = unsafeEff $ \es -> do
57get = unsafeEff $ \es -> do
51 IdE (State v) <- getEnv es
58 IdE (State v) <- getEnv es
52 readMVar v
59 readMVar v
53
60
61+-- | Get a function of the current state.
62+--
63+-- @'gets' f ≡ f '<$>' 'get'@
54gets :: State s :> es => (s -> a) -> Eff es a
64gets :: State s :> es => (s -> a) -> Eff es a
55gets f = f <$> get
65gets f = f <$> get
56
66
67+-- | Set the current state to the given value.
57put :: State s :> es => s -> Eff es ()
68put :: State s :> es => s -> Eff es ()
58put s = unsafeEff $ \es -> do
69put s = unsafeEff $ \es -> do
59 IdE (State v) <- getEnv es
70 IdE (State v) <- getEnv es
60 modifyMVar_ v $ \_ -> s `seq` pure s
71 modifyMVar_ v $ \_ -> s `seq` pure s
61
72
73+-- | Apply the function to the current state and return a value.
74+--
75+-- /Note:/ this function gets an exclusive access to the state for its duration.
62state :: State s :> es => (s -> (a, s)) -> Eff es a
76state :: State s :> es => (s -> (a, s)) -> Eff es a
63state f = unsafeEff $ \es -> do
77state f = unsafeEff $ \es -> do
64 IdE (State v) <- getEnv es
78 IdE (State v) <- getEnv es
65 modifyMVar v $ \s0 -> let (a, s) = f s0 in s `seq` pure (s, a)
79 modifyMVar v $ \s0 -> let (a, s) = f s0 in s `seq` pure (s, a)
66
80
81+-- | Apply the function to the current state.
82+--
83+-- @'modify' f ≡ 'state' (\\s -> ((), f s))@
84+--
85+-- /Note:/ this function gets an exclusive access to the state for its duration.
67modify :: State s :> es => (s -> s) -> Eff es ()
86modify :: State s :> es => (s -> s) -> Eff es ()
68modify f = state (\s -> ((), f s))
87modify f = state (\s -> ((), f s))
69
88
89+-- | Apply the monadic function to the current state and return a value.
90+--
91+-- /Note:/ this function gets an exclusive access to the state for its duration.
70stateM :: State s :> es => (s -> Eff es (a, s)) -> Eff es a
92stateM :: State s :> es => (s -> Eff es (a, s)) -> Eff es a
71stateM f = unsafeEff $ \es -> do
93stateM f = unsafeEff $ \es -> do
72 IdE (State v) <- getEnv es
94 IdE (State v) <- getEnv es
@@ -74,5 +96,10 @@ stateM f = unsafeEff $ \es -> do
74 (a, s) <- unEff (f s0) es
96 (a, s) <- unEff (f s0) es
75 s `seq` pure (s, a)
97 s `seq` pure (s, a)
76
98
99+-- | Apply the monadic function to the current state.
100+--
101+-- @'modifyM' f ≡ 'stateM' (\\s -> ((), ) '<$>' f s)@
102+--
103+-- /Note:/ this function gets an exclusive access to the state for its duration.
77modifyM :: State s :> es => (s -> Eff es s) -> Eff es ()
104modifyM :: State s :> es => (s -> Eff es s) -> Eff es ()
78modifyM f = stateM (\s -> ((), ) <$> f s)
105modifyM f = stateM (\s -> ((), ) <$> f s)
effectful-core/src/Effectful/Writer/Shared.hs+11
@@ -17,23 +17,34 @@ import Effectful.Monad
17newtype Writer w :: Effect where
17newtype Writer w :: Effect where
18 Writer :: MVar w -> Writer w m r
18 Writer :: MVar w -> Writer w m r
19
19
20+-- | Run a 'Writer' effect and return the final value along with the final
21+-- output.
20runWriter :: Monoid w => Eff (Writer w : es) a -> Eff es (a, w)
22runWriter :: Monoid w => Eff (Writer w : es) a -> Eff es (a, w)
21runWriter m = do
23runWriter m = do
22 v <- unsafeEff_ $ newMVar mempty
24 v <- unsafeEff_ $ newMVar mempty
23 a <- evalEffect (IdE (Writer v)) m
25 a <- evalEffect (IdE (Writer v)) m
24 (a, ) <$> unsafeEff_ (readMVar v)
26 (a, ) <$> unsafeEff_ (readMVar v)
25
27
28+-- | Run a 'Writer' effect and return the final output, discarding the final
29+-- value.
26execWriter :: Monoid w => Eff (Writer w : es) a -> Eff es w
30execWriter :: Monoid w => Eff (Writer w : es) a -> Eff es w
27execWriter m = do
31execWriter m = do
28 v <- unsafeEff_ $ newMVar mempty
32 v <- unsafeEff_ $ newMVar mempty
29 _ <- evalEffect (IdE (Writer v)) m
33 _ <- evalEffect (IdE (Writer v)) m
30 unsafeEff_ $ readMVar v
34 unsafeEff_ $ readMVar v
31
35
36+-- | Append the given output to the overall output of the 'Writer'.
32tell :: (Writer w :> es, Monoid w) => w -> Eff es ()
37tell :: (Writer w :> es, Monoid w) => w -> Eff es ()
33tell w1 = unsafeEff $ \es -> do
38tell w1 = unsafeEff $ \es -> do
34 IdE (Writer v) <- getEnv es
39 IdE (Writer v) <- getEnv es
35 modifyMVar_ v $ \w0 -> let w = w0 <> w1 in w `seq` pure w
40 modifyMVar_ v $ \w0 -> let w = w0 <> w1 in w `seq` pure w
36
41
42+-- | Execute an action and append its output to the overall output of the
43+-- 'Writer'.
44+--
45+-- /Note:/ if a runtime exception is received while the action is executed, the
46+-- partial output of the action will still be appended to the overall output of
47+-- the 'Writer'.
37listen :: (Writer w :> es, Monoid w) => Eff es a -> Eff es (a, w)
48listen :: (Writer w :> es, Monoid w) => Eff es a -> Eff es (a, w)
38listen m = unsafeEff $ \es -> do
49listen m = unsafeEff $ \es -> do
39 -- The mask is uninterruptible because modifyMVar_ v0 in the merge function
50 -- The mask is uninterruptible because modifyMVar_ v0 in the merge function