mtl-tf-0.2.1.0: Monad Transformer Library with Type Families

Copyright(c) Michael Weber <michael.weber@post.rwth-aachen.de> 2001
(c) Jeff Newbern 2003-2006
(c) Andriy Palamarchuk 2006
LicenseBSD-style (see the file libraries/base/LICENSE)
Maintainerlibraries@haskell.org
Stabilityexperimental
Portabilitynon-portable (multi-parameter type classes)
Safe HaskellSafe
LanguageHaskell2010

Control.Monad.Except

Contents

Description

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:
Either String a

The Error monad (also called the Exception monad).

Synopsis

Documentation

newtype ExceptT e (m :: * -> *) a :: * -> (* -> *) -> * -> * #

A monad transformer that adds exceptions to other monads.

ExceptT constructs a monad parameterized over two things:

  • e - The exception type.
  • m - The inner monad.

The return function yields a computation that produces the given value, while >>= sequences two subcomputations, exiting on the first exception.

Constructors

ExceptT (m (Either e a)) 

Instances

MonadTrans (ExceptT e) 

Methods

lift :: Monad m => m a -> ExceptT e m a #

Monad m => Monad (ExceptT e m) 

Methods

(>>=) :: ExceptT e m a -> (a -> ExceptT e m b) -> ExceptT e m b #

(>>) :: ExceptT e m a -> ExceptT e m b -> ExceptT e m b #

return :: a -> ExceptT e m a #

fail :: String -> ExceptT e m a #

Functor m => Functor (ExceptT e m) 

Methods

fmap :: (a -> b) -> ExceptT e m a -> ExceptT e m b #

(<$) :: a -> ExceptT e m b -> ExceptT e m a #

MonadFix m => MonadFix (ExceptT e m) 

Methods

mfix :: (a -> ExceptT e m a) -> ExceptT e m a #

MonadFail m => MonadFail (ExceptT e m) 

Methods

fail :: String -> ExceptT e m a #

(Functor m, Monad m) => Applicative (ExceptT e m) 

Methods

pure :: a -> ExceptT e m a #

(<*>) :: ExceptT e m (a -> b) -> ExceptT e m a -> ExceptT e m b #

liftA2 :: (a -> b -> c) -> ExceptT e m a -> ExceptT e m b -> ExceptT e m c #

(*>) :: ExceptT e m a -> ExceptT e m b -> ExceptT e m b #

(<*) :: ExceptT e m a -> ExceptT e m b -> ExceptT e m a #

Foldable f => Foldable (ExceptT e f) 

Methods

fold :: Monoid m => ExceptT e f m -> m #

foldMap :: Monoid m => (a -> m) -> ExceptT e f a -> m #

foldr :: (a -> b -> b) -> b -> ExceptT e f a -> b #

foldr' :: (a -> b -> b) -> b -> ExceptT e f a -> b #

foldl :: (b -> a -> b) -> b -> ExceptT e f a -> b #

foldl' :: (b -> a -> b) -> b -> ExceptT e f a -> b #

foldr1 :: (a -> a -> a) -> ExceptT e f a -> a #

foldl1 :: (a -> a -> a) -> ExceptT e f a -> a #

toList :: ExceptT e f a -> [a] #

null :: ExceptT e f a -> Bool #

length :: ExceptT e f a -> Int #

elem :: Eq a => a -> ExceptT e f a -> Bool #

maximum :: Ord a => ExceptT e f a -> a #

minimum :: Ord a => ExceptT e f a -> a #

sum :: Num a => ExceptT e f a -> a #

product :: Num a => ExceptT e f a -> a #

Traversable f => Traversable (ExceptT e f) 

Methods

traverse :: Applicative f => (a -> f b) -> ExceptT e f a -> f (ExceptT e f b) #

sequenceA :: Applicative f => ExceptT e f (f a) -> f (ExceptT e f a) #

mapM :: Monad m => (a -> m b) -> ExceptT e f a -> m (ExceptT e f b) #

sequence :: Monad m => ExceptT e f (m a) -> m (ExceptT e f a) #

(Eq e, Eq1 m) => Eq1 (ExceptT e m) 

Methods

liftEq :: (a -> b -> Bool) -> ExceptT e m a -> ExceptT e m b -> Bool #

(Ord e, Ord1 m) => Ord1 (ExceptT e m) 

Methods

liftCompare :: (a -> b -> Ordering) -> ExceptT e m a -> ExceptT e m b -> Ordering #

(Read e, Read1 m) => Read1 (ExceptT e m) 

Methods

liftReadsPrec :: (Int -> ReadS a) -> ReadS [a] -> Int -> ReadS (ExceptT e m a) #

liftReadList :: (Int -> ReadS a) -> ReadS [a] -> ReadS [ExceptT e m a] #

liftReadPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec (ExceptT e m a) #

liftReadListPrec :: ReadPrec a -> ReadPrec [a] -> ReadPrec [ExceptT e m a] #

(Show e, Show1 m) => Show1 (ExceptT e m) 

Methods

liftShowsPrec :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> Int -> ExceptT e m a -> ShowS #

liftShowList :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> [ExceptT e m a] -> ShowS #

MonadZip m => MonadZip (ExceptT e m) 

Methods

mzip :: ExceptT e m a -> ExceptT e m b -> ExceptT e m (a, b) #

mzipWith :: (a -> b -> c) -> ExceptT e m a -> ExceptT e m b -> ExceptT e m c #

munzip :: ExceptT e m (a, b) -> (ExceptT e m a, ExceptT e m b) #

MonadIO m => MonadIO (ExceptT e m) 

Methods

liftIO :: IO a -> ExceptT e m a #

(Functor m, Monad m, Monoid e) => Alternative (ExceptT e m) 

Methods

empty :: ExceptT e m a #

(<|>) :: ExceptT e m a -> ExceptT e m a -> ExceptT e m a #

some :: ExceptT e m a -> ExceptT e m [a] #

many :: ExceptT e m a -> ExceptT e m [a] #

(Monad m, Monoid e) => MonadPlus (ExceptT e m) 

Methods

mzero :: ExceptT e m a #

mplus :: ExceptT e m a -> ExceptT e m a -> ExceptT e m a #

MonadState m => MonadState (ExceptT e m) Source # 

Associated Types

type StateType (ExceptT e m :: * -> *) :: * Source #

Methods

get :: ExceptT e m (StateType (ExceptT e m)) Source #

put :: StateType (ExceptT e m) -> ExceptT e m () Source #

MonadReader m => MonadReader (ExceptT e m) Source # 

Associated Types

type EnvType (ExceptT e m :: * -> *) :: * Source #

Methods

ask :: ExceptT e m (EnvType (ExceptT e m)) Source #

local :: (EnvType (ExceptT e m) -> EnvType (ExceptT e m)) -> ExceptT e m a -> ExceptT e m a Source #

Monad m => MonadError (ExceptT e m) Source # 

Associated Types

type ErrorType (ExceptT e m :: * -> *) :: * Source #

Methods

throwError :: ErrorType (ExceptT e m) -> ExceptT e m a Source #

catchError :: ExceptT e m a -> (ErrorType (ExceptT e m) -> ExceptT e m a) -> ExceptT e m a Source #

MonadCont m => MonadCont (ExceptT e m) Source # 

Methods

callCC :: ((a -> ExceptT e m b) -> ExceptT e m a) -> ExceptT e m a Source #

MonadWriter m => MonadWriter (ExceptT e m) Source # 

Associated Types

type WritType (ExceptT e m :: * -> *) :: * Source #

Methods

tell :: WritType (ExceptT e m) -> ExceptT e m () Source #

listen :: ExceptT e m a -> ExceptT e m (a, WritType (ExceptT e m)) Source #

pass :: ExceptT e m (a, WritType (ExceptT e m) -> WritType (ExceptT e m)) -> ExceptT e m a Source #

(Monoid (WritType m), MonadRWS m) => MonadRWS (ExceptT e m) Source # 
(Eq e, Eq1 m, Eq a) => Eq (ExceptT e m a) 

Methods

(==) :: ExceptT e m a -> ExceptT e m a -> Bool #

(/=) :: ExceptT e m a -> ExceptT e m a -> Bool #

(Ord e, Ord1 m, Ord a) => Ord (ExceptT e m a) 

Methods

compare :: ExceptT e m a -> ExceptT e m a -> Ordering #

(<) :: ExceptT e m a -> ExceptT e m a -> Bool #

(<=) :: ExceptT e m a -> ExceptT e m a -> Bool #

(>) :: ExceptT e m a -> ExceptT e m a -> Bool #

(>=) :: ExceptT e m a -> ExceptT e m a -> Bool #

max :: ExceptT e m a -> ExceptT e m a -> ExceptT e m a #

min :: ExceptT e m a -> ExceptT e m a -> ExceptT e m a #

(Read e, Read1 m, Read a) => Read (ExceptT e m a) 

Methods

readsPrec :: Int -> ReadS (ExceptT e m a) #

readList :: ReadS [ExceptT e m a] #

readPrec :: ReadPrec (ExceptT e m a) #

readListPrec :: ReadPrec [ExceptT e m a] #

(Show e, Show1 m, Show a) => Show (ExceptT e m a) 

Methods

showsPrec :: Int -> ExceptT e m a -> ShowS #

show :: ExceptT e m a -> String #

showList :: [ExceptT e m a] -> ShowS #

type StateType (ExceptT e m) Source # 
type StateType (ExceptT e m) = StateType m
type EnvType (ExceptT e m) Source # 
type EnvType (ExceptT e m) = EnvType m
type ErrorType (ExceptT e m) Source # 
type ErrorType (ExceptT e m) = e
type WritType (ExceptT e m) Source # 
type WritType (ExceptT e m) = WritType m

mapExceptT :: (m (Either e a) -> n (Either e' b)) -> ExceptT e m a -> ExceptT e' n b #

Map the unwrapped computation using the given function.

Example 1: Custom Error Data Type

Here is an example that demonstrates the use of a custom Error data type with the throwError and catchError exception mechanism from MonadError. 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))

Example 2: Using ExceptT Monad Transformer

ExceptT 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 = ExceptT String IO

main = do
  -- runExceptT removes the ExceptT wrapper
  r <- runExceptT 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))