haskeline-0.7.4.0: A command-line interface for user input, written in Haskell.

Safe Haskell | None
Language | Haskell98

System.Console.Haskeline.MonadException

Contents

- The MonadException class
- Generalizations of Control.Exception
- Helpers for defining "wrapper" functions
- Internal implementation
- Extensible Exceptions

Description

This module redefines some of the functions in Control.Exception to work for more general monads built on top of `IO`.

Synopsis

- class MonadIO m => MonadException m where
- catch :: (MonadException m, Exception e) => m a -> (e -> m a) -> m a
- handle :: (MonadException m, Exception e) => (e -> m a) -> m a -> m a
- catches :: MonadException m => m a -> [Handler m a] -> m a
- data Handler m a = Exception e => Handler (e -> m a)
- finally :: MonadException m => m a -> m b -> m a
- throwIO :: (MonadIO m, Exception e) => e -> m a
- throwTo :: (MonadIO m, Exception e) => ThreadId -> e -> m ()
- bracket :: MonadException m => m a -> (a -> m b) -> (a -> m c) -> m c
- liftIOOp :: MonadException m => ((a -> IO (m b)) -> IO (m c)) -> (a -> m b) -> m c
- liftIOOp_ :: MonadException m => (IO (m a) -> IO (m a)) -> m a -> m a
- newtype RunIO m = RunIO (forall b. m b -> IO (m b))
- class (Typeable * e, Show e) => Exception e
- data SomeException :: * where
  - SomeException :: SomeException
- data IOException :: *

# The MonadException class

class MonadIO m => MonadException m where #

An instance of `MonadException` is generally made up of monad transformers layered on top of the IO monad.

The `controlIO` method enables us to "lift" a function that manages IO actions (such as `bracket` or `catch`) into a function that wraps arbitrary monadic actions.

Minimal complete definition

controlIO

Methods

controlIO :: (RunIO m -> IO (m a)) -> m a #

Instances

MonadException IO # |
Methods controlIO :: (RunIO IO -> IO (IO a)) -> IO a #
MonadException m => MonadException (MaybeT m) # |
Methods controlIO :: (RunIO (MaybeT m) -> IO (MaybeT m a)) -> MaybeT m a #
MonadException m => MonadException (ListT m) # |
Methods controlIO :: (RunIO (ListT m) -> IO (ListT m a)) -> ListT m a #
MonadException m => MonadException (InputT m) # |
Methods controlIO :: (RunIO (InputT m) -> IO (InputT m a)) -> InputT m a #
(Monoid w, MonadException m) => MonadException (WriterT w m) # |
Methods controlIO :: (RunIO (WriterT w m) -> IO (WriterT w m a)) -> WriterT w m a #
MonadException m => MonadException (StateT s m) # |
Methods controlIO :: (RunIO (StateT s m) -> IO (StateT s m a)) -> StateT s m a #
MonadException m => MonadException (IdentityT * m) # |
Methods controlIO :: (RunIO (IdentityT * m) -> IO (IdentityT * m a)) -> IdentityT * m a #
(MonadException m, Error e) => MonadException (ErrorT e m) # |
Methods controlIO :: (RunIO (ErrorT e m) -> IO (ErrorT e m a)) -> ErrorT e m a #
MonadException m => MonadException (ReaderT * r m) # |
Methods controlIO :: (RunIO (ReaderT * r m) -> IO (ReaderT * r m a)) -> ReaderT * r m a #
(Monoid w, MonadException m) => MonadException (RWST r w s m) # |
Methods controlIO :: (RunIO (RWST r w s m) -> IO (RWST r w s m a)) -> RWST r w s m a #

# Generalizations of Control.Exception

catch :: (MonadException m, Exception e) => m a -> (e -> m a) -> m a #

handle :: (MonadException m, Exception e) => (e -> m a) -> m a -> m a #

catches :: MonadException m => m a -> [Handler m a] -> m a #

data Handler m a #

Constructors

Exception e => Handler (e -> m a) |

finally :: MonadException m => m a -> m b -> m a #

throwIO :: (MonadIO m, Exception e) => e -> m a #

throwTo :: (MonadIO m, Exception e) => ThreadId -> e -> m () #

bracket :: MonadException m => m a -> (a -> m b) -> (a -> m c) -> m c #

# Helpers for defining "wrapper" functions

liftIOOp :: MonadException m => ((a -> IO (m b)) -> IO (m c)) -> (a -> m b) -> m c #

Lift a IO operation

    wrap :: (a -> IO b) -> IO b

to a more general monadic operation

    liftIOOp wrap :: MonadException m => (a -> m b) -> m b

For example:

     liftIOOp (withFile f m) :: MonadException m => (Handle -> m r) -> m r
     liftIOOp alloca :: (MonadException m, Storable a) => (Ptr a -> m b) -> m b
     liftIOOp (withForeignPtr fp) :: MonadException m => (Ptr a -> m b) -> m b

liftIOOp_ :: MonadException m => (IO (m a) -> IO (m a)) -> m a -> m a #

Lift an IO operation

    wrap :: IO a -> IO a

to a more general monadic operation

    liftIOOp_ wrap :: MonadException m => m a -> m a

# Internal implementation

newtype RunIO m #

A `RunIO` function takes a monadic action `m` as input, and outputs an IO action which performs the underlying impure part of `m` and returns the '`pure'` part of `m`.

Note that `(RunIO return)` is an incorrect implementation, since it does not separate the pure and impure parts of the monadic action. This module defines implementations for several common monad transformers.

Constructors

RunIO (forall b. m b -> IO (m b)) |

# Extensible Exceptions

class (Typeable * e, Show e) => Exception e Source #

Any type that you wish to throw or catch as an exception must be an instance of the `Exception` class. The simplest case is a new exception type directly below the root:

    data MyException = ThisException | ThatException
        deriving Show

    instance Exception MyException

The default method definitions in the `Exception` class do what we need in this case. You can now throw and catch `ThisException` and `ThatException` as exceptions:

    *Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
    Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

    ---------------------------------------------------------------------
    -- Make the root exception type for all the exceptions in a compiler

    data SomeCompilerException = forall e . Exception e => SomeCompilerException e

    instance Show SomeCompilerException where
        show (SomeCompilerException e) = show e

    instance Exception SomeCompilerException

    compilerExceptionToException :: Exception e => e -> SomeException
    compilerExceptionToException = toException . SomeCompilerException

    compilerExceptionFromException :: Exception e => SomeException -> Maybe e
    compilerExceptionFromException x = do
        SomeCompilerException a <- fromException x
        cast a

    ---------------------------------------------------------------------
    -- Make a subhierarchy for exceptions in the frontend of the compiler

    data SomeFrontendException = forall e . Exception e => SomeFrontendException e

    instance Show SomeFrontendException where
        show (SomeFrontendException e) = show e

    instance Exception SomeFrontendException where
        toException = compilerExceptionToException
        fromException = compilerExceptionFromException

    frontendExceptionToException :: Exception e => e -> SomeException
    frontendExceptionToException = toException . SomeFrontendException

    frontendExceptionFromException :: Exception e => SomeException -> Maybe e
    frontendExceptionFromException x = do
        SomeFrontendException a <- fromException x
        cast a

    ---------------------------------------------------------------------
    -- Make an exception type for a particular frontend compiler exception

    data MismatchedParentheses = MismatchedParentheses
        deriving Show

    instance Exception MismatchedParentheses where
        toException   = frontendExceptionToException
        fromException = frontendExceptionFromException

We can now catch a `MismatchedParentheses` exception as `MismatchedParentheses`, `SomeFrontendException` or `SomeCompilerException`, but not other types, e.g. `IOException`:

    *Main> throw MismatchedParentheses catch e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
    Caught MismatchedParentheses
    *Main> throw MismatchedParentheses catch e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
    Caught MismatchedParentheses
    *Main> throw MismatchedParentheses catch e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
    Caught MismatchedParentheses
    *Main> throw MismatchedParentheses catch e -> putStrLn ("Caught " ++ show (e :: IOException))
    *** Exception: MismatchedParentheses

Instances

Exception PatternMatchFail | Since: 4.0
Methods toException :: PatternMatchFail -> SomeException Source # fromException :: SomeException -> Maybe PatternMatchFail Source # displayException :: PatternMatchFail -> String Source #
Exception RecSelError | Since: 4.0
Methods toException :: RecSelError -> SomeException Source # fromException :: SomeException -> Maybe RecSelError Source # displayException :: RecSelError -> String Source #
Exception RecConError | Since: 4.0
Methods toException :: RecConError -> SomeException Source # fromException :: SomeException -> Maybe RecConError Source # displayException :: RecConError -> String Source #
Exception RecUpdError | Since: 4.0
Methods toException :: RecUpdError -> SomeException Source # fromException :: SomeException -> Maybe RecUpdError Source # displayException :: RecUpdError -> String Source #
Exception NoMethodError | Since: 4.0
Methods toException :: NoMethodError -> SomeException Source # fromException :: SomeException -> Maybe NoMethodError Source # displayException :: NoMethodError -> String Source #
Exception TypeError | Since: 4.9.0.0
Methods toException :: TypeError -> SomeException Source # fromException :: SomeException -> Maybe TypeError Source # displayException :: TypeError -> String Source #
Exception NonTermination | Since: 4.0
Methods toException :: NonTermination -> SomeException Source # fromException :: SomeException -> Maybe NonTermination Source # displayException :: NonTermination -> String Source #
Exception NestedAtomically | Since: 4.0
Methods toException :: NestedAtomically -> SomeException Source # fromException :: SomeException -> Maybe NestedAtomically Source # displayException :: NestedAtomically -> String Source #
Exception BlockedIndefinitelyOnMVar | Since: 4.1.0.0
Methods toException :: BlockedIndefinitelyOnMVar -> SomeException Source # fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar Source # displayException :: BlockedIndefinitelyOnMVar -> String Source #
Exception BlockedIndefinitelyOnSTM | Since: 4.1.0.0
Methods toException :: BlockedIndefinitelyOnSTM -> SomeException Source # fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM Source # displayException :: BlockedIndefinitelyOnSTM -> String Source #
Exception Deadlock | Since: 4.1.0.0
Methods toException :: Deadlock -> SomeException Source # fromException :: SomeException -> Maybe Deadlock Source # displayException :: Deadlock -> String Source #
Exception AllocationLimitExceeded | Since: 4.8.0.0
Methods toException :: AllocationLimitExceeded -> SomeException Source # fromException :: SomeException -> Maybe AllocationLimitExceeded Source # displayException :: AllocationLimitExceeded -> String Source #
Exception CompactionFailed | Since: 4.10.0.0
Methods toException :: CompactionFailed -> SomeException Source # fromException :: SomeException -> Maybe CompactionFailed Source # displayException :: CompactionFailed -> String Source #
Exception AssertionFailed | Since: 4.1.0.0
Methods toException :: AssertionFailed -> SomeException Source # fromException :: SomeException -> Maybe AssertionFailed Source # displayException :: AssertionFailed -> String Source #
Exception SomeAsyncException | Since: 4.7.0.0
Methods toException :: SomeAsyncException -> SomeException Source # fromException :: SomeException -> Maybe SomeAsyncException Source # displayException :: SomeAsyncException -> String Source #
Exception AsyncException | Since: 4.7.0.0
Methods toException :: AsyncException -> SomeException Source # fromException :: SomeException -> Maybe AsyncException Source # displayException :: AsyncException -> String Source #
Exception ArrayException | Since: 4.1.0.0
Methods toException :: ArrayException -> SomeException Source # fromException :: SomeException -> Maybe ArrayException Source # displayException :: ArrayException -> String Source #
Exception ExitCode | Since: 4.1.0.0
Methods toException :: ExitCode -> SomeException Source # fromException :: SomeException -> Maybe ExitCode Source # displayException :: ExitCode -> String Source #
Exception IOException | Since: 4.1.0.0
Methods toException :: IOException -> SomeException Source # fromException :: SomeException -> Maybe IOException Source # displayException :: IOException -> String Source #
Exception ErrorCall | Since: 4.0.0.0
Methods toException :: ErrorCall -> SomeException Source # fromException :: SomeException -> Maybe ErrorCall Source # displayException :: ErrorCall -> String Source #
Exception ArithException | Since: 4.0.0.0
Methods toException :: ArithException -> SomeException Source # fromException :: SomeException -> Maybe ArithException Source # displayException :: ArithException -> String Source #
Exception SomeException | Since: 3.0
Methods toException :: SomeException -> SomeException Source # fromException :: SomeException -> Maybe SomeException Source # displayException :: SomeException -> String Source #
Exception Interrupt # |
Methods toException :: Interrupt -> SomeException Source # fromException :: SomeException -> Maybe Interrupt Source # displayException :: Interrupt -> String Source #

data SomeException :: * where Source #

The `SomeException` type is the root of the exception type hierarchy. When an exception of type `e` is thrown, behind the scenes it is encapsulated in a `SomeException`.

Constructors

SomeException :: SomeException |

Instances

Show SomeException | Since: 3.0
Methods showsPrec :: Int -> SomeException -> ShowS Source # show :: SomeException -> String Source # showList :: [SomeException] -> ShowS Source #
Exception SomeException | Since: 3.0
Methods toException :: SomeException -> SomeException Source # fromException :: SomeException -> Maybe SomeException Source # displayException :: SomeException -> String Source #

data IOException :: * Source #

Exceptions that occur in the `IO` monad. An `IOException` records a more specific error type, a descriptive string and maybe the handle that was used when the error was flagged.

Instances

Eq IOException | Since: 4.1.0.0
Methods (==) :: IOException -> IOException -> Bool # (/=) :: IOException -> IOException -> Bool #
Show IOException | Since: 4.1.0.0
Methods showsPrec :: Int -> IOException -> ShowS Source # show :: IOException -> String Source # showList :: [IOException] -> ShowS Source #
Exception IOException | Since: 4.1.0.0
Methods toException :: IOException -> SomeException Source # fromException :: SomeException -> Maybe IOException Source # displayException :: IOException -> String Source #
Error IOException |
Methods noMsg :: IOException Source # strMsg :: String -> IOException Source #