1 -----------------------------------------------------------------------------
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/base/LICENSE)
8 -- Maintainer : libraries@haskell.org
9 -- Stability : experimental
10 -- Portability : non-portable (multi-param classes, functional dependencies)
14 -- This module is 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.
20 -- See below for examples.
22 -----------------------------------------------------------------------------
24 module Control.Monad.State (
42 module Control.Monad.Fix,
43 module Control.Monad.Trans,
51 import Control.Monad.Fix
52 import Control.Monad.Trans
53 import Control.Monad.Reader
54 import Control.Monad.Writer
56 -- ---------------------------------------------------------------------------
57 -- | /get/ returns the state from the internals of the monad.
59 -- /put/ replaces the state inside the monad.
61 class (Monad m) => MonadState s m | m -> s where
65 -- | Monadic state transformer.
67 -- Maps an old state to a new state inside a state monad.
68 -- The old state is thrown away.
70 -- > Main> :t modify ((+1) :: Int -> Int)
71 -- > modify (...) :: (MonadState Int a) => a ()
73 -- This says that @modify (+1)@ acts over any
74 -- Monad that is a member of the @MonadState@ class,
75 -- with an @Int@ state.
77 modify :: (MonadState s m) => (s -> s) -> m ()
82 -- | Gets specific component of the state, using a projection function
85 gets :: (MonadState s m) => (s -> a) -> m a
90 -- ---------------------------------------------------------------------------
91 -- | A parameterizable state monad where /s/ is the type of the state
92 -- to carry and /a/ is the type of the /return value/.
94 newtype State s a = State { runState :: s -> (a, s) }
96 -- The State Monad structure is parameterized over just the state.
98 instance Functor (State s) where
99 fmap f m = State $ \s -> let
100 (a, s') = runState m s
103 instance Monad (State s) where
104 return a = State $ \s -> (a, s)
105 m >>= k = State $ \s -> let
106 (a, s') = runState m s
109 instance MonadFix (State s) where
110 mfix f = State $ \s -> let (a, s') = runState (f a) s in (a, s')
112 instance MonadState s (State s) where
113 get = State $ \s -> (s, s)
114 put s = State $ \_ -> ((), s)
116 -- |Evaluate this state monad with the given initial state,throwing
117 -- away the final state. Very much like @fst@ composed with
120 evalState :: State s a -- ^The state to evaluate
121 -> s -- ^An initial value
122 -> a -- ^The return value of the state application
123 evalState m s = fst (runState m s)
125 -- |Execute this state and return the new state, throwing away the
126 -- return value. Very much like @snd@ composed with
129 execState :: State s a -- ^The state to evaluate
130 -> s -- ^An initial value
131 -> s -- ^The new state
132 execState m s = snd (runState m s)
134 -- |Map a stateful computation from one (return value, state) pair to
135 -- another. For instance, to convert numberTree from a function that
136 -- returns a tree to a function that returns the sum of the numbered
137 -- tree (see the Examples section for numberTree and sumTree) you may
140 -- > sumNumberedTree :: (Eq a) => Tree a -> State (Table a) Int
141 -- > sumNumberedTree = mapState (\ (t, tab) -> (sumTree t, tab)) . numberTree
143 mapState :: ((a, s) -> (b, s)) -> State s a -> State s b
144 mapState f m = State $ f . runState m
146 -- |Apply this function to this state and return the resulting state.
147 withState :: (s -> s) -> State s a -> State s a
148 withState f m = State $ runState m . f
150 -- ---------------------------------------------------------------------------
151 -- | A parameterizable state monad for encapsulating an inner
154 -- The StateT Monad structure is parameterized over two things:
158 -- * m - The inner monad.
160 -- Here are some examples of use:
162 -- (Parser from ParseLib with Hugs)
164 -- > type Parser a = StateT String [] a
165 -- > ==> StateT (String -> [(a,String)])
167 -- For example, item can be written as:
169 -- > item = do (x:xs) <- get
173 -- > type BoringState s a = StateT s Indentity a
174 -- > ==> StateT (s -> Identity (a,s))
176 -- > type StateWithIO s a = StateT s IO a
177 -- > ==> StateT (s -> IO (a,s))
179 -- > type StateWithErr s a = StateT s Maybe a
180 -- > ==> StateT (s -> Maybe (a,s))
182 newtype StateT s m a = StateT { runStateT :: s -> m (a,s) }
184 instance (Monad m) => Functor (StateT s m) where
185 fmap f m = StateT $ \s -> do
186 (x, s') <- runStateT m s
189 instance (Monad m) => Monad (StateT s m) where
190 return a = StateT $ \s -> return (a, s)
191 m >>= k = StateT $ \s -> do
192 (a, s') <- runStateT m s
194 fail str = StateT $ \_ -> fail str
196 instance (MonadPlus m) => MonadPlus (StateT s m) where
197 mzero = StateT $ \_ -> mzero
198 m `mplus` n = StateT $ \s -> runStateT m s `mplus` runStateT n s
200 instance (MonadFix m) => MonadFix (StateT s m) where
201 mfix f = StateT $ \s -> mfix $ \ ~(a, _) -> runStateT (f a) s
203 instance (Monad m) => MonadState s (StateT s m) where
204 get = StateT $ \s -> return (s, s)
205 put s = StateT $ \_ -> return ((), s)
207 instance MonadTrans (StateT s) where
208 lift m = StateT $ \s -> do
212 instance (MonadIO m) => MonadIO (StateT s m) where
213 liftIO = lift . liftIO
215 instance (MonadReader r m) => MonadReader r (StateT s m) where
217 local f m = StateT $ \s -> local f (runStateT m s)
219 instance (MonadWriter w m) => MonadWriter w (StateT s m) where
221 listen m = StateT $ \s -> do
222 ((a, s'), w) <- listen (runStateT m s)
224 pass m = StateT $ \s -> pass $ do
225 ((a, f), s') <- runStateT m s
228 -- |Similar to 'evalState'
229 evalStateT :: (Monad m) => StateT s m a -> s -> m a
231 (a, _) <- runStateT m s
234 -- |Similar to 'execState'
235 execStateT :: (Monad m) => StateT s m a -> s -> m s
237 (_, s') <- runStateT m s
240 -- |Similar to 'mapState'
241 mapStateT :: (m (a, s) -> n (b, s)) -> StateT s m a -> StateT s n b
242 mapStateT f m = StateT $ f . runStateT m
244 -- |Similar to 'withState'
245 withStateT :: (s -> s) -> StateT s m a -> StateT s m a
246 withStateT f m = StateT $ runStateT m . f
248 -- ---------------------------------------------------------------------------
249 -- MonadState instances for other monad transformers
251 instance (MonadState s m) => MonadState s (ReaderT r m) where
255 instance (Monoid w, MonadState s m) => MonadState s (WriterT w m) where
259 -- ---------------------------------------------------------------------------
261 -- A function to increment a counter. Taken from the paper
262 -- /Generalising Monads to Arrows/, John
263 -- Hughes (<http://www.math.chalmers.se/~rjmh/>), November 1998:
265 -- > tick :: State Int Int
266 -- > tick = do n <- get
270 -- Add one to the given number using the state monad:
272 -- > plusOne :: Int -> Int
273 -- > plusOne n = execState tick n
275 -- A contrived addition example. Works only with positive numbers:
277 -- > plus :: Int -> Int -> Int
278 -- > plus n x = execState (sequence $ replicate n tick) x
280 -- An example from /The Craft of Functional Programming/, Simon
281 -- Thompson (<http://www.cs.kent.ac.uk/people/staff/sjt/>),
282 -- Addison-Wesley 1999: \"Given an arbitrary tree, transform it to a
283 -- tree of integers in which the original elements are replaced by
284 -- natural numbers, starting from 0. The same element has to be
285 -- replaced by the same number at every occurrence, and when we meet
286 -- an as-yet-unvisited element we have to find a 'new' number to match
289 -- > data Tree a = Nil | Node a (Tree a) (Tree a) deriving (Show, Eq)
290 -- > type Table a = [a]
292 -- > numberTree :: Eq a => Tree a -> State (Table a) (Tree Int)
293 -- > numberTree Nil = return Nil
294 -- > numberTree (Node x t1 t2)
295 -- > = do num <- numberNode x
296 -- > nt1 <- numberTree t1
297 -- > nt2 <- numberTree t2
298 -- > return (Node num nt1 nt2)
300 -- > numberNode :: Eq a => a -> State (Table a) Int
302 -- > = do table <- get
303 -- > (newTable, newPos) <- return (nNode x table)
306 -- > nNode:: (Eq a) => a -> Table a -> (Table a, Int)
308 -- > = case (findIndexInList (== x) table) of
309 -- > Nothing -> (table ++ [x], length table)
310 -- > Just i -> (table, i)
311 -- > findIndexInList :: (a -> Bool) -> [a] -> Maybe Int
312 -- > findIndexInList = findIndexInListHelp 0
313 -- > findIndexInListHelp _ _ [] = Nothing
314 -- > findIndexInListHelp count f (h:t)
317 -- > else findIndexInListHelp (count+1) f t
319 -- numTree applies numberTree with an initial state:
321 -- > numTree :: (Eq a) => Tree a -> Tree Int
322 -- > numTree t = evalState (numberTree t) []
324 -- > testTree = Node "Zero" (Node "One" (Node "Two" Nil Nil) (Node "One" (Node "Zero" Nil Nil) Nil)) Nil
325 -- > numTree testTree => Node 0 (Node 1 (Node 2 Nil Nil) (Node 1 (Node 0 Nil Nil) Nil)) Nil
327 -- sumTree is a little helper function that does not use the State monad:
329 -- > sumTree :: (Num a) => Tree a -> a
331 -- > sumTree (Node e t1 t2) = e + (sumTree t1) + (sumTree t2)