MTLPrelude

Introduces a recursive binding to the continuation. Due to the use of callCC, calling the continuation will interrupt execution of the current block creating an effect similar to goto/setjmp in C.

Lift a callCC operation to the new monad.

A monad transformer that adds exceptions to other monads.

ExceptT constructs a monad parameterized over two things:

• e - The exception type.

• m - The inner monad.

The return function yields a computation that produces the given value, while >>= sequences two subcomputations, exiting on the first exception.

The parameterizable exception monad.

Computations are either exceptions or normal values.

The return function returns a normal value, while >>= exits on the first exception. For a variant that continues after an error and collects all the errors, see Errors.

Constructor for computations in the exception monad. (The inverse of runExcept).

Extractor for computations in the exception monad. (The inverse of except).

The inverse of ExceptT.

Map the unwrapped computation using the given function.

• runExcept (mapExcept f m) = f (runExcept m)

Map the unwrapped computation using the given function.

• runExceptT (mapExceptT f m) = f (runExceptT m)

Transform any exceptions thrown by the computation using the given function (a specialization of withExceptT).

Transform any exceptions thrown by the computation using the given function.

The parameterizable reader monad.

Computations are functions of a shared environment.

The return function ignores the environment, while m >>= k passes the inherited environment to both subcomputations:

image: images/bind-ReaderT.svg

Runs a Reader and extracts the final value from it. (The inverse of reader.)

Transform the value returned by a Reader.

• runReader (mapReader f m) = f . runReader m

Execute a computation in a modified environment (a specialization of withReaderT).

• runReader (withReader f m) = runReader m . f

The reader monad transformer, which adds a read-only environment to the given monad.

The return function ignores the environment, while m >>= k passes the inherited environment to both subcomputations:

image: images/bind-ReaderT.svg

Transform the computation inside a ReaderT.

• runReaderT (mapReaderT f m) = f . runReaderT m

Execute a computation in a modified environment (a more general version of local).

• runReaderT (withReaderT f m) = runReaderT m . f

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

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

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

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

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

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 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)

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.

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

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

Map the inner computation using the given function.

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

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)

A state monad parameterized by the type s of the state to carry.

The return function leaves the state unchanged, while >>= uses the final state of the first computation as the initial state of the second.

Unwrap a state monad computation as a function. (The inverse of state.)

Evaluate a state computation with the given initial state and return the final value, discarding the final state.

• evalState m s = fst (runState m s)

Evaluate a state computation with the given initial state and return the final state, discarding the final value.

• execState m s = snd (runState m s)

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

• runState (mapState f m) = f . runState m

withState f m executes action m on a state modified by applying f.

• withState f m = modify f >> m

A state transformer monad parameterized by:

• s - The state.

• m - The inner monad.

The return function leaves the state unchanged, while >>= uses the final state of the first computation as the initial state of the second.

Evaluate a state computation with the given initial state and return the final value, discarding the final state.

• evalStateT m s = liftM fst (runStateT m s)

Evaluate a state computation with the given initial state and return the final state, discarding the final value.

• execStateT m s = liftM snd (runStateT m s)

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

• runStateT (mapStateT f m) = f . runStateT m

withStateT f m executes action m on a state modified by applying f.

• withStateT f m = modify f >> m

A writer monad parameterized by the type w of output to accumulate.

The return function produces the output mempty, while m >>= k combines the outputs of the subcomputations using mappend (also known as <>):

image: images/bind-WriterT.svg

Unwrap a writer computation as a (result, output) pair. (The inverse of writer.)

Extract the output from a writer computation.

• execWriter m = snd (runWriter m)

Map both the return value and output of a computation using the given function.

• runWriter (mapWriter f m) = f (runWriter m)

A writer monad parameterized by:

• w - the output to accumulate.

• m - The inner monad.

The return function produces the output mempty, while m >>= k combines the outputs of the subcomputations using mappend (also known as <>):

image: images/bind-WriterT.svg

Continuation monad. Cont r a is a CPS ("continuation-passing style") computation that produces an intermediate result of type a within a CPS computation whose final result type is r.

The return function simply creates a continuation which passes the value on.

The >>= operator adds the bound function into the continuation chain.

Identity functor and monad. (a non-strict monad)

Examples

>>> fmap (+1) (Identity 0)Identity 1

>>> Identity [1, 2, 3] <> Identity [4, 5, 6]Identity [1,2,3,4,5,6]

>>> do
      x <- Identity 10
      y <- Identity (x + 5)
      pure (x + y)
Identity 25

Extract the output from a writer computation.

• execWriterT m = liftM snd (runWriterT m)

Map both the return value and output of a computation using the given function.

• runWriterT (mapWriterT f m) = f (runWriterT m)

Simplified version of label without arguments.

The continuation monad transformer. Can be used to add continuation handling to any type constructor: the Monad instance and most of the operations do not require m to be a monad.

ContT is not a functor on the category of monads, and many operations cannot be lifted through it.

The parameterizable maybe monad, obtained by composing an arbitrary monad with the Maybe monad.

Computations are actions that may produce a value or exit.

The return function yields a computation that produces that value, while >>= sequences two subcomputations, exiting if either computation does.

The class of monad transformers. For any monad m, the result t m should also be a monad, and lift should be a monad transformation from m to t m, i.e. it should satisfy the following laws:

• lift . return = return

• lift (m >>= f) = lift m >>= (lift . f)

Since 0.6.0.0 and for GHC 8.6 and later, the requirement that t m be a Monad is enforced by the implication constraint forall m. Monad m => Monad (t m) enabled by the QuantifiedConstraints extension.

Ambiguity error with GHC 9.0 to 9.2.2

These versions of GHC have a bug (https://gitlab.haskell.org/ghc/ghc/-/issues/20582) which causes constraints like

(MonadTrans t, forall m. Monad m => Monad (t m)) => ...

to be reported as ambiguous. For transformers 0.6 and later, this can be fixed by removing the second constraint, which is implied by the first.

See examples in Control.Monad.Reader. Note, the partially applied function type (->) r is a simple reader monad. See the instance declaration below.

Construct a continuation-passing computation from a function. (The inverse of runCont)

The result of running a CPS computation with the identity as the final continuation.

• evalCont (return x) = x

The result of running a CPS computation with return as the final continuation.

• evalContT (lift m) = m

liftLocal ask local yields a local function for ContT r m.

Apply a function to transform the result of a continuation-passing computation.

• runCont (mapCont f m) = f . runCont m

Apply a function to transform the result of a continuation-passing computation. This has a more restricted type than the map operations for other monad transformers, because ContT does not define a functor in the category of monads.

• runContT (mapContT f m) = f . runContT m

reset m delimits the continuation of any shift inside m.

• reset (return m) = return m

resetT m delimits the continuation of any shiftT inside m.

• resetT (lift m) = lift m

The result of running a CPS computation with a given final continuation. (The inverse of cont)

shift f captures the continuation up to the nearest enclosing reset and passes it to f:

• reset (shift f >>= k) = reset (f (evalCont . k))

shiftT f captures the continuation up to the nearest enclosing resetT and passes it to f:

• resetT (shiftT f >>= k) = resetT (f (evalContT . k))

Apply a function to transform the continuation passed to a CPS computation.

• runCont (withCont f m) = runCont m . f

Apply a function to transform the continuation passed to a CPS computation.

• runContT (withContT f m) = runContT m . f

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

The strategy of combining computations that can throw exceptions by bypassing bound functions from the point an exception is thrown to the point that it is handled.

Is parameterized over the type of error information and the monad type constructor. It is common to use Either String as the monad type constructor for an error monad in which error descriptions take the form of strings. In that case and many other common cases the resulting monad is already defined as an instance of the MonadError class. You can also define your own error type and/or use a monad type constructor other than Either String or Either IOError. In these cases you will have to explicitly define instances of the MonadError class. (If you are using the deprecated Control.Monad.Error or Control.Monad.Trans.Error, you may also have to define an Error instance.)

As handle is flipped catch, handleError is flipped catchError.

Lifts an Either e into any MonadError e.

do { val <- liftEither =<< action1; action2 }

where action1 returns an Either to represent errors.

MonadError analogue of the mapExceptT function. The computation is unwrapped, a function is applied to the Either, and the result is lifted into the second MonadError instance.

A different MonadError analogue to the withExceptT function. Modify the value (and possibly the type) of an error in an ExceptT-transformed monad, while stripping the ExceptT layer.

This is useful for adapting the MonadError constraint of a computation.

For example:

data DatabaseError = ...

performDatabaseQuery :: (MonadError DatabaseError m, ...) => m PersistedValue

data AppError
  = MkDatabaseError DatabaseError
  | ...

app :: (MonadError AppError m, ...) => m ()

Given these types, performDatabaseQuery cannot be used directly inside app, because the error types don't match. Using modifyError, an equivalent function with a different error type can be constructed:

performDatabaseQuery' :: (MonadError AppError m, ...) => m PersistedValue
performDatabaseQuery' = modifyError MkDatabaseError performDatabaseQuery

Since the error types do match, performDatabaseQuery' _can_ be used in app, assuming all other constraints carry over.

This works by instantiating the m in the type of performDatabaseQuery to ExceptT DatabaseError m', which satisfies the MonadError DatabaseError constraint. Immediately, the ExceptT DatabaseError layer is unwrapped, producing Either a DatabaseError or a PersistedValue. If it's the former, the error is wrapped in MkDatabaseError and re-thrown in the inner monad, otherwise the result value is returned.

MonadError analogue to the try function.

MonadError analogue to the withExceptT function. Modify the value (but not the type) of an error. The type is fixed because of the functional dependency m -> e. If you need to change the type of e use mapError or modifyError.

Lift a listen operation to the new monad.

Lift a pass operation to the new monad.

Convert a ExceptT computation to MaybeT, discarding the value of any exception.

Convert a Maybe computation to MaybeT.

Lift a catchE operation to the new monad.

Transform the computation inside a MaybeT.

• runMaybeT (mapMaybeT f m) = f (runMaybeT m)

Convert a MaybeT computation to ExceptT, with a default exception value.

Retrieves a function of the current environment.

Minimal definition is either both of get and put or just state

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

Monadic state transformer.

Maps an old state to a new state inside a state monad. The old state is thrown away.

     Main> :t modify ((+1) :: Int -> Int)
     modify (...) :: (MonadState Int a) => a ()

This says that modify (+1) acts over any Monad that is a member of the MonadState class, with an Int state.

A variant of modify in which the computation is strict in the new state.

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)

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)