Ticket #1059: Control-Monad-Error.html

File Control-Monad-Error.html, 22.2 KB (added by Andriy, 6 years ago)

Version 2 of the haddock output

Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<!--Rendered using the Haskell Html Library v0.2-->
3<HTML>
4<HEAD
5><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8"
6><TITLE
7>Control.Monad.Error</TITLE
8><LINK HREF="haddock.css" REL="stylesheet" TYPE="text/css"
9><SCRIPT SRC="haddock.js" TYPE="text/javascript"
10></SCRIPT
11>
12<style type="text/css">
13/* -------- Global things --------- */
14
15BODY { 
16  background-color: #ffffff;
17  color: #000000;
18  font-family: sans-serif;
19  } 
20
21A:link    { color: #0000e0; text-decoration: none }
22A:visited { color: #0000a0; text-decoration: none }
23A:hover   { background-color: #e0e0ff; text-decoration: none }
24
25TABLE.vanilla {
26  width: 100%;
27  border-width: 0px;
28  /* I can't seem to specify cellspacing or cellpadding properly using CSS... */
29}
30
31TABLE.vanilla2 {
32  border-width: 0px;
33}
34
35/* <TT> font is a little too small in MSIE */
36TT  { font-size: 100%; }
37PRE { font-size: 100%; }
38
39LI P { margin: 0pt } 
40
41TD {
42  border-width: 0px;
43}
44
45TABLE.narrow {
46  border-width: 0px;
47}
48
49TD.s8  {  height: 8px;  }
50TD.s15 {  height: 15px; }
51
52SPAN.keyword { text-decoration: underline; }
53
54/* Resize the buttom image to match the text size */
55IMG.coll { width : 0.75em; height: 0.75em; margin-bottom: 0; margin-right: 0.5em }
56
57/* --------- Contents page ---------- */
58
59DIV.node {
60  padding-left: 3em;
61}
62
63DIV.cnode {
64  padding-left: 1.75em;
65}
66
67SPAN.pkg {
68  position: absolute;
69  left: 50em;
70}
71
72/* --------- Documentation elements ---------- */
73
74TD.children {
75  padding-left: 25px;
76  }
77
78TD.synopsis {
79  padding: 2px;
80  background-color: #f0f0f0;
81  font-family: monospace
82 }
83
84TD.decl { 
85  padding: 2px;
86  background-color: #f0f0f0; 
87  font-family: monospace;
88  vertical-align: top;
89  }
90
91/*
92  arg is just like decl, except that wrapping is not allowed.  It is
93  used for function and constructor arguments which have a text box
94  to the right, where if wrapping is allowed the text box squashes up
95  the declaration by wrapping it.
96*/
97TD.arg { 
98  padding: 2px;
99  background-color: #f0f0f0; 
100  font-family: monospace;
101  vertical-align: top;
102  white-space: nowrap;
103  }
104
105TD.recfield { padding-left: 20px }
106
107TD.doc  { 
108  padding-top: 2px;
109  padding-left: 10px;
110  }
111
112TD.ndoc  { 
113  padding: 2px;
114  }
115
116TD.rdoc  { 
117  padding: 2px;
118  padding-left: 10px;
119  width: 100%;
120  }
121
122TD.body  { 
123  padding-left: 10px
124  }
125
126TD.pkg {
127  width: 100%;
128  padding-left: 10px
129}
130
131TD.indexentry {
132  vertical-align: top;
133  padding-right: 10px
134  }
135
136TD.indexannot {
137  vertical-align: top;
138  padding-left: 20px;
139  white-space: nowrap
140  }
141
142TD.indexlinks {
143  width: 100%
144  }
145
146/* ------- Section Headings ------- */
147
148TD.section1 {
149  padding-top: 15px;
150  font-weight: bold;
151  font-size: 150%
152  }
153
154TD.section2 {
155  padding-top: 10px;
156  font-weight: bold;
157  font-size: 130%
158  }
159
160TD.section3 {
161  padding-top: 5px;
162  font-weight: bold;
163  font-size: 110%
164  }
165
166TD.section4 {
167  font-weight: bold;
168  font-size: 100%
169  }
170
171/* -------------- The title bar at the top of the page */
172
173TD.infohead {
174  color: #ffffff;
175  font-weight: bold;
176  padding-right: 10px;
177  text-align: left;
178}
179
180TD.infoval {
181  color: #ffffff;
182  padding-right: 10px;
183  text-align: left;
184}
185
186TD.topbar {
187  background-color: #000099;
188  padding: 5px;
189}
190
191TD.title {
192  color: #ffffff;
193  padding-left: 10px;
194  width: 100%
195  }
196
197TD.topbut {
198  padding-left: 5px;
199  padding-right: 5px;
200  border-left-width: 1px;
201  border-left-color: #ffffff;
202  border-left-style: solid;
203  white-space: nowrap;
204  }
205
206TD.topbut A:link {
207  color: #ffffff
208  }
209
210TD.topbut A:visited {
211  color: #ffff00
212  }
213
214TD.topbut A:hover {
215  background-color: #6060ff;
216  }
217
218TD.topbut:hover {
219  background-color: #6060ff
220  }
221
222TD.modulebar { 
223  background-color: #0077dd;
224  padding: 5px;
225  border-top-width: 1px;
226  border-top-color: #ffffff;
227  border-top-style: solid;
228  }
229
230/* --------- The page footer --------- */
231
232TD.botbar {
233  background-color: #000099;
234  color: #ffffff;
235  padding: 5px
236  }
237TD.botbar A:link {
238  color: #ffffff;
239  text-decoration: underline
240  }
241TD.botbar A:visited {
242  color: #ffff00
243  }
244TD.botbar A:hover {
245  background-color: #6060ff
246  }
247</style>
248
249</HEAD
250><BODY
251><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
252><TR
253><TD CLASS="topbar"
254><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
255><TR
256><TD
257><IMG SRC="haskell_icon.gif" WIDTH="16" HEIGHT="16" ALT=" "
258></TD
259><TD CLASS="title"
260></TD
261><TD CLASS="topbut"
262><A HREF="index.html"
263>Contents</A
264></TD
265><TD CLASS="topbut"
266><A HREF="doc-index.html"
267>Index</A
268></TD
269></TR
270></TABLE
271></TD
272></TR
273><TR
274><TD CLASS="modulebar"
275><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
276><TR
277><TD
278><FONT SIZE="6"
279>Control.Monad.Error</FONT
280></TD
281><TD ALIGN="right"
282><TABLE CLASS="narrow" CELLSPACING="0" CELLPADDING="0"
283><TR
284><TD CLASS="infohead"
285>Portability</TD
286><TD CLASS="infoval"
287>non-portable (multi-parameter type classes)</TD
288></TR
289><TR
290><TD CLASS="infohead"
291>Stability</TD
292><TD CLASS="infoval"
293>experimental</TD
294></TR
295><TR
296><TD CLASS="infohead"
297>Maintainer</TD
298><TD CLASS="infoval"
299>libraries@haskell.org</TD
300></TR
301></TABLE
302></TD
303></TR
304></TABLE
305></TD
306></TR
307><TR
308><TD CLASS="s15"
309></TD
310></TR
311><TR
312><TD
313><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
314><TR
315><TD CLASS="section4"
316><B
317>Contents</B
318></TD
319></TR
320><TR
321><TD
322><DL
323><DT
324><A HREF="#1"
325>Example 1: Custom Error Data Type
326</A
327></DT
328><DT
329><A HREF="#2"
330>Example 2: Using ErrorT Monad Transformer
331</A
332></DT
333></DL
334></TD
335></TR
336></TABLE
337></TD
338></TR
339><TR
340><TD CLASS="s15"
341></TD
342></TR
343><TR
344><TD CLASS="section1"
345>Description</TD
346></TR
347><TR
348><TD CLASS="doc"
349><DL
350><DT
351>Computation type:</DT
352><DD
353> Computations which may fail or throw exceptions.
354</DD
355><DT
356>Binding strategy:</DT
357><DD
358> Failure records information about the cause/location
359of the failure. Failure values bypass the bound function,
360other values are used as inputs to the bound function.
361</DD
362><DT
363>Useful for:</DT
364><DD
365> Building computations from sequences of functions that may fail
366or using exception handling to structure error handling.
367</DD
368><DT
369>Zero and plus:</DT
370><DD
371> Zero is represented by an empty error and the plus operation
372executes its second argument if the first fails.
373</DD
374><DT
375>Example type:</DT
376><DD
377> <TT
378><TT
379><A HREF="Data.html#t%3AEither"
380>Either</A
381></TT
382> String a</TT
383>
384</DD
385></DL
386><P
387>The Error monad (also called the Exception monad).
388</P
389></TD
390></TR
391><TR
392><TD CLASS="s15"
393></TD
394></TR
395><TR
396><TD CLASS="section1"
397>Synopsis</TD
398></TR
399><TR
400><TD CLASS="s15"
401></TD
402></TR
403><TR
404><TD CLASS="body"
405><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
406><TR
407><TD CLASS="decl"
408><SPAN CLASS="keyword"
409>class</SPAN
410> <A HREF="#t%3AError"
411>Error</A
412> a  <SPAN CLASS="keyword"
413>where</SPAN
414></TD
415></TR
416><TR
417><TD CLASS="body"
418><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
419><TR
420><TD CLASS="decl"
421><A HREF="#v%3AnoMsg"
422>noMsg</A
423> :: a</TD
424></TR
425><TR
426><TD CLASS="decl"
427><A HREF="#v%3AstrMsg"
428>strMsg</A
429> :: String -&gt; a</TD
430></TR
431></TABLE
432></TD
433></TR
434><TR
435><TD CLASS="s8"
436></TD
437></TR
438><TR
439><TD CLASS="decl"
440><SPAN CLASS="keyword"
441>class</SPAN
442> Monad m =&gt; <A HREF="#t%3AMonadError"
443>MonadError</A
444> e m | m -&gt; e <SPAN CLASS="keyword"
445>where</SPAN
446></TD
447></TR
448><TR
449><TD CLASS="body"
450><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
451><TR
452><TD CLASS="decl"
453><A HREF="#v%3AthrowError"
454>throwError</A
455> :: e -&gt; m a</TD
456></TR
457><TR
458><TD CLASS="decl"
459><A HREF="#v%3AcatchError"
460>catchError</A
461> :: m a -&gt; (e -&gt; m a) -&gt; m a</TD
462></TR
463></TABLE
464></TD
465></TR
466><TR
467><TD CLASS="s8"
468></TD
469></TR
470><TR
471><TD CLASS="decl"
472><SPAN CLASS="keyword"
473>newtype</SPAN
474> <A HREF="#t%3AErrorT"
475>ErrorT</A
476> e m a = <A HREF="#v%3AErrorT"
477>ErrorT</A
478> {<TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
479><TR
480><TD CLASS="recfield"
481><A HREF="#v%3ArunErrorT"
482>runErrorT</A
483> :: (m (Either e a))</TD
484></TR
485></TABLE
486>}</TD
487></TR
488><TR
489><TD CLASS="s8"
490></TD
491></TR
492><TR
493><TD CLASS="decl"
494><A HREF="#v%3AmapErrorT"
495>mapErrorT</A
496> :: (m (Either e a) -&gt; n (Either e' b)) -&gt; <A HREF="Control-Monad-Error.html#t%3AErrorT"
497>ErrorT</A
498> e m a -&gt; <A HREF="Control-Monad-Error.html#t%3AErrorT"
499>ErrorT</A
500> e' n b</TD
501></TR
502></TABLE
503></TD
504></TR
505><TR
506><TD CLASS="s15"
507></TD
508></TR
509><TR
510><TD CLASS="section1"
511>Documentation</TD
512></TR
513><TR
514><TD CLASS="s15"
515></TD
516></TR
517><TR
518><TD CLASS="decl"
519><SPAN CLASS="keyword"
520>class</SPAN
521> <A NAME="t%3AError"
522></A
523><B
524>Error</B
525> a  <SPAN CLASS="keyword"
526>where</SPAN
527></TD
528></TR
529><TR
530><TD CLASS="body"
531><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
532><TR
533><TD CLASS="ndoc"
534>An exception to be thrown.
535 An instance must redefine at least one of <TT
536><A HREF="Control-Monad-Error.html#v%3AnoMsg"
537>noMsg</A
538></TT
539>, <TT
540><A HREF="Control-Monad-Error.html#v%3AstrMsg"
541>strMsg</A
542></TT
543>.
544</TD
545></TR
546><TR
547><TD CLASS="s8"
548></TD
549></TR
550><TR
551><TD CLASS="section4"
552>Methods</TD
553></TR
554><TR
555><TD CLASS="body"
556><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
557><TR
558><TD CLASS="decl"
559><A NAME="v%3AnoMsg"
560></A
561><B
562>noMsg</B
563> :: a</TD
564></TR
565><TR
566><TD CLASS="doc"
567>Creates an exception without a message.
568 Default implementation is <TT
569><TT
570><A HREF="Control-Monad-Error.html#v%3AstrMsg"
571>strMsg</A
572></TT
573> &quot;&quot;</TT
574>.
575</TD
576></TR
577><TR
578><TD CLASS="s8"
579></TD
580></TR
581><TR
582><TD CLASS="decl"
583><A NAME="v%3AstrMsg"
584></A
585><B
586>strMsg</B
587> :: String -&gt; a</TD
588></TR
589><TR
590><TD CLASS="doc"
591>Creates an exception with a message.
592 Default implementation is <TT
593><A HREF="Control-Monad-Error.html#v%3AnoMsg"
594>noMsg</A
595></TT
596>.
597</TD
598></TR
599></TABLE
600></TD
601></TR
602><TR
603><TD CLASS="s8"
604></TD
605></TR
606><TR
607><TD CLASS="section4"
608><IMG SRC="minus.gif" CLASS="coll" ONCLICK="toggle(this,'i:Error')" ALT="show/hide"
609> Instances</TD
610></TR
611><TR
612><TD CLASS="body"
613><DIV ID="i:Error" STYLE="display:block;"
614><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0"
615><TR
616><TD CLASS="decl"
617><A HREF="Control-Monad-Error.html#t%3AError"
618>Error</A
619> IOError</TD
620></TR
621><TR
622><TD CLASS="decl"
623><A HREF="Control-Monad-Error.html#t%3AError"
624>Error</A
625> String</TD
626></TR
627></TABLE
628></DIV
629></TD
630></TR
631></TABLE
632></TD
633></TR
634><TR
635><TD CLASS="s15"
636></TD
637></TR
638><TR
639><TD CLASS="decl"
640><SPAN CLASS="keyword"
641>class</SPAN
642> Monad m =&gt; <A NAME="t%3AMonadError"
643></A
644><B
645>MonadError</B
646> e m | m -&gt; e <SPAN CLASS="keyword"
647>where</SPAN
648></TD
649></TR
650><TR
651><TD CLASS="body"
652><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
653><TR
654><TD CLASS="ndoc"
655><P
656>The strategy of combining computations that can throw exceptions
657by bypassing bound functions
658from the point an exception is thrown to the point that it is handled.
659</P
660><P
661>Is parameterized over the type of error information and
662the monad type constructor.
663It is common to use <TT
664><TT
665><A HREF="Data.html#t%3AEither"
666>Either</A
667></TT
668> String</TT
669> as the monad type constructor
670for an error monad in which error descriptions take the form of strings.
671In that case and many other common cases the resulting monad is already defined
672as an instance of the <TT
673><A HREF="Control-Monad-Error.html#t%3AMonadError"
674>MonadError</A
675></TT
676> class.
677You can also define your own error type and/or use a monad type constructor
678other than <TT
679><TT
680><A HREF="Data.html#t%3AEither"
681>Either</A
682></TT
683> String</TT
684> or <TT
685><TT
686><A HREF="Data.html#t%3AEither"
687>Either</A
688></TT
689> IOError</TT
690>.
691In these cases you will have to explicitly define instances of the <TT
692><A HREF="Control-Monad-Error.html#t%3AError"
693>Error</A
694></TT
695>
696and/or <TT
697><A HREF="Control-Monad-Error.html#t%3AMonadError"
698>MonadError</A
699></TT
700> classes.
701</P
702></TD
703></TR
704><TR
705><TD CLASS="s8"
706></TD
707></TR
708><TR
709><TD CLASS="section4"
710>Methods</TD
711></TR
712><TR
713><TD CLASS="body"
714><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
715><TR
716><TD CLASS="decl"
717><A NAME="v%3AthrowError"
718></A
719><B
720>throwError</B
721> :: e -&gt; m a</TD
722></TR
723><TR
724><TD CLASS="doc"
725>Is used within a monadic computation to begin exception processing.
726</TD
727></TR
728><TR
729><TD CLASS="s8"
730></TD
731></TR
732><TR
733><TD CLASS="decl"
734><A NAME="v%3AcatchError"
735></A
736><B
737>catchError</B
738> :: m a -&gt; (e -&gt; m a) -&gt; m a</TD
739></TR
740><TR
741><TD CLASS="doc"
742><P
743>A handler function to handle previous errors and return to normal execution.
744  A common idiom is:
745</P
746><PRE
747> do { action1; action2; action3 } `catchError` handler
748</PRE
749><P
750>where the <TT
751>action</TT
752> functions can call <TT
753><A HREF="Control-Monad-Error.html#v%3AthrowError"
754>throwError</A
755></TT
756>.
757  Note that <TT
758>handler</TT
759> and the do-block must have the same return type.
760</P
761></TD
762></TR
763></TABLE
764></TD
765></TR
766><TR
767><TD CLASS="s8"
768></TD
769></TR
770><TR
771><TD CLASS="section4"
772><IMG SRC="minus.gif" CLASS="coll" ONCLICK="toggle(this,'i:MonadError')" ALT="show/hide"
773> Instances</TD
774></TR
775><TR
776><TD CLASS="body"
777><DIV ID="i:MonadError" STYLE="display:block;"
778><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0"
779><TR
780><TD CLASS="decl"
781><A HREF="Control-Monad-Error.html#t%3AMonadError"
782>MonadError</A
783> IOError IO</TD
784></TR
785><TR
786><TD CLASS="decl"
787><A HREF="Control-Monad-Error.html#t%3AError"
788>Error</A
789> e =&gt; <A HREF="Control-Monad-Error.html#t%3AMonadError"
790>MonadError</A
791> e (Either e)</TD
792></TR
793><TR
794><TD CLASS="decl"
795>(Monad m, <A HREF="Control-Monad-Error.html#t%3AError"
796>Error</A
797> e) =&gt; <A HREF="Control-Monad-Error.html#t%3AMonadError"
798>MonadError</A
799> e (<A HREF="Control-Monad-Error.html#t%3AErrorT"
800>ErrorT</A
801> e m)</TD
802></TR
803><TR
804><TD CLASS="decl"
805><A HREF="Control-Monad-Error.html#t%3AMonadError"
806>MonadError</A
807> e m =&gt; <A HREF="Control-Monad-Error.html#t%3AMonadError"
808>MonadError</A
809> e (ReaderT r m)</TD
810></TR
811><TR
812><TD CLASS="decl"
813><A HREF="Control-Monad-Error.html#t%3AMonadError"
814>MonadError</A
815> e m =&gt; <A HREF="Control-Monad-Error.html#t%3AMonadError"
816>MonadError</A
817> e (<A HREF="Control-Monad-State.html#t%3AStateT"
818>StateT</A
819> s m)</TD
820></TR
821><TR
822><TD CLASS="decl"
823>(Monoid w, <A HREF="Control-Monad-Error.html#t%3AMonadError"
824>MonadError</A
825> e m) =&gt; <A HREF="Control-Monad-Error.html#t%3AMonadError"
826>MonadError</A
827> e (WriterT w m)</TD
828></TR
829><TR
830><TD CLASS="decl"
831>(Monoid w, <A HREF="Control-Monad-Error.html#t%3AMonadError"
832>MonadError</A
833> e m) =&gt; <A HREF="Control-Monad-Error.html#t%3AMonadError"
834>MonadError</A
835> e (RWST r w s m)</TD
836></TR
837></TABLE
838></DIV
839></TD
840></TR
841></TABLE
842></TD
843></TR
844><TR
845><TD CLASS="s15"
846></TD
847></TR
848><TR
849><TD CLASS="decl"
850><SPAN CLASS="keyword"
851>newtype</SPAN
852> <A NAME="t%3AErrorT"
853></A
854><B
855>ErrorT</B
856> e m a</TD
857></TR
858><TR
859><TD CLASS="body"
860><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
861><TR
862><TD CLASS="ndoc"
863><P
864>The error monad transformer. It can be used to add error handling to other
865monads.
866</P
867><P
868>The <TT
869>ErrorT</TT
870> Monad structure is parameterized over two things:
871</P
872><UL
873><LI
874> e - The error type.
875</LI
876><LI
877> m - The inner monad.
878</LI
879></UL
880><P
881>Here are some examples of use:
882</P
883><PRE
884> -- wraps IO action that can throw an error e
885 type ErrorWithIO e a = ErrorT e IO a
886 ==&gt; ErrorT (IO (Either e a))
887
888 -- IO monad wrapped in StateT inside of ErrorT
889 type ErrorAndStateWithIO e s a = ErrorT e (StateT s IO) a
890 ==&gt; ErrorT (StateT s IO (Either e a))
891 ==&gt; ErrorT (StateT (s -&gt; IO (Either e a,s)))
892</PRE
893></TD
894></TR
895><TR
896><TD CLASS="section4"
897>Constructors</TD
898></TR
899><TR
900><TD CLASS="body"
901><TABLE CLASS="vanilla" CELLSPACING="5" CELLPADDING="0"
902><TR
903><TD CLASS="arg"
904><A NAME="v%3AErrorT"
905></A
906><B
907>ErrorT</B
908></TD
909><TD CLASS="rdoc"
910></TD
911></TR
912><TR
913><TD CLASS="body" COLSPAN="2"
914><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0"
915><TR
916><TD CLASS="arg"
917><A NAME="v%3ArunErrorT"
918></A
919><B
920>runErrorT</B
921> :: (m (Either e a))</TD
922><TD CLASS="rdoc"
923></TD
924></TR
925></TABLE
926></TD
927></TR
928></TABLE
929></TD
930></TR
931><TR
932><TD CLASS="section4"
933><IMG SRC="minus.gif" CLASS="coll" ONCLICK="toggle(this,'i:ErrorT')" ALT="show/hide"
934> Instances</TD
935></TR
936><TR
937><TD CLASS="body"
938><DIV ID="i:ErrorT" STYLE="display:block;"
939><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0"
940><TR
941><TD CLASS="decl"
942>(Monad m, <A HREF="Control-Monad-Error.html#t%3AError"
943>Error</A
944> e) =&gt; <A HREF="Control-Monad-Error.html#t%3AMonadError"
945>MonadError</A
946> e (<A HREF="Control-Monad-Error.html#t%3AErrorT"
947>ErrorT</A
948> e m)</TD
949></TR
950><TR
951><TD CLASS="decl"
952>(<A HREF="Control-Monad-Error.html#t%3AError"
953>Error</A
954> e, MonadReader r m) =&gt; MonadReader r (<A HREF="Control-Monad-Error.html#t%3AErrorT"
955>ErrorT</A
956> e m)</TD
957></TR
958><TR
959><TD CLASS="decl"
960>(<A HREF="Control-Monad-Error.html#t%3AError"
961>Error</A
962> e, <A HREF="Control-Monad-State.html#t%3AMonadState"
963>MonadState</A
964> s m) =&gt; <A HREF="Control-Monad-State.html#t%3AMonadState"
965>MonadState</A
966> s (<A HREF="Control-Monad-Error.html#t%3AErrorT"
967>ErrorT</A
968> e m)</TD
969></TR
970><TR
971><TD CLASS="decl"
972>(<A HREF="Control-Monad-Error.html#t%3AError"
973>Error</A
974> e, MonadWriter w m) =&gt; MonadWriter w (<A HREF="Control-Monad-Error.html#t%3AErrorT"
975>ErrorT</A
976> e m)</TD
977></TR
978><TR
979><TD CLASS="decl"
980><A HREF="Control-Monad-Error.html#t%3AError"
981>Error</A
982> e =&gt; MonadTrans (<A HREF="Control-Monad-Error.html#t%3AErrorT"
983>ErrorT</A
984> e)</TD
985></TR
986><TR
987><TD CLASS="decl"
988>Monad m =&gt; Functor (<A HREF="Control-Monad-Error.html#t%3AErrorT"
989>ErrorT</A
990> e m)</TD
991></TR
992><TR
993><TD CLASS="decl"
994>(Monad m, <A HREF="Control-Monad-Error.html#t%3AError"
995>Error</A
996> e) =&gt; Monad (<A HREF="Control-Monad-Error.html#t%3AErrorT"
997>ErrorT</A
998> e m)</TD
999></TR
1000><TR
1001><TD CLASS="decl"
1002>(<A HREF="Control-Monad-Error.html#t%3AError"
1003>Error</A
1004> e, MonadCont m) =&gt; MonadCont (<A HREF="Control-Monad-Error.html#t%3AErrorT"
1005>ErrorT</A
1006> e m)</TD
1007></TR
1008><TR
1009><TD CLASS="decl"
1010>(MonadFix m, <A HREF="Control-Monad-Error.html#t%3AError"
1011>Error</A
1012> e) =&gt; MonadFix (<A HREF="Control-Monad-Error.html#t%3AErrorT"
1013>ErrorT</A
1014> e m)</TD
1015></TR
1016><TR
1017><TD CLASS="decl"
1018>(<A HREF="Control-Monad-Error.html#t%3AError"
1019>Error</A
1020> e, MonadIO m) =&gt; MonadIO (<A HREF="Control-Monad-Error.html#t%3AErrorT"
1021>ErrorT</A
1022> e m)</TD
1023></TR
1024><TR
1025><TD CLASS="decl"
1026>(Monad m, <A HREF="Control-Monad-Error.html#t%3AError"
1027>Error</A
1028> e) =&gt; MonadPlus (<A HREF="Control-Monad-Error.html#t%3AErrorT"
1029>ErrorT</A
1030> e m)</TD
1031></TR
1032></TABLE
1033></DIV
1034></TD
1035></TR
1036></TABLE
1037></TD
1038></TR
1039><TR
1040><TD CLASS="s15"
1041></TD
1042></TR
1043><TR
1044><TD CLASS="decl"
1045><A NAME="v%3AmapErrorT"
1046></A
1047><B
1048>mapErrorT</B
1049> :: (m (Either e a) -&gt; n (Either e' b)) -&gt; <A HREF="Control-Monad-Error.html#t%3AErrorT"
1050>ErrorT</A
1051> e m a -&gt; <A HREF="Control-Monad-Error.html#t%3AErrorT"
1052>ErrorT</A
1053> e' n b</TD
1054></TR
1055><TR
1056><TD CLASS="s15"
1057></TD
1058></TR
1059><TR
1060><TD CLASS="section1"
1061><A NAME="1"
1062>Example 1: Custom Error Data Type
1063</A
1064></TD
1065></TR
1066><TR
1067><TD CLASS="s15"
1068></TD
1069></TR
1070><TR
1071><TD CLASS="doc"
1072><P
1073>Here is an example that demonstrates the use of a custom <TT
1074><A HREF="Control-Monad-Error.html#t%3AError"
1075>Error</A
1076></TT
1077> data type with
1078the ErrorMonad's <TT
1079><A HREF="Control-Monad-Error.html#v%3AthrowError"
1080>throwError</A
1081></TT
1082> and <TT
1083><A HREF="Control-Monad-Error.html#v%3AcatchError"
1084>catchError</A
1085></TT
1086> exception mechanism.
1087The example throws an exception if the user enters an empty string
1088or a string longer than 5 characters. Otherwise it prints length of the string.
1089</P
1090><PRE
1091>-- This is the type to represent length calculation error.
1092data LengthError = EmptyString  -- Entered string was empty.
1093          | StringTooLong Int   -- A string is longer than 5 characters.
1094                                -- Records a length of the string.
1095          | OtherError String   -- Other error, stores the problem description.
1096
1097-- We make LengthError an instance of the Error class
1098-- to be able to throw it as an exception.
1099instance Error LengthError where
1100  noMsg    = OtherError &quot;A String Error!&quot;
1101  strMsg s = OtherError s
1102
1103-- Converts LengthError to a readable message.
1104instance Show LengthError where
1105  show EmptyString = &quot;The string was empty!&quot;
1106  show (StringTooLong len) =
1107      &quot;The length of the string (&quot; ++ (show len) ++ &quot;) is bigger than 5!&quot;
1108  show (OtherError msg) = msg
1109
1110-- For our monad type constructor, we use Either LengthError
1111-- which represents failure using Left LengthError
1112-- or a successful result of type a using Right a.
1113type LengthMonad = Either LengthError
1114
1115main = do
1116  putStrLn &quot;Please enter a string:&quot;
1117  s &lt;- getLine
1118  reportResult (calculateLength s)
1119
1120-- Wraps length calculation to catch the errors.
1121-- Returns either length of the string or an error.
1122calculateLength :: String -&gt; LengthMonad Int
1123calculateLength s = (calculateLengthOrFail s) `catchError` Left
1124
1125-- Attempts to calculate length and throws an error if the provided string is
1126-- empty or longer than 5 characters.
1127-- The processing is done in Either monad.
1128calculateLengthOrFail :: String -&gt; LengthMonad Int
1129calculateLengthOrFail [] = throwError EmptyString
1130calculateLengthOrFail s | len &gt; 5 = throwError (StringTooLong len)
1131                        | otherwise = return len
1132  where len = length s
1133
1134-- Prints result of the string length calculation.
1135reportResult :: LengthMonad Int -&gt; IO ()
1136reportResult (Right len) = putStrLn (&quot;The length of the string is &quot; ++ (show len))
1137reportResult (Left e) = putStrLn (&quot;Length calculation failed with error: &quot; ++ (show e))
1138</PRE
1139></TD
1140></TR
1141><TR
1142><TD CLASS="s15"
1143></TD
1144></TR
1145><TR
1146><TD CLASS="section1"
1147><A NAME="2"
1148>Example 2: Using ErrorT Monad Transformer
1149</A
1150></TD
1151></TR
1152><TR
1153><TD CLASS="s15"
1154></TD
1155></TR
1156><TR
1157><TD CLASS="doc"
1158><P
1159><TT
1160><TT
1161><A HREF="Control-Monad-Error.html#t%3AErrorT"
1162>ErrorT</A
1163></TT
1164></TT
1165> monad transformer can be used to add error handling to another monad.
1166Here is an example how to combine it with an <TT
1167>IO</TT
1168> monad:
1169</P
1170><PRE
1171>import Control.Monad.Error
1172
1173-- An IO monad which can return String failure.
1174-- It is convenient to define the monad type of the combined monad,
1175-- especially if we combine more monad transformers.
1176type LengthMonad = ErrorT String IO
1177
1178main = do
1179  -- runErrorT removes the ErrorT wrapper
1180  r &lt;- runErrorT calculateLength
1181  reportResult r
1182
1183-- Asks user for a non-empty string and returns its length.
1184-- Throws an error if user enters an empty string.
1185calculateLength :: LengthMonad Int
1186calculateLength = do
1187  -- all the IO operations have to be lifted to the IO monad in the monad stack
1188  liftIO $ putStrLn &quot;Please enter a non-empty string: &quot;
1189  s &lt;- liftIO getLine
1190  if null s
1191    then throwError &quot;The string was empty!&quot;
1192    else return $ length s
1193
1194-- Prints result of the string length calculation.
1195reportResult :: Either String Int -&gt; IO ()
1196reportResult (Right len) = putStrLn (&quot;The length of the string is &quot; ++ (show len))
1197reportResult (Left e) = putStrLn (&quot;Length calculation failed with error: &quot; ++ (show e))
1198</PRE
1199></TD
1200></TR
1201><TR
1202><TD CLASS="s15"
1203></TD
1204></TR
1205><TR
1206><TD CLASS="botbar"
1207>Produced by <A HREF="http://www.haskell.org/haddock/"
1208>Haddock</A
1209> version 0.7</TD
1210></TR
1211></TABLE
1212></BODY
1213></HTML
1214>