New patches:
[Converted the module documentation to Haddock format. Per Jeff Newbern's gracious permission included relevant information from his cool tutorial "All About Monads" http://www.nomaware.com/monads/. Added examples for custom error type, ErrorT. Use String instead of [Char].
Andriy Palamarchuk **20070115222741] {
hunk ./Control/Monad/Error.hs 4

 
 Module : Control.Monad.Error
 Copyright : (c) Michael Weber , 2001
 License : BSDstyle (see the file libraries/base/LICENSE)

 Maintainer : libraries@haskell.org
 Stability : experimental
 Portability : nonportable (multiparameter type classes)

 The Error monad.

 Rendered by Michael Weber ,
 inspired by the Haskell Monad Template Library from
 Andy Gill ()


+{ 
+Module : Control.Monad.Error
+Copyright : (c) Michael Weber 2001,
+ (c) Jeff Newbern 20032006,
+ (c) Andriy Palamarchuk 2006
+License : BSDstyle (see the file libraries/base/LICENSE)
+
+Maintainer : libraries@haskell.org
+Stability : experimental
+Portability : nonportable (multiparameter type classes)
hunk ./Control/Monad/Error.hs 15
+[Computation type:] Computations which may fail or throw exceptions.
+
+[Binding strategy:] Failure records information about the cause\/location
+of the failure. Failure values bypass the bound function,
+other values are used as inputs to the bound function.
+
+[Useful for:] Building computations from sequences of functions that may fail
+or using exception handling to structure error handling.
+
+[Zero and plus:] Zero is represented by an empty error and the plus operation
+executes its second argument if the first fails.
+
+[Example type:] @'Data.Either' String a@
+
+The Error monad (also called the Exception monad).
+}
+
+{
+ Rendered by Michael Weber ,
+ inspired by the Haskell Monad Template Library from
+ Andy Gill ()
+}
hunk ./Control/Monad/Error.hs 45
+  * Example 1: Custom Error Data Type
+  $customErrorExample
+
+  * Example 2: Using ErrorT Monad Transformer
+  $ErrorTExample
hunk ./Control/Monad/Error.hs 66
 
 class MonadError

 throws an exception inside the monad and thus interrupts
 normal execution order, until an error handler is reached}

 catches an exception inside the monad (that was previously
 thrown by throwError

+  An exception to be thrown.
+ An instance must redefine at least one of 'noMsg', 'strMsg'.
hunk ./Control/Monad/Error.hs 69
+   Creates an exception without a message.
+  Default implementation is @'strMsg' \"\"@.
hunk ./Control/Monad/Error.hs 72
+   Creates an exception with a message.
+  Default implementation is 'noMsg'.
hunk ./Control/Monad/Error.hs 76
 noMsg = strMsg ""
 strMsg _ = noMsg
+noMsg = strMsg ""
+strMsg _ = noMsg
hunk ./Control/Monad/Error.hs 79
instance Error [Char] where
+  A string can be thrown as an error.
+instance Error String where
hunk ./Control/Monad/Error.hs 87
+{ 
+The strategy of combining computations that can throw exceptions
+by bypassing bound functions
+from the point an exception is thrown to the point that it is handled.
+
+Is parameterized over the type of error information and
+the monad type constructor.
+It is common to use @'Data.Either' String@ as the monad type constructor
+for an error monad in which error descriptions take the form of strings.
+In that case and many other common cases the resulting monad is already defined
+as an instance of the 'MonadError' class.
+You can also define your own error type and\/or use a monad type constructor
+other than @'Data.Either' String@ or @'Data.Either' IOError@.
+In these cases you will have to explicitly define instances of the 'Error'
+and\/or 'MonadError' classes.
+}
hunk ./Control/Monad/Error.hs 104
+   Is used within a monadic computation to begin exception processing.
hunk ./Control/Monad/Error.hs 106
 catchError :: m a > (e > m a) > m a
+
+ { 
+ A handler function to handle previous errors and return to normal execution.
+ A common idiom is:
+
+ > do { action1; action2; action3 } `catchError` handler
+
+ where the @action@ functions can call 'throwError'.
+ Note that @handler@ and the doblock must have the same return type.
+ }
+ catchError :: m a > (e > m a) > m a
hunk ./Control/Monad/Error.hs 152
 
 Our parameterizable error monad, with an inner monad
+{ 
+The error monad transformer. It can be used to add error handling to other
+monads.
hunk ./Control/Monad/Error.hs 156
newtype ErrorT e m a = ErrorT { runErrorT :: m (Either e a) }
+The @ErrorT@ Monad structure is parameterized over two things:
+
+ * e  The error type.
+
+ * m  The inner monad.
+
+Here are some examples of use:
hunk ./Control/Monad/Error.hs 164
 The ErrorT Monad structure is parameterized over two things:
 * e  The error type.
 * m  The inner monad.
+>  wraps IO action that can throw an error e
+> type ErrorWithIO e a = ErrorT e IO a
+> ==> ErrorT (IO (Either e a))
+>
+>  IO monad wrapped in StateT inside of ErrorT
+> 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)))
+}
+
+newtype ErrorT e m a = ErrorT { runErrorT :: m (Either e a) }
hunk ./Control/Monad/Error.hs 176
 Here are some examples of use:

 type ErrorWithIO e a = ErrorT e IO a
 ==> ErrorT (IO (Either e a))

 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)))

hunk ./Control/Monad/Error.hs 274
+{ $customErrorExample
+Here is an example that demonstrates the use of a custom 'Error' data type with
+the 'ErrorMonad'\'s 'throwError' and 'catchError' exception mechanism.
+The example throws an exception if the user enters an empty string
+or a string longer than 5 characters. Otherwise it prints length of the string.
+
+> This is the type to represent length calculation error.
+>data LengthError = EmptyString  Entered string was empty.
+>  StringTooLong Int  A string is longer than 5 characters.
+>  Records a length of the string.
+>  OtherError String  Other error, stores the problem description.
+>
+> We make LengthError an instance of the Error class
+> to be able to throw it as an exception.
+>instance Error LengthError where
+> noMsg = OtherError "A String Error!"
+> strMsg s = OtherError s
+>
+> Converts LengthError to a readable message.
+>instance Show LengthError where
+> show EmptyString = "The string was empty!"
+> show (StringTooLong len) =
+> "The length of the string (" ++ (show len) ++ ") is bigger than 5!"
+> show (OtherError msg) = msg
+>
+> For our monad type constructor, we use Either LengthError
+> which represents failure using Left LengthError
+> or a successful result of type a using Right a.
+>type LengthMonad = Either LengthError
+>
+>main = do
+> putStrLn "Please enter a string:"
+> s < getLine
+> reportResult (calculateLength s)
+>
+> Wraps length calculation to catch the errors.
+> Returns either length of the string or an error.
+>calculateLength :: String > LengthMonad Int
+>calculateLength s = (calculateLengthOrFail s) `catchError` Left
+>
+> Attempts to calculate length and throws an error if the provided string is
+> empty or longer than 5 characters.
+> The processing is done in Either monad.
+>calculateLengthOrFail :: String > LengthMonad Int
+>calculateLengthOrFail [] = throwError EmptyString
+>calculateLengthOrFail s  len > 5 = throwError (StringTooLong len)
+>  otherwise = return len
+> where len = length s
+>
+> Prints result of the string length calculation.
+>reportResult :: LengthMonad Int > IO ()
+>reportResult (Right len) = putStrLn ("The length of the string is " ++ (show len))
+>reportResult (Left e) = putStrLn ("Length calculation failed with error: " ++ (show e))
+}
+
+{ $ErrorTExample
+@'ErrorT'@ monad transformer can be used to add error handling to another monad.
+Here is an example how to combine it with an @IO@ monad:
+
+>import Control.Monad.Error
+>
+> An IO monad which can return String failure.
+> It is convenient to define the monad type of the combined monad,
+> especially if we combine more monad transformers.
+>type LengthMonad = ErrorT String IO
+>
+>main = do
+>  runErrorT removes the ErrorT wrapper
+> r < runErrorT calculateLength
+> reportResult r
+>
+> Asks user for a nonempty string and returns its length.
+> Throws an error if user enters an empty string.
+>calculateLength :: LengthMonad Int
+>calculateLength = do
+>  all the IO operations have to be lifted to the IO monad in the monad stack
+> liftIO $ putStrLn "Please enter a nonempty string: "
+> s < liftIO getLine
+> if null s
+> then throwError "The string was empty!"
+> else return $ length s
+>
+> Prints result of the string length calculation.
+>reportResult :: Either String Int > IO ()
+>reportResult (Right len) = putStrLn ("The length of the string is " ++ (show len))
+>reportResult (Left e) = putStrLn ("Length calculation failed with error: " ++ (show e))
+}
+
}
Context:
[Added Haddock documentation. Converted the module documentation to Haddock format. Per Jeff Newbern's permission included parts his tutorial "All About Monads" http://www.nomaware.com/monads/.
Andriy Palamarchuk **20061218165621]
[add boilerplate Setup.hs
Ross Paterson **20060928231525]
[use Control.Monad.Instances from base
Ross Paterson **20060410112533]
[Add fallowundecidableinstances to some Control.Monad modules
simonpj@microsoft.com**20060209121334
I have recently tightened up GHC's implementation of the coverage
condition. As a result some of the Control.Monad modules are rejected.
Example:
class (Monad m) => MonadReader r m  m > r where
instance (Monoid w, MonadReader r m) => MonadReader r (WriterT w m)
Here, fv(Writer w m) is not a superset of fv(r).
The flag allows it. I wonder if it's possible to use these modules
to send the type cheker into a loop.
]
[TAG Initial conversion from CVS complete
John Goerzen **20060112154134]
Patch bundle hash:
c6c1462ef1551bf85f5e505aaafbf26177a1c14b