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