Unverified Commit 5a137796 authored by Edward Kmett's avatar Edward Kmett Committed by GitHub

Merge pull request #56 from owickstrom/docs

Improve "first contact" aspect in README file
parents 634ece6b dac27e58
The `mtl` Package [![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)
=====================
# `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)
See [`mtl` on Hackage](http://hackage.haskell.org/package/mtl) for more information.
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 `StateFoo` 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:
``` haskell
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`:
``` haskell
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](https://hackage.haskell.org/package/mtl).
* `Control.Monad.Cont`
The Continuation monad transformer adds the ability to use
[continuation-passing style
(CPS)](https://en.wikipedia.org/wiki/Continuation-passing_style)
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.List`
This transformer combines the list monad with another monad. _Note
that this does not yield a monad unless the inner monad is
[commutative](https://en.wikipedia.org/wiki/Commutative_property)._
- Transformer: `Control.Monad.List.ListT`
* `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](http://hackage.haskell.org/package/mtl/docs/Control-Monad-Reader.html)
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`
## Resources
* [`mtl` on Hackage](http://hackage.haskell.org/package/mtl)
* The [Monad Transformers](http://dev.stephendiehl.com/hask/#monad-transformers)
chapter in "What I Wish I Knew When Learning Haskell".
* References:
- This package is inspired by the paper _Functional Programming
with Overloading and Higher-Order Polymorphism_, by Mark P
Jones, in _Advanced School of Functional Programming_, 1995
(<http://web.cecs.pdx.edu/~mpj/pubs/springschool.html>).
......@@ -6,15 +6,13 @@ license-file: LICENSE
author: Andy Gill
maintainer: Edward Kmett <ekmett@gmail.com>
category: Control
synopsis: Monad classes, using functional dependencies
synopsis: Monad classes for transformers, using functional dependencies
homepage: http://github.com/haskell/mtl
bug-reports: http://github.com/haskell/mtl/issues
description:
Monad classes using functional dependencies, with instances
for various monad transformers, inspired by the paper
/Functional Programming with Overloading and Higher-Order Polymorphism/,
by Mark P Jones, in /Advanced School of Functional Programming/, 1995
(<http://web.cecs.pdx.edu/~mpj/pubs/springschool.html>).
MTL is a collection of monad classes, extending the 'transformers'
package, using functional dependencies for generic lifting of
monadic actions.
build-type: Simple
extra-source-files: CHANGELOG.markdown, README.markdown
tested-with:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment