mtl Hackage Build Status

MTL is a collection of monad classes, extending the transformers package, using functional dependencies for generic lifting of monadic actions.

Structure

Transformers in MTL are divided into classes and data types. Classes define the monadic operations of transformers. Data types, generally from the transformers package, implement transformers, and MTL provides instances for all the transformer type classes.

MTL and transformers use a common module, data type, and function naming scheme. As an example, let’s imagine we have a transformer Foo.

In the Control.Monad.Foo module, we’d find:

  • A type class MonadFoo with the transformer operations.
  • A data type FooT with instances for all monad transformer classes.
  • Functions to run the transformed computation, e.g. runFooT. For the actual transformers, there are usually a number of useful runner functions.

Lifting

When using monad transformers, you often need to “lift” a monadic action into your transformed monadic action. This is done using the lift function from MonadTrans in the Control.Monad.Trans.Class module:

lift :: (Monad m, MonadTrans t) => m a -> t m a

The action m a is lifted into the transformer action t m a.

As an example, here we lift an action of type IO a into an action of type ExceptT MyError IO a:

data MyError = EmptyLine

mightFail :: ExceptT MyError IO ()
mightFail = do
  l <- lift getLine
  when (null l) (throwError EmptyLine)

Transformers

The following outlines the available monad classes and transformers in MTL and transformers. For more details, and the corresponding documentation of the mtl version you are using, see the documentation on Hackage.

  • Control.Monad.Cont

    The Continuation monad transformer adds the ability to use continuation-passing style (CPS) in a monadic computation. Continuations can be used to manipulate the control flow of a program, e.g. early exit, error handling, or suspending a computation.

    • Class: Control.Monad.Cont.Class.MonadCont
    • Transformer: Control.Monad.Cont.ContT
  • Control.Monad.Error (deprecated!)

    The Error monad transformer has been deprecated in favor of Control.Monad.Except.

  • Control.Monad.Except

    The Except monad transformer adds the ability to fail with an error in a monadic computation.

    • Class: Control.Monad.Except.Class.MonadError
    • Transformer: Control.Monad.Except.ExceptT
  • Control.Monad.Identity

    The Identity monad transformer does not add any abilities to a monad. It simply applies the bound function to its inner monad without any modification.

    • Transformer: Control.Monad.Trans.Identity.IdentityT (in the transformers package)
    • Identity functor and monad: Data.Functor.Identity.Identity (in the base package)
  • Control.Monad.RWS

    A convenient transformer that combines the Reader, Writer, and State monad transformers.

    • Lazy transformer: Control.Monad.RWS.Lazy.RWST (which is the default, exported by Control.Monad.RWS)
    • Strict transformer: Control.Monad.RWS.Strict.RWST
  • Control.Monad.Reader

    The Reader monad transformer represents a computation which can read values from an environment.

    • Class: Control.Monad.Reader.Class.MonadReader
    • Transformer: Control.Monad.Reader.ReaderT
  • Control.Monad.State

    The State monad transformer represents a computation which can read and write internal state values. If you only need to read values, you might want to use Reader instead.

    • Class: Control.Monad.State.Class.MonadState
    • Lazy transformer: Control.Monad.State.Lazy.StateT (the default, exported by Control.Monad.State)
    • Strict transformer: Control.Monad.State.Strict.StateT
  • Control.Monad.Writer

    The Writer monad transformer represents a computation that can produce a stream of data in addition to the computed values. This can be used to collect values in some data structure with a Monoid instance. This can be used for things like logging and accumulating values throughout a computation.

    • Class: Control.Monad.Writer.Class.MonadWriter
    • Lazy transformers: Control.Monad.Writer.Lazy.WriterT
    • Strict transformers: Control.Monad.Writer.Strict.WriterT
  • Control.Monad.Accum

    The Accum monad transformer represents a computation which manages append-only state, or a writer that can read all previous inputs. It binds a function to a monadic value by lazily accumulating subcomputations via (<>). For more general access, use State instead.

    • Class: Control.Monad.Accum
    • Transformer: Control.Monad.Trans.Accum.AccumT
  • Control.Monad.Select

    The Select monad transformer represents a computation which can do backtracking search using a ‘ranked’ evaluation strategy. Binding a function to a monad value chains together evaluation strategies in the sense that the results of previous strategies may influence subsequent rank and evaluation strategies in subcomputations.

    • Class: Control.Monad.Select
    • Transformer: Control.Monad.Trans.Select.SelectT

Resources

Changes

2.3.1 – 2022-09-10

  • Add modifyError to Control.Monad.Error.Class, and re-export from Control.Monad.Except.
  • Make the MonadCont instance for ContT more polykinded; now, r is allowed to be of an arbitrary kind k, rather than only Type.
  • Add a generic liftCallCC for use with any MonadTrans.
  • Add modifyError to Control.Monad.Error.Class
  • Return re-export of ExceptT and related functions to Control.Monad.Except.
  • Add label function to MonadCont

2.3 – 2022-05-07

  • Add instances for Control.Monad.Trans.Writer.CPS and Control.Monad.Trans.RWS.CPS from transformers 0.5.6 and add Control.Monad.Writer.CPS and Control.Monad.RWS.CPS.
  • Control.Monad.Cont now re-exports evalCont and evalContT.
  • Add tryError, withError, handleError, and mapError to Control.Monad.Error.Class, and re-export from Control.Monad.Except.
  • Remove Control.Monad.List and Control.Monad.Error.
  • Remove instances of deprecated ListT and ErrorT.
  • Remove re-exports of Error.
  • Add instances for Control.Monad.Trans.Accum and Control.Monad.Trans.Select.
  • Require GHC 8.6 or higher, and cabal-install 3.0 or higher.
  • Require transformers-0.5.6 or higher.
  • Add Control.Monad.Accum for the MonadAccum type class, as well as the LiftingAccum deriving helper.
  • Add Control.Monad.Select for the MonadSelect type class, as well as the LiftingSelect deriving helper.
  • Remove re-exports of Control.Monad, Control.Monad.Fix and Data.Monoid modules

2.2.2 – 2018-02-24

  • Control.Monad.Identity now re-exports Control.Monad.Trans.Identity
  • Fix a bug in which Control.Monad.State.Class.modify' was not as strict in the new state as its counterparts in transformers
  • Add a MonadError () Maybe instance
  • Add liftEither :: MonadError e m => Either e a -> m a to Control.Monad.Except{.Class}
  • Add a MonadWriter w ((,) w) instance (when built against base-4.9 or later)

2.2.1 – 2014-06-02

  • Provide MINIMAL pragmas for MonadState, MonadWriter, MonadReader
  • Added a cyclic definition of ask in terms of reader for consistency with get/put vs. state and tell vs. writer
  • Fix deprecation warnings caused by transformers 0.4 deprecating ErrorT.
  • Added Control.Monad.Except in the style of the other mtl re-export modules

2.2.0.1 – 2014-05-05

  • Fixed a bug caused by the change in how transformers 0.4 exports its data types. We will now export runFooT for each transformer again!

2.2 – 2014-05-05

  • transformers 0.4 support
  • Added instances for ExceptT
  • Added modify' to Control.Monad.State.*

2.1.3.1 – 2014-03-24

  • Avoid importing Control.Monad.Instances on GHC 7.8 to build without deprecation warnings.

2.1.3

  • Removed the now-irrelevant Error constraint from the MonadError instance for Either e.