2353d76decccf0f1325d9068f141e9821707fc3b
[packages/base.git] / Control / Monad / State.hs
1 -----------------------------------------------------------------------------
2 -- |
3 -- Module : Control.Monad.State
4 -- Copyright : (c) Andy Gill 2001,
5 -- (c) Oregon Graduate Institute of Science and Technology, 2001
6 -- License : BSD-style (see the file libraries/core/LICENSE)
7 --
8 -- Maintainer : libraries@haskell.org
9 -- Stability : experimental
10 -- Portability : non-portable ( mulit-param classes, functional dependencies )
11 --
12 -- State monads.
13 --
14 -- Inspired by the paper
15 -- /Functional Programming with Overloading and
16 -- Higher-Order Polymorphism/,
17 -- Mark P Jones (<http://www.cse.ogi.edu/~mpj>)
18 -- Advanced School of Functional Programming, 1995.
19 -----------------------------------------------------------------------------
20
21 module Control.Monad.State (
22 MonadState(..),
23 modify,
24 gets,
25 State(..),
26 runState,
27 evalState,
28 execState,
29 mapState,
30 withState,
31 StateT(..),
32 runStateT,
33 evalStateT,
34 execStateT,
35 mapStateT,
36 withStateT,
37 module Control.Monad,
38 module Control.Monad.Fix,
39 module Control.Monad.Trans,
40 ) where
41
42 import Prelude
43
44 import Control.Monad
45 import Control.Monad.Fix
46 import Control.Monad.Trans
47 import Control.Monad.Reader
48 import Control.Monad.Writer
49
50 -- ---------------------------------------------------------------------------
51 -- MonadState class
52 --
53 -- get: returns the state from the internals of the monad.
54 -- put: changes (replaces) the state inside the monad.
55
56 class (Monad m) => MonadState s m | m -> s where
57 get :: m s
58 put :: s -> m ()
59
60 -- Monadic state transformer.
61 --
62 -- Maps an old state to a new state inside a state monad.
63 -- The old state is thrown away.}
64 --
65 -- Main> :t modify ((+1) :: Int -> Int)
66 -- modify (...) :: (MonadState Int a) => a ()
67 --
68 -- This says that modify (+1) acts over any
69 -- Monad that is a member of the MonadState class,
70 -- with an Int state.
71
72 modify :: (MonadState s m) => (s -> s) -> m ()
73 modify f = do
74 s <- get
75 put (f s)
76
77 -- Get part of the state
78 --
79 -- gets specific component of the state,
80 -- using a projection function supplied.
81
82 gets :: (MonadState s m) => (s -> a) -> m a
83 gets f = do
84 s <- get
85 return (f s)
86
87 -- ---------------------------------------------------------------------------
88 -- Our parameterizable state monad
89
90 newtype State s a = State { runState :: s -> (a, s) }
91
92 -- The State Monad structure is paramterized over just the state.
93
94 instance Functor (State s) where
95 fmap f m = State $ \s -> let
96 (a, s') = runState m s
97 in (f a, s')
98
99 instance Monad (State s) where
100 return a = State $ \s -> (a, s)
101 m >>= k = State $ \s -> let
102 (a, s') = runState m s
103 in runState (k a) s'
104
105 instance MonadFix (State s) where
106 mfix f = State $ \s -> let (a, s') = runState (f a) s in (a, s')
107
108 instance MonadState s (State s) where
109 get = State $ \s -> (s, s)
110 put s = State $ \_ -> ((), s)
111
112
113 evalState :: State s a -> s -> a
114 evalState m s = fst (runState m s)
115
116 execState :: State s a -> s -> s
117 execState m s = snd (runState m s)
118
119 mapState :: ((a, s) -> (b, s)) -> State s a -> State s b
120 mapState f m = State $ f . runState m
121
122 withState :: (s -> s) -> State s a -> State s a
123 withState f m = State $ runState m . f
124
125 -- ---------------------------------------------------------------------------
126 -- Our parameterizable state monad, with an inner monad
127
128 newtype StateT s m a = StateT { runStateT :: s -> m (a,s) }
129
130 --The StateT Monad structure is parameterized over two things:
131 --
132 -- * s - The state.
133 -- * m - The inner monad.
134
135 -- Here are some examples of use:
136
137 -- (Parser from ParseLib with Hugs)
138 -- type Parser a = StateT String [] a
139 -- ==> StateT (String -> [(a,String)])
140 -- For example, item can be written as:
141 -- item = do (x:xs) <- get
142 -- put xs
143 -- return x
144
145 -- type BoringState s a = StateT s Indentity a
146 -- ==> StateT (s -> Identity (a,s))
147 --
148 -- type StateWithIO s a = StateT s IO a
149 -- ==> StateT (s -> IO (a,s))
150 --
151 -- type StateWithErr s a = StateT s Maybe a
152 -- ==> StateT (s -> Maybe (a,s))
153
154 instance (Monad m) => Functor (StateT s m) where
155 fmap f m = StateT $ \s -> do
156 (x, s') <- runStateT m s
157 return (f x, s')
158
159 instance (Monad m) => Monad (StateT s m) where
160 return a = StateT $ \s -> return (a, s)
161 m >>= k = StateT $ \s -> do
162 (a, s') <- runStateT m s
163 runStateT (k a) s'
164 fail str = StateT $ \_ -> fail str
165
166 instance (MonadPlus m) => MonadPlus (StateT s m) where
167 mzero = StateT $ \_ -> mzero
168 m `mplus` n = StateT $ \s -> runStateT m s `mplus` runStateT n s
169
170 instance (MonadFix m) => MonadFix (StateT s m) where
171 mfix f = StateT $ \s -> mfix $ \ ~(a, _) -> runStateT (f a) s
172
173 instance (Monad m) => MonadState s (StateT s m) where
174 get = StateT $ \s -> return (s, s)
175 put s = StateT $ \_ -> return ((), s)
176
177 instance MonadTrans (StateT s) where
178 lift m = StateT $ \s -> do
179 a <- m
180 return (a, s)
181
182 instance (MonadIO m) => MonadIO (StateT s m) where
183 liftIO = lift . liftIO
184
185 instance (MonadReader r m) => MonadReader r (StateT s m) where
186 ask = lift ask
187 local f m = StateT $ \s -> local f (runStateT m s)
188
189 instance (MonadWriter w m) => MonadWriter w (StateT s m) where
190 tell = lift . tell
191 listen m = StateT $ \s -> do
192 ((a, s'), w) <- listen (runStateT m s)
193 return ((a, w), s')
194 pass m = StateT $ \s -> pass $ do
195 ((a, f), s') <- runStateT m s
196 return ((a, s'), f)
197
198
199 evalStateT :: (Monad m) => StateT s m a -> s -> m a
200 evalStateT m s = do
201 (a, _) <- runStateT m s
202 return a
203
204 execStateT :: (Monad m) => StateT s m a -> s -> m s
205 execStateT m s = do
206 (_, s') <- runStateT m s
207 return s'
208
209 mapStateT :: (m (a, s) -> n (b, s)) -> StateT s m a -> StateT s n b
210 mapStateT f m = StateT $ f . runStateT m
211
212 withStateT :: (s -> s) -> StateT s m a -> StateT s m a
213 withStateT f m = StateT $ runStateT m . f
214
215 -- ---------------------------------------------------------------------------
216 -- MonadState instances for other monad transformers
217
218 instance (MonadState s m) => MonadState s (ReaderT r m) where
219 get = lift get
220 put = lift . put
221
222 instance (Monoid w, MonadState s m) => MonadState s (WriterT w m) where
223 get = lift get
224 put = lift . put