<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Control.Monad.Trans.Class</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[ window.onload = function () {pageLoad();setSynopsis("mini_Control-Monad-Trans-Class.html");}; //]]> </script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/Control-Monad-Trans-Class.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">transformers-0.2.2.0: Concrete functor and monad transformers</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Portability</th><td>portable</td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Maintainer</th><td>ross@soi.city.ac.uk</td></tr></table><p class="caption">Control.Monad.Trans.Class</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Transformer class </a></li><li><a href="#g:2">Examples </a><ul><li><a href="#g:3">Parsing </a></li><li><a href="#g:4">Parsing and counting </a></li></ul></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>Classes for monad transformers. </p><p>A monad transformer makes new monad out of an existing monad, such that computations of the old monad may be embedded in the new one. To construct a monad with a desired set of features, one typically starts with a base monad, such as <code>Identity</code>, <code>[]</code> or <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/System-IO.html#t:IO">IO</a></code>, and applies a sequence of monad transformers. </p><p>Most monad transformer modules include the special case of applying the transformer to <code>Identity</code>. For example, <code>State s</code> is an abbreviation for <code>StateT s Identity</code>. </p><p>Each monad transformer also comes with an operation <code>run</code><em>XXX</em> to unwrap the transformer, exposing a computation of the inner monad. </p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><span class="keyword">class</span> <a href="#t:MonadTrans">MonadTrans</a> t <span class="keyword">where</span><ul class="subs"><li><a href="#v:lift">lift</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m => m a -> t m a</li></ul></li></ul></div><div id="interface"><h1 id="g:1">Transformer class </h1><div class="top"><p class="src"><span class="keyword">class</span> <a name="t:MonadTrans" class="def">MonadTrans</a> t <span class="keyword">where</span><a href="src/Control-Monad-Trans-Class.html#MonadTrans" class="link">Source</a></p><div class="doc"><p>The class of monad transformers. Instances should satisfy the following laws, which state that <code><a href="Control-Monad-Trans-Class.html#v:lift">lift</a></code> is a transformer of monads: </p><ul><li><pre><code><a href="Control-Monad-Trans-Class.html#v:lift">lift</a></code> . <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#v:return">return</a></code> = <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#v:return">return</a></code></pre></li><li><pre><code><a href="Control-Monad-Trans-Class.html#v:lift">lift</a></code> (m >>= f) = <code><a href="Control-Monad-Trans-Class.html#v:lift">lift</a></code> m >>= (<code><a href="Control-Monad-Trans-Class.html#v:lift">lift</a></code> . f)</pre></li></ul></div><div class="subs methods"><p class="caption">Methods</p><p class="src"><a name="v:lift" class="def">lift</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m => m a -> t m a<a href="src/Control-Monad-Trans-Class.html#lift" class="link">Source</a></p><div class="doc"><p>Lift a computation from the argument monad to the constructed monad. </p></div></div><div class="subs instances"><p id="control.i:MonadTrans" class="caption collapser" onclick="toggleSection('i:MonadTrans')">Instances</p><div id="section.i:MonadTrans" class="show"><table><tr><td class="src"><a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> <a href="Control-Monad-Trans-Identity.html#t:IdentityT">IdentityT</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> <a href="Control-Monad-Trans-List.html#t:ListT">ListT</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> <a href="Control-Monad-Trans-Maybe.html#t:MaybeT">MaybeT</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> (<a href="Control-Monad-Trans-Cont.html#t:ContT">ContT</a> r)</td><td class="doc empty"> </td></tr><tr><td class="src"><a href="Control-Monad-Trans-Error.html#t:Error">Error</a> e => <a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> (<a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e)</td><td class="doc empty"> </td></tr><tr><td class="src"><a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> (<a href="Control-Monad-Trans-Reader.html#t:ReaderT">ReaderT</a> r)</td><td class="doc empty"> </td></tr><tr><td class="src"><a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> (<a href="Control-Monad-Trans-State-Lazy.html#t:StateT">StateT</a> s)</td><td class="doc empty"> </td></tr><tr><td class="src"><a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> (<a href="Control-Monad-Trans-State-Strict.html#t:StateT">StateT</a> s)</td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Monoid.html#t:Monoid">Monoid</a> w => <a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> (<a href="Control-Monad-Trans-Writer-Lazy.html#t:WriterT">WriterT</a> w)</td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Monoid.html#t:Monoid">Monoid</a> w => <a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> (<a href="Control-Monad-Trans-Writer-Strict.html#t:WriterT">WriterT</a> w)</td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Monoid.html#t:Monoid">Monoid</a> w => <a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> (<a href="Control-Monad-Trans-RWS-Lazy.html#t:RWST">RWST</a> r w s)</td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Monoid.html#t:Monoid">Monoid</a> w => <a href="Control-Monad-Trans-Class.html#t:MonadTrans">MonadTrans</a> (<a href="Control-Monad-Trans-RWS-Strict.html#t:RWST">RWST</a> r w s)</td><td class="doc empty"> </td></tr></table></div></div></div><h1 id="g:2">Examples </h1><h2 id="g:3">Parsing </h2><div class="doc"><p>One might define a parsing monad by adding a state (the <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Char.html#t:String">String</a></code> remaining to be parsed) to the <code>[]</code> monad, which provides non-determinism: </p><pre> import Control.Monad.Trans.State type Parser = StateT String [] </pre><p>Then <code>Parser</code> is an instance of <code>MonadPlus</code>: monadic sequencing implements concatenation of parsers, while <code>mplus</code> provides choice. To use parsers, we need a primitive to run a constructed parser on an input string: </p><pre> runParser :: Parser a -> String -> [a] runParser p s = [x | (x, "") <- runStateT p s] </pre><p>Finally, we need a primitive parser that matches a single character, from which arbitrarily complex parsers may be constructed: </p><pre> item :: Parser Char item = do c:cs <- get put cs return c </pre><p>In this example we use the operations <code>get</code> and <code>put</code> from <a href="Control-Monad-Trans-State.html">Control.Monad.Trans.State</a>, which are defined only for monads that are applications of <code>StateT</code>. Alternatively one could use monad classes from other packages, which contain methods <code>get</code> and <code>put</code> with types generalized over all suitable monads. </p></div><h2 id="g:4">Parsing and counting </h2><div class="doc"><p>We can define a parser that also counts by adding a <code>WriterT</code> transformer: </p><pre> import Control.Monad.Trans.Class import Control.Monad.Trans.State import Control.Monad.Trans.Writer import Data.Monoid type Parser = WriterT (Sum Int) (StateT String []) </pre><p>The function that applies a parser must now unwrap each of the monad transformers in turn: </p><pre> runParser :: Parser a -> String -> [(a, Int)] runParser p s = [(x, n) | ((x, Sum n), "") <- runStateT (runWriterT p) s] </pre><p>To define <code>item</code> parser, we need to lift the <code>StateT</code> operations through the <code>WriterT</code> transformers. </p><pre> item :: Parser Char item = do c:cs <- lift get lift (put cs) return c </pre><p>In this case, we were able to do this with <code><a href="Control-Monad-Trans-Class.html#v:lift">lift</a></code>, but operations with more complex types require special lifting functions, which are provided by monad transformers for which they can be implemented. If you use one of packages of monad classes, this lifting is handled automatically by the instances of the classes, and you need only use the generalized methods <code>get</code> and <code>put</code>. </p><p>We can also define a primitive using the Writer: </p><pre> tick :: Parser () tick = tell (Sum 1) </pre><p>Then the parser will keep track of how many <code>tick</code>s it executes. </p></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.9.2</p></div></body></html>