extra-1.4.2: Extra functions I use.

Safe Haskell | Safe
Language | Haskell2010

Control.Exception.Extra

Contents

- Exception catching/ignoring

Description

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.

Synopsis

- module Control.Exception
- retry :: Int -> IO a -> IO a
- retryBool :: Exception e => (e -> Bool) -> Int -> IO a -> IO a
- showException :: Show e => e -> IO String
- stringException :: String -> IO String
- errorIO :: String -> IO a
- ignore :: IO () -> IO ()
- catch_ :: IO a -> (SomeException -> IO a) -> IO a
- handle_ :: (SomeException -> IO a) -> IO a -> IO a
- try_ :: IO a -> IO (Either SomeException a)
- catchJust_ :: (SomeException -> Maybe b) -> IO a -> (b -> IO a) -> IO a
- handleJust_ :: (SomeException -> Maybe b) -> (b -> IO a) -> IO a -> IO a
- tryJust_ :: (SomeException -> Maybe b) -> IO a -> IO (Either b a)
- catchBool :: Exception e => (e -> Bool) -> IO a -> (e -> IO a) -> IO a
- handleBool :: Exception e => (e -> Bool) -> (e -> IO a) -> IO a -> IO a
- tryBool :: Exception e => (e -> Bool) -> IO a -> IO (Either e a)

# Documentation

module Control.Exception

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.

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"                           == return "test"
    stringException ("test" ++ undefined)            == return "test<Exception>"
    stringException ("test" ++ undefined ++ "hello") == return "test<Exception>"
    stringException ['t','e','s','t',undefined]      == return "test<Exception>"

errorIO :: String -> IO a

Like error, but in the `IO` monad. Note that while `fail` in `IO` raises an `IOException`, this function raises an `ErrorCall` exception.

    try (errorIO "Hello") == return (Left (ErrorCall "Hello"))

# Exception catching/ignoring

ignore :: IO () -> IO ()

Ignore any exceptions thrown by the action.

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

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 $ return "")

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`.