transformers-0.3.0.0: Concrete functor and monad transformers

Copyright | (c) Andy Gill 2001, (c) Oregon Graduate Institute of Science and Technology, 2001
License | BSD-style (see the file LICENSE)
Maintainer | ross@soi.city.ac.uk
Stability | experimental
Portability | portable
Safe Haskell | Safe-Inferred
Language | Haskell98

Control.Monad.Trans.RWS.Strict

Contents

- The RWS monad
- The RWST monad transformer
- Reader operations
- Writer operations
- State operations
- Lifting other operations

Description

A monad transformer that combines `ReaderT`, `WriterT` and `StateT`. This version is strict; for a lazy version, see Control.Monad.Trans.RWS.Lazy, which has the same interface.

Synopsis

- type RWS r w s = RWST r w s Identity
- rws :: (r -> s -> (a, s, w)) -> RWS r w s a
- runRWS :: RWS r w s a -> r -> s -> (a, s, w)
- evalRWS :: RWS r w s a -> r -> s -> (a, w)
- execRWS :: RWS r w s a -> r -> s -> (s, w)
- mapRWS :: ((a, s, w) -> (b, s, w')) -> RWS r w s a -> RWS r w' s b
- withRWS :: (r' -> s -> (r, s)) -> RWS r w s a -> RWS r' w s a
- newtype RWST r w s m a = RWST {
  - runRWST :: r -> s -> m (a, s, w)
  }
- evalRWST :: Monad m => RWST r w s m a -> r -> s -> m (a, w)
- execRWST :: Monad m => RWST r w s m a -> r -> s -> m (s, w)
- mapRWST :: (m (a, s, w) -> n (b, s, w')) -> RWST r w s m a -> RWST r w' s n b
- withRWST :: (r' -> s -> (r, s)) -> RWST r w s m a -> RWST r' w s m a
- reader :: (Monoid w, Monad m) => (r -> a) -> RWST r w s m a
- ask :: (Monoid w, Monad m) => RWST r w s m r
- local :: (Monoid w, Monad m) => (r -> r) -> RWST r w s m a -> RWST r w s m a
- asks :: (Monoid w, Monad m) => (r -> a) -> RWST r w s m a
- writer :: Monad m => (a, w) -> RWST r w s m a
- tell :: (Monoid w, Monad m) => w -> RWST r w s m ()
- listen :: (Monoid w, Monad m) => RWST r w s m a -> RWST r w s m (a, w)
- listens :: (Monoid w, Monad m) => (w -> b) -> RWST r w s m a -> RWST r w s m (a, b)
- pass :: (Monoid w, Monad m) => RWST r w s m (a, w -> w) -> RWST r w s m a
- censor :: (Monoid w, Monad m) => (w -> w) -> RWST r w s m a -> RWST r w s m a
- state :: (Monoid w, Monad m) => (s -> (a, s)) -> RWST r w s m a
- get :: (Monoid w, Monad m) => RWST r w s m s
- put :: (Monoid w, Monad m) => s -> RWST r w s m ()
- modify :: (Monoid w, Monad m) => (s -> s) -> RWST r w s m ()
- gets :: (Monoid w, Monad m) => (s -> a) -> RWST r w s m a
- liftCallCC :: Monoid w => ((((a, s, w) -> m (b, s, w)) -> m (a, s, w)) -> m (a, s, w)) -> ((a -> RWST r w s m b) -> RWST r w s m a) -> RWST r w s m a
- liftCallCC' :: Monoid w => ((((a, s, w) -> m (b, s, w)) -> m (a, s, w)) -> m (a, s, w)) -> ((a -> RWST r w s m b) -> RWST r w s m a) -> RWST r w s m a
- liftCatch :: (m (a, s, w) -> (e -> m (a, s, w)) -> m (a, s, w)) -> RWST l w s m a -> (e -> RWST l w s m a) -> RWST l w s m a

# The RWS monad

type RWS r w s = RWST r w s Identity

A monad containing an environment of type `r`, output of type `w` and an updatable state of type `s`.

rws :: (r -> s -> (a, s, w)) -> RWS r w s a

Construct an RWS computation from a function. (The inverse of `runRWS`.)

runRWS :: RWS r w s a -> r -> s -> (a, s, w)

Unwrap an RWS computation as a function. (The inverse of `rws`.)

evalRWS

Arguments

:: RWS r w s a | RWS computation to execute
-> r | initial environment
-> s | initial value
-> (a, w) | final value and output

Evaluate a computation with the given initial state and environment, returning the final value and output, discarding the final state.

execRWS

Arguments

:: RWS r w s a | RWS computation to execute
-> r | initial environment
-> s | initial value
-> (s, w) | final state and output

Evaluate a computation with the given initial state and environment, returning the final state and output, discarding the final value.

mapRWS :: ((a, s, w) -> (b, s, w')) -> RWS r w s a -> RWS r w' s b

Map the return value, final state and output of a computation using the given function.

-     runRWS (mapRWS f m) r s = f (runRWS m r s)

withRWS :: (r' -> s -> (r, s)) -> RWS r w s a -> RWS r' w s a

``withRWS` f m` executes action `m` with an initial environment and state modified by applying `f`.

-     runRWS (withRWS f m) r s = uncurry (runRWS m) (f r s)

# The RWST monad transformer

newtype RWST r w s m a

A monad transformer adding reading an environment of type `r`, collecting an output of type `w` and updating a state of type `s` to an inner monad `m`.

Constructors

RWST |
Fields runRWST :: r -> s -> m (a, s, w)

Instances

Monoid w => MonadTrans (RWST r w s) |
(Monoid w, Functor m, MonadPlus m) => Alternative (RWST r w s m) |
(Monoid w, Monad m) => Monad (RWST r w s m) |
Functor m => Functor (RWST r w s m) |
(Monoid w, MonadFix m) => MonadFix (RWST r w s m) |
(Monoid w, MonadPlus m) => MonadPlus (RWST r w s m) |
(Monoid w, Functor m, Monad m) => Applicative (RWST r w s m) |
(Monoid w, MonadIO m) => MonadIO (RWST r w s m) |

evalRWST

Arguments

:: Monad m |
=> RWST r w s m a | computation to execute
-> r | initial environment
-> s | initial value
-> m (a, w) | computation yielding final value and output

Evaluate a computation with the given initial state and environment, returning the final value and output, discarding the final state.

execRWST

Arguments

:: Monad m |
=> RWST r w s m a | computation to execute
-> r | initial environment
-> s | initial value
-> m (s, w) | computation yielding final state and output

Evaluate a computation with the given initial state and environment, returning the final state and output, discarding the final value.

mapRWST :: (m (a, s, w) -> n (b, s, w')) -> RWST r w s m a -> RWST r w' s n b

Map the inner computation using the given function.

-     runRWST (mapRWST f m) r s = f (runRWST m r s)

withRWST :: (r' -> s -> (r, s)) -> RWST r w s m a -> RWST r' w s m a

``withRWST` f m` executes action `m` with an initial environment and state modified by applying `f`.

-     runRWST (withRWST f m) r s = uncurry (runRWST m) (f r s)

# Reader operations

reader :: (Monoid w, Monad m) => (r -> a) -> RWST r w s m a

Constructor for computations in the reader monad (equivalent to `asks`).

ask :: (Monoid w, Monad m) => RWST r w s m r

Fetch the value of the environment.

local :: (Monoid w, Monad m) => (r -> r) -> RWST r w s m a -> RWST r w s m a

Execute a computation in a modified environment

-     runRWST (local f m) r s = runRWST m (f r) s

asks :: (Monoid w, Monad m) => (r -> a) -> RWST r w s m a

Retrieve a function of the current environment.

-     asks f = liftM f ask

# Writer operations

writer :: Monad m => (a, w) -> RWST r w s m a

Construct a writer computation from a (result, output) pair.

tell :: (Monoid w, Monad m) => w -> RWST r w s m ()

``tell` w` is an action that produces the output `w`.

listen :: (Monoid w, Monad m) => RWST r w s m a -> RWST r w s m (a, w)

``listen` m` is an action that executes the action `m` and adds its output to the value of the computation.

-     runRWST (listen m) r s = liftM (\(a, w) -> ((a, w), w)) (runRWST m r s)

listens :: (Monoid w, Monad m) => (w -> b) -> RWST r w s m a -> RWST r w s m (a, b)

``listens` f m` is an action that executes the action `m` and adds the result of applying `f` to the output to the value of the computation.

-     listens f m = liftM (id *** f) (listen m)

-     runRWST (listens f m) r s = liftM (\(a, w) -> ((a, f w), w)) (runRWST m r s)

pass :: (Monoid w, Monad m) => RWST r w s m (a, w -> w) -> RWST r w s m a

``pass` m` is an action that executes the action `m`, which returns a value and a function, and returns the value, applying the function to the output.

-     runRWST (pass m) r s = liftM (\((a, f), w) -> (a, f w)) (runRWST m r s)

censor :: (Monoid w, Monad m) => (w -> w) -> RWST r w s m a -> RWST r w s m a

``censor` f m` is an action that executes the action `m` and applies the function `f` to its output, leaving the return value unchanged.

-     censor f m = pass (liftM (\x -> (x,f)) m)

-     runRWST (censor f m) r s = liftM (\(a, w) -> (a, f w)) (runRWST m r s)

# State operations

state :: (Monoid w, Monad m) => (s -> (a, s)) -> RWST r w s m a

Construct a state monad computation from a state transformer function.

get :: (Monoid w, Monad m) => RWST r w s m s

Fetch the current value of the state within the monad.

put :: (Monoid w, Monad m) => s -> RWST r w s m ()

``put` s` sets the state within the monad to `s`.

modify :: (Monoid w, Monad m) => (s -> s) -> RWST r w s m ()

``modify` f` is an action that updates the state to the result of applying `f` to the current state.

-     modify f = get >>= (put . f)

gets :: (Monoid w, Monad m) => (s -> a) -> RWST r w s m a

Get a specific component of the state, using a projection function supplied.

-     gets f = liftM f get

# Lifting other operations

liftCallCC :: Monoid w => ((((a, s, w) -> m (b, s, w)) -> m (a, s, w)) -> m (a, s, w)) -> ((a -> RWST r w s m b) -> RWST r w s m a) -> RWST r w s m a

Uniform lifting of a `callCC` operation to the new monad. This version rolls back to the original state on entering the continuation.

liftCallCC' :: Monoid w => ((((a, s, w) -> m (b, s, w)) -> m (a, s, w)) -> m (a, s, w)) -> ((a -> RWST r w s m b) -> RWST r w s m a) -> RWST r w s m a

In-situ lifting of a `callCC` operation to the new monad. This version uses the current state on entering the continuation.

liftCatch :: (m (a, s, w) -> (e -> m (a, s, w)) -> m (a, s, w)) -> RWST l w s m a -> (e -> RWST l w s m a) -> RWST l w s m a

Lift a `catchError` operation to the new monad.