Documentation fix: MonadFoo instead of StateFoo
[packages/mtl.git] / README.markdown
1 # `mtl` [![Hackage](https://img.shields.io/hackage/v/mtl.svg)](https://hackage.haskell.org/package/mtl) [![Build Status](https://travis-ci.org/haskell/mtl.svg)](https://travis-ci.org/haskell/mtl)
2
3 MTL is a collection of monad classes, extending the `transformers`
4 package, using functional dependencies for generic lifting of monadic
5 actions.
6
7 ## Structure
8
9 Transformers in MTL are divided into classes and data types. Classes
10 define the monadic operations of transformers. Data types, generally
11 from the `transformers` package, implement transformers, and MTL
12 provides instances for all the transformer type classes.
13
14 MTL and `transformers` use a common module, data type, and function
15 naming scheme. As an example, let's imagine we have a transformer
16 `Foo`.
17
18 In the `Control.Monad.Foo` module, we'd find:
19
20 * A type class `MonadFoo` with the transformer operations.
21 * A data type `FooT` with instances for all monad transformer classes.
22 * Functions to run the transformed computation, e.g. `runFooT`. For
23   the actual transformers, there are usually a number of useful runner
24   functions.
25
26 ### Lifting
27
28 When using monad transformers, you often need to "lift" a monadic
29 action into your transformed monadic action. This is done using the
30 `lift` function from `MonadTrans` in the `Control.Monad.Trans.Class`
31 module:
32
33 ``` haskell
34 lift :: (Monad m, MonadTrans t) => m a -> t m a
35 ```
36
37 The action `m a` is lifted into the transformer action `t m a`.
38
39 As an example, here we lift an action of type `IO a` into an action of
40 type `ExceptT MyError IO a`:
41
42 ``` haskell
43 data MyError = EmptyLine
44
45 mightFail :: ExceptT MyError IO ()
46 mightFail = do
47   l <- lift getLine
48   when (null l) (throwError EmptyLine)
49 ```
50
51 ### Transformers
52
53 The following outlines the available monad classes and transformers in
54 MTL and `transformers`. For more details, and the corresponding
55 documentation of the `mtl` version you are using, see [the
56 documentation on Hackage](https://hackage.haskell.org/package/mtl).
57
58 * `Control.Monad.Cont`
59
60     The Continuation monad transformer adds the ability to use
61     [continuation-passing style
62     (CPS)](https://en.wikipedia.org/wiki/Continuation-passing_style)
63     in a monadic computation. Continuations can be used to manipulate
64     the control flow of a program, e.g. early exit, error handling, or
65     suspending a computation.
66
67     - Class: `Control.Monad.Cont.Class.MonadCont`
68     - Transformer: `Control.Monad.Cont.ContT`
69
70 * `Control.Monad.Error` (deprecated!)
71
72     The Error monad transformer has been deprecated in favor of
73     `Control.Monad.Except`.
74
75 * `Control.Monad.Except`
76
77     The Except monad transformer adds the ability to fail with an
78     error in a monadic computation.
79
80     - Class: `Control.Monad.Except.Class.MonadError`
81     - Transformer: `Control.Monad.Except.ExceptT`
82
83 * `Control.Monad.Identity`
84
85     The Identity monad transformer does not add any abilities to a
86     monad. It simply applies the bound function to its inner monad
87     without any modification.
88
89     - Transformer: `Control.Monad.Trans.Identity.IdentityT` (in the `transformers` package)
90     - Identity functor and monad: `Data.Functor.Identity.Identity` (in the `base` package)
91
92 * `Control.Monad.List`
93
94     This transformer combines the list monad with another monad. _Note
95     that this does not yield a monad unless the inner monad is
96     [commutative](https://en.wikipedia.org/wiki/Commutative_property)._
97
98     - Transformer: `Control.Monad.List.ListT`
99
100 * `Control.Monad.RWS`
101
102     A convenient transformer that combines the Reader, Writer, and
103     State monad transformers.
104
105     - Lazy transformer: `Control.Monad.RWS.Lazy.RWST` (which is the default, exported by `Control.Monad.RWS`)
106     - Strict transformer: `Control.Monad.RWS.Strict.RWST`
107
108 * `Control.Monad.Reader`
109
110     The Reader monad transformer represents a computation which can
111     read values from an environment.
112
113     - Class: `Control.Monad.Reader.Class.MonadReader`
114     - Transformer: `Control.Monad.Reader.ReaderT`
115
116 * `Control.Monad.State`
117
118     The State monad transformer represents a computation which can
119     read and write internal state values. If you only need to _read_
120     values, you might want to use
121     [Reader](http://hackage.haskell.org/package/mtl/docs/Control-Monad-Reader.html)
122     instead.
123
124     - Class: `Control.Monad.State.Class.MonadState`
125     - Lazy transformer: `Control.Monad.State.Lazy.StateT` (the default, exported by `Control.Monad.State`)
126     - Strict transformer: `Control.Monad.State.Strict.StateT`
127
128 * `Control.Monad.Writer`
129
130     The Writer monad transformer represents a computation that can
131     produce a stream of data in addition to the computed values. This
132     can be used to collect values in some data structure with a
133     `Monoid` instance. This can be used for things like logging and
134     accumulating values throughout a computation.
135
136     - Class: `Control.Monad.Writer.Class.MonadWriter`
137     - Lazy transformers: `Control.Monad.Writer.Lazy.WriterT`
138     - Strict transformers: `Control.Monad.Writer.Strict.WriterT`
139
140 ## Resources
141
142 * [`mtl` on Hackage](http://hackage.haskell.org/package/mtl)
143 * The [Monad Transformers](http://dev.stephendiehl.com/hask/#monad-transformers)
144   chapter in "What I Wish I Knew When Learning Haskell".
145 * References:
146     - This package is inspired by the paper _Functional Programming
147       with Overloading and Higher-Order Polymorphism_, by Mark P
148       Jones, in _Advanced School of Functional Programming_, 1995
149       (<http://web.cecs.pdx.edu/~mpj/pubs/springschool.html>).