Improve "first contact" aspect in README file
authorOskar Wickström <oskar.wickstrom@gmail.com>
Sat, 9 Jun 2018 13:06:05 +0000 (15:06 +0200)
committerOskar Wickström <oskar.wickstrom@gmail.com>
Sun, 10 Jun 2018 12:00:43 +0000 (14:00 +0200)
Added:

* Synopsis/header
* Structure
  * Lifting
  * Transformers
* Resources

README.markdown
mtl.cabal

index d8fa1b4..c475127 100644 (file)
@@ -1,4 +1,145 @@
-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 an implementation of monad transformers, 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 implement
+transformers, providing instances for _all_ the transformer type classes
+in MTL.
+
+The transformers in MTL 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`.
+
+### 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 transformers in MTL. 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 a shared 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.
+
+    - 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>).
index 97ed479..373f908 100644 (file)
--- a/mtl.cabal
+++ b/mtl.cabal
@@ -6,15 +6,12 @@ license-file: LICENSE
 author:       Andy Gill
 maintainer:   Edward Kmett <ekmett@gmail.com>
 category:     Control
-synopsis:     Monad classes, using functional dependencies
+synopsis:     Monad 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 an implementation of monad transformers, using functional
+  dependencies for generic lifting of monadic actions.
 build-type: Simple
 extra-source-files: CHANGELOG.markdown, README.markdown
 tested-with: