<!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.Error</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-Error.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/Control-Monad-Trans-Error.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.Error</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">The ErrorT monad transformer
</a></li><li><a href="#g:2">Error operations
</a></li><li><a href="#g:3">Lifting other operations
</a></li><li><a href="#g:4">Examples
</a></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>This monad transformer adds the ability to fail or throw exceptions
to a monad.
</p><p>A sequence of actions succeeds, producing a value, only if all the
actions in the sequence are successful. If one fails with an error,
the rest of the sequence is skipped and the composite action fails
with that error.
</p><p>If the value of the error is not required, the variant in
<a href="Control-Monad-Trans-Maybe.html">Control.Monad.Trans.Maybe</a> may be used instead.
</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:Error">Error</a> a <span class="keyword">where</span><ul class="subs"><li><a href="#v:noMsg">noMsg</a> :: a</li><li><a href="#v:strMsg">strMsg</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Char.html#t:String">String</a> -> a</li></ul></li><li class="src short"><span class="keyword">class</span> <a href="#t:ErrorList">ErrorList</a> a <span class="keyword">where</span><ul class="subs"><li><a href="#v:listMsg">listMsg</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Char.html#t:String">String</a> -> [a]</li></ul></li><li class="src short"><span class="keyword">newtype</span> <a href="#t:ErrorT">ErrorT</a> e m a = <a href="#v:ErrorT">ErrorT</a> {<ul class="subs"><li><a href="#v:runErrorT">runErrorT</a> :: m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a)</li></ul>}</li><li class="src short"><a href="#v:mapErrorT">mapErrorT</a> :: (m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a) -> n (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e' b)) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e' n b</li><li class="src short"><a href="#v:throwError">throwError</a> :: (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m, <a href="Control-Monad-Trans-Error.html#t:Error">Error</a> e) => e -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a</li><li class="src short"><a href="#v:catchError">catchError</a> :: (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m, <a href="Control-Monad-Trans-Error.html#t:Error">Error</a> e) => <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a -> (e -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a</li><li class="src short"><a href="#v:liftCallCC">liftCallCC</a> :: (((<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a -> m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e b)) -> m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a)) -> m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a)) -> ((a -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m b) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a</li><li class="src short"><a href="#v:liftListen">liftListen</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m => (m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a) -> m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a, w)) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m (a, w)</li><li class="src short"><a href="#v:liftPass">liftPass</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m => (m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a, w -> w) -> m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a)) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m (a, w -> w) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a</li></ul></div><div id="interface"><h1 id="g:1">The ErrorT monad transformer
</h1><div class="top"><p class="src"><span class="keyword">class</span> <a name="t:Error" class="def">Error</a> a <span class="keyword">where</span><a href="src/Control-Monad-Trans-Error.html#Error" class="link">Source</a></p><div class="doc"><p>An exception to be thrown.
</p><p>Minimal complete definition: <code><a href="Control-Monad-Trans-Error.html#v:noMsg">noMsg</a></code> or <code><a href="Control-Monad-Trans-Error.html#v:strMsg">strMsg</a></code>.
</p></div><div class="subs methods"><p class="caption">Methods</p><p class="src"><a name="v:noMsg" class="def">noMsg</a> :: a<a href="src/Control-Monad-Trans-Error.html#noMsg" class="link">Source</a></p><div class="doc"><p>Creates an exception without a message.
The default implementation is <code><code><a href="Control-Monad-Trans-Error.html#v:strMsg">strMsg</a></code> ""</code>.
</p></div><p class="src"><a name="v:strMsg" class="def">strMsg</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Char.html#t:String">String</a> -> a<a href="src/Control-Monad-Trans-Error.html#strMsg" class="link">Source</a></p><div class="doc"><p>Creates an exception with a message.
The default implementation of <code><code><a href="Control-Monad-Trans-Error.html#v:strMsg">strMsg</a></code> s</code> is <code><a href="Control-Monad-Trans-Error.html#v:noMsg">noMsg</a></code>.
</p></div></div><div class="subs instances"><p id="control.i:Error" class="caption collapser" onclick="toggleSection('i:Error')">Instances</p><div id="section.i:Error" class="show"><table><tr><td class="src"><a href="Control-Monad-Trans-Error.html#t:Error">Error</a> <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Exception-Base.html#t:IOException">IOException</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="Control-Monad-Trans-Error.html#t:ErrorList">ErrorList</a> a => <a href="Control-Monad-Trans-Error.html#t:Error">Error</a> [a]</td><td class="doc"><p>A string can be thrown as an error.
</p></td></tr></table></div></div></div><div class="top"><p class="src"><span class="keyword">class</span> <a name="t:ErrorList" class="def">ErrorList</a> a <span class="keyword">where</span><a href="src/Control-Monad-Trans-Error.html#ErrorList" class="link">Source</a></p><div class="doc"><p>Workaround so that we can have a Haskell 98 instance <code><code><a href="Control-Monad-Trans-Error.html#t:Error">Error</a></code> <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Char.html#t:String">String</a></code></code>.
</p></div><div class="subs methods"><p class="caption">Methods</p><p class="src"><a name="v:listMsg" class="def">listMsg</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Char.html#t:String">String</a> -> [a]<a href="src/Control-Monad-Trans-Error.html#listMsg" class="link">Source</a></p></div><div class="subs instances"><p id="control.i:ErrorList" class="caption collapser" onclick="toggleSection('i:ErrorList')">Instances</p><div id="section.i:ErrorList" class="show"><table><tr><td class="src"><a href="Control-Monad-Trans-Error.html#t:ErrorList">ErrorList</a> <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Char.html#t:Char">Char</a></td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><span class="keyword">newtype</span> <a name="t:ErrorT" class="def">ErrorT</a> e m a <a href="src/Control-Monad-Trans-Error.html#ErrorT" class="link">Source</a></p><div class="doc"><p>The error monad transformer. It can be used to add error handling
to other monads.
</p><p>The <code>ErrorT</code> Monad structure is parameterized over two things:
</p><ul><li> e - The error type.
</li><li> m - The inner monad.
</li></ul><p>The <code><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#v:return">return</a></code> function yields a successful computation, while <code>>>=</code>
sequences two subcomputations, failing on the first error.
</p></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:ErrorT" class="def">ErrorT</a></td><td class="doc empty"> </td></tr><tr><td colspan="2"><div class="subs fields"><p class="caption">Fields</p><dl><dt class="src"><a name="v:runErrorT" class="def">runErrorT</a> :: m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a)</dt><dd class="doc empty"> </dd></dl><div class="clear"></div></div></td></tr></table></div><div class="subs instances"><p id="control.i:ErrorT" class="caption collapser" onclick="toggleSection('i:ErrorT')">Instances</p><div id="section.i:ErrorT" class="show"><table><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="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m, <a href="Control-Monad-Trans-Error.html#t:Error">Error</a> e) => <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> (<a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m)</td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Functor">Functor</a> m => <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Functor">Functor</a> (<a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m)</td><td class="doc empty"> </td></tr><tr><td class="src">(<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad-Fix.html#t:MonadFix">MonadFix</a> m, <a href="Control-Monad-Trans-Error.html#t:Error">Error</a> e) => <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad-Fix.html#t:MonadFix">MonadFix</a> (<a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m)</td><td class="doc empty"> </td></tr><tr><td class="src">(<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m, <a href="Control-Monad-Trans-Error.html#t:Error">Error</a> e) => <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:MonadPlus">MonadPlus</a> (<a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m)</td><td class="doc empty"> </td></tr><tr><td class="src">(<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Functor">Functor</a> m, <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m) => <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Applicative.html#t:Applicative">Applicative</a> (<a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m)</td><td class="doc empty"> </td></tr><tr><td class="src">(<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Functor">Functor</a> m, <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m, <a href="Control-Monad-Trans-Error.html#t:Error">Error</a> e) => <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Applicative.html#t:Alternative">Alternative</a> (<a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m)</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-IO-Class.html#t:MonadIO">MonadIO</a> m) => <a href="Control-Monad-IO-Class.html#t:MonadIO">MonadIO</a> (<a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m)</td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><a name="v:mapErrorT" class="def">mapErrorT</a> :: (m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a) -> n (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e' b)) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e' n b<a href="src/Control-Monad-Trans-Error.html#mapErrorT" class="link">Source</a></p><div class="doc"><p>Map the unwrapped computation using the given function.
</p><ul><li> <code><code><a href="Control-Monad-Trans-Error.html#v:runErrorT">runErrorT</a></code> (<code><a href="Control-Monad-Trans-Error.html#v:mapErrorT">mapErrorT</a></code> f m) = f (<code><a href="Control-Monad-Trans-Error.html#v:runErrorT">runErrorT</a></code> m</code>)
</li></ul></div></div><h1 id="g:2">Error operations
</h1><div class="top"><p class="src"><a name="v:throwError" class="def">throwError</a> :: (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m, <a href="Control-Monad-Trans-Error.html#t:Error">Error</a> e) => e -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a<a href="src/Control-Monad-Trans-Error.html#throwError" class="link">Source</a></p><div class="doc"><p>Signal an error value <code>e</code>.
</p><ul><li><pre><code><a href="Control-Monad-Trans-Error.html#v:runErrorT">runErrorT</a></code> (<code>throwErrorT</code> e) = <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/Data-Either.html#v:Left">Left</a></code> e)</pre></li></ul></div></div><div class="top"><p class="src"><a name="v:catchError" class="def">catchError</a><a href="src/Control-Monad-Trans-Error.html#catchError" class="link">Source</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m, <a href="Control-Monad-Trans-Error.html#t:Error">Error</a> e)</td><td class="doc empty"> </td></tr><tr><td class="src">=> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a</td><td class="doc"><p>the inner computation
</p></td></tr><tr><td class="src">-> (e -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a)</td><td class="doc"><p>a handler for errors in the inner
computation
</p></td></tr><tr><td class="src">-> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Handle an error.
</p></div></div><h1 id="g:3">Lifting other operations
</h1><div class="top"><p class="src"><a name="v:liftCallCC" class="def">liftCallCC</a> :: (((<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a -> m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e b)) -> m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a)) -> m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a)) -> ((a -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m b) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a<a href="src/Control-Monad-Trans-Error.html#liftCallCC" class="link">Source</a></p><div class="doc"><p>Lift a <code>callCC</code> operation to the new monad.
</p></div></div><div class="top"><p class="src"><a name="v:liftListen" class="def">liftListen</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m => (m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a) -> m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a, w)) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m (a, w)<a href="src/Control-Monad-Trans-Error.html#liftListen" class="link">Source</a></p><div class="doc"><p>Lift a <code>listen</code> operation to the new monad.
</p></div></div><div class="top"><p class="src"><a name="v:liftPass" class="def">liftPass</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Control-Monad.html#t:Monad">Monad</a> m => (m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a, w -> w) -> m (<a href="/usr/share/doc/ghc/html/libraries/base-4.3.1.0/Data-Either.html#t:Either">Either</a> e a)) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m (a, w -> w) -> <a href="Control-Monad-Trans-Error.html#t:ErrorT">ErrorT</a> e m a<a href="src/Control-Monad-Trans-Error.html#liftPass" class="link">Source</a></p><div class="doc"><p>Lift a <code>pass</code> operation to the new monad.
</p></div></div><h1 id="g:4">Examples
</h1><div class="doc"><p>Wrapping an IO action that can throw an error <code>e</code>:
</p><pre> type ErrorWithIO e a = ErrorT e IO a
==> ErrorT (IO (Either e a))
</pre><p>An IO monad wrapped in <code>StateT</code> inside of <code>ErrorT</code>:
</p><pre> type ErrorAndStateWithIO e s a = ErrorT e (StateT s IO) a
==> ErrorT (StateT s IO (Either e a))
==> ErrorT (StateT (s -> IO (Either e a,s)))
</pre></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>
