Control.Exception.Extra

Extra functions for Control.Exception. These functions provide retrying, showing in the presence of exceptions, and functions to catch/ignore exceptions, including monomorphic (no Exception context) versions.

If you want to use a safer set of exceptions see the safe-exceptions package.

Documentation

module Control.Exception

type Partial = HasCallStack

A constraint which documents that a function is partial, and on GHC 8.0 and above produces a stack trace on failure. For example:

myHead :: Partial => [a] -> a
myHead [] = error "bad"
myHead (x:xs) = x

When using Partial with GHC 7.8 or below you need to enable the language feature ConstraintKinds, e.g. {-# LANGUAGE ConstraintKinds #-} at the top of the file.

retry :: Int -> IO a -> IO a

Retry an operation at most n times (n must be positive). If the operation fails the nth time it will throw that final exception.

retry 1 (print "x")  == print "x"
retry 3 (fail "die") == fail "die"

retryBool :: Exception e => (e -> Bool) -> Int -> IO a -> IO a

Retry an operation at most n times (n must be positive), while the exception value and type match a predicate. If the operation fails the nth time it will throw that final exception.

errorWithoutStackTrace :: forall (r :: RuntimeRep) (a :: TYPE r). [Char] -> a

A variant of error that does not produce a stack trace.

Since: base-4.9.0.0

showException :: Show e => e -> IO String

Show a value, but if the result contains exceptions, produce <Exception>. Defined as stringException . show. Particularly useful for printing exceptions to users, remembering that exceptions can themselves contain undefined values.

stringException :: String -> IO String

Fully evaluate an input String. If the String contains embedded exceptions it will produce <Exception>.

stringException "test"                           == pure "test"
stringException ("test" ++ undefined)            == pure "test<Exception>"
stringException ("test" ++ undefined ++ "hello") == pure "test<Exception>"
stringException ['t','e','s','t',undefined]      == pure "test<Exception>"

errorIO :: Partial => String -> IO a

An IO action that when evaluated calls error, in the IO monad. Note that while fail in IO raises an IOException, this function raises an ErrorCall exception with a call stack.

catch (errorIO "Hello") (\(ErrorCall x) -> pure x) == pure "Hello"
seq (errorIO "foo") (print 1) == print 1

assertIO :: Partial => Bool -> IO ()

An IO action that when evaluated calls assert in the IO monad, which throws an AssertionFailed exception if the argument is False. With optimizations enabled (and -fgnore-asserts) this function ignores its argument and does nothing.

catch (assertIO True  >> pure 1) (\(x :: AssertionFailed) -> pure 2) == pure 1
seq (assertIO False) (print 1) == print 1

Exception catching/ignoring

ignore :: IO () -> IO ()

Ignore any exceptions thrown by the action.

ignore (print 1)    == print 1
ignore (fail "die") == pure ()

catch_ :: IO a -> (SomeException -> IO a) -> IO a

A version of catch without the Exception context, restricted to SomeException, so catches all exceptions.

handle_ :: (SomeException -> IO a) -> IO a -> IO a

Like catch_ but for handle

try_ :: IO a -> IO (Either SomeException a)

Like catch_ but for try

catchJust_ :: (SomeException -> Maybe b) -> IO a -> (b -> IO a) -> IO a

Like catch_ but for catchJust

handleJust_ :: (SomeException -> Maybe b) -> (b -> IO a) -> IO a -> IO a

Like catch_ but for handleJust

tryJust_ :: (SomeException -> Maybe b) -> IO a -> IO (Either b a)

Like catch_ but for tryJust

catchBool :: Exception e => (e -> Bool) -> IO a -> (e -> IO a) -> IO a

Catch an exception if the predicate passes, then call the handler with the original exception. As an example:

readFileExists x == catchBool isDoesNotExistError (readFile "myfile") (const $ pure "")

handleBool :: Exception e => (e -> Bool) -> (e -> IO a) -> IO a -> IO a

Like catchBool but for handle.

tryBool :: Exception e => (e -> Bool) -> IO a -> IO (Either e a)

Like catchBool but for try.