Ticket #1059: error.diff

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 <apa3a@yahoo.com>**20070115222741] {
hunk ./Control/Monad/Error.hs 4
------------------------------------------------------------------------------
--- |
--- Module      :  Control.Monad.Error
--- Copyright   :  (c) Michael Weber <michael.weber@post.rwth-aachen.de>, 2001
--- License     :  BSD-style (see the file libraries/base/LICENSE)
--- 
--- Maintainer  :  libraries@haskell.org
--- Stability   :  experimental
--- Portability :  non-portable (multi-parameter type classes)
---
--- The Error monad.
---
--- Rendered by Michael Weber <mailto:michael.weber@post.rwth-aachen.de>,
---     inspired by the Haskell Monad Template Library from
---     Andy Gill (<http://www.cse.ogi.edu/~andy/>)
---
------------------------------------------------------------------------------
+{- |
+Module      :  Control.Monad.Error
+Copyright   :  (c) Michael Weber <michael.weber@post.rwth-aachen.de> 2001,
+      (c) Jeff Newbern 2003-2006,
+      (c) Andriy Palamarchuk 2006
+License     :  BSD-style (see the file libraries/base/LICENSE)
+ 
+Maintainer  :  libraries@haskell.org
+Stability   :  experimental
+Portability :  non-portable (multi-parameter 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 <mailto:michael.weber@post.rwth-aachen.de>,
+  inspired by the Haskell Monad Template Library from
+    Andy Gill (<http://www.cse.ogi.edu/~andy/>)
+-}
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 do-block 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 non-empty 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 non-empty 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 <apa3a@yahoo.com>**20061218165621] 
[add boilerplate Setup.hs
Ross Paterson <ross@soi.city.ac.uk>**20060928231525] 
[use Control.Monad.Instances from base
Ross Paterson <ross@soi.city.ac.uk>**20060410112533] 
[Add -fallow-undecidable-instances 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 <jgoerzen@complete.org>**20060112154134] 
Patch bundle hash:
c6c1462ef1551bf85f5e505aaafbf26177a1c14b