relude-1.2.2.0: Safe, performant, user-friendly and lightweight Haskell Standard Library

Copyright | (c) 2016 Stephen Diehl (c) 2016-2018 Serokell (c) 2018-2023 Kowainik
License | MIT
Maintainer | Kowainik <xrom.xkov@gmail.com>
Stability | Stable
Portability | Portable
Safe Haskell | Safe
Language | Haskell2010

Relude.Exception

Contents

- Control.Exception reexports
- `Bug`s

Description

Re-exports most useful functionality from the Control.Exception module. Also provides some convenient utilities to throw and handle exceptions.

Synopsis

- class (Typeable e, Show e) => Exception e where
  - toException :: e -> SomeException
  - fromException :: SomeException -> Maybe e
  - displayException :: e -> String
  - backtraceDesired :: e -> Bool
- data SomeException = (Exception e, HasExceptionContext) => SomeException e
- data Bug = Bug SomeException CallStack
- bug :: (HasCallStack, Exception e) => e -> a
- pattern Exc :: Exception e => e -> SomeException

# Control.Exception reexports

class (Typeable e, Show e) => Exception e where #

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

Minimal complete definition

Nothing

Methods

toException :: e -> SomeException #

`toException` should produce a `SomeException` with no attached `ExceptionContext`.

fromException :: SomeException -> Maybe e #

displayException :: e -> String #

Render this exception value in a human-friendly manner.

Default implementation: ``show``.

@since base-4.8.0.0

backtraceDesired :: e -> Bool #

#### Instances

Instances details

Exception Timeout | Since: base-4.7.0.0
Instance details Defined in System.Timeout Methods toException :: Timeout -> SomeException # fromException :: SomeException -> Maybe Timeout # displayException :: Timeout -> String # backtraceDesired :: Timeout -> Bool #
Exception SizeOverflowException |
Instance details Defined in Data.ByteString.Internal.Type Methods toException :: SizeOverflowException -> SomeException # fromException :: SomeException -> Maybe SizeOverflowException # displayException :: SizeOverflowException -> String # backtraceDesired :: SizeOverflowException -> Bool #
Exception Void | @since base-4.8.0.0
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: Void -> SomeException # fromException :: SomeException -> Maybe Void # displayException :: Void -> String # backtraceDesired :: Void -> Bool #
Exception ErrorCall | @since base-4.0.0.0
Instance details Defined in GHC.Internal.Exception Methods toException :: ErrorCall -> SomeException # fromException :: SomeException -> Maybe ErrorCall # displayException :: ErrorCall -> String # backtraceDesired :: ErrorCall -> Bool #
Exception ArithException | @since base-4.0.0.0
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: ArithException -> SomeException # fromException :: SomeException -> Maybe ArithException # displayException :: ArithException -> String # backtraceDesired :: ArithException -> Bool #
Exception SomeException | This drops any attached `ExceptionContext`. @since base-3.0
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String # backtraceDesired :: SomeException -> Bool #
Exception AllocationLimitExceeded | @since base-4.8.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: AllocationLimitExceeded -> SomeException # fromException :: SomeException -> Maybe AllocationLimitExceeded # displayException :: AllocationLimitExceeded -> String # backtraceDesired :: AllocationLimitExceeded -> Bool #
Exception ArrayException | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: ArrayException -> SomeException # fromException :: SomeException -> Maybe ArrayException # displayException :: ArrayException -> String # backtraceDesired :: ArrayException -> Bool #
Exception AssertionFailed | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: AssertionFailed -> SomeException # fromException :: SomeException -> Maybe AssertionFailed # displayException :: AssertionFailed -> String # backtraceDesired :: AssertionFailed -> Bool #
Exception AsyncException | @since base-4.7.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: AsyncException -> SomeException # fromException :: SomeException -> Maybe AsyncException # displayException :: AsyncException -> String # backtraceDesired :: AsyncException -> Bool #
Exception BlockedIndefinitelyOnMVar | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: BlockedIndefinitelyOnMVar -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar # displayException :: BlockedIndefinitelyOnMVar -> String # backtraceDesired :: BlockedIndefinitelyOnMVar -> Bool #
Exception BlockedIndefinitelyOnSTM | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: BlockedIndefinitelyOnSTM -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM # displayException :: BlockedIndefinitelyOnSTM -> String # backtraceDesired :: BlockedIndefinitelyOnSTM -> Bool #
Exception CompactionFailed | @since base-4.10.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: CompactionFailed -> SomeException # fromException :: SomeException -> Maybe CompactionFailed # displayException :: CompactionFailed -> String # backtraceDesired :: CompactionFailed -> Bool #
Exception Deadlock | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: Deadlock -> SomeException # fromException :: SomeException -> Maybe Deadlock # displayException :: Deadlock -> String # backtraceDesired :: Deadlock -> Bool #
Exception ExitCode | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: ExitCode -> SomeException # fromException :: SomeException -> Maybe ExitCode # displayException :: ExitCode -> String # backtraceDesired :: ExitCode -> Bool #
Exception FixIOException | @since base-4.11.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: FixIOException -> SomeException # fromException :: SomeException -> Maybe FixIOException # displayException :: FixIOException -> String # backtraceDesired :: FixIOException -> Bool #
Exception IOException | @since base-4.1.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String # backtraceDesired :: IOException -> Bool #
Exception SomeAsyncException | @since base-4.7.0.0
Instance details Defined in GHC.Internal.IO.Exception Methods toException :: SomeAsyncException -> SomeException # fromException :: SomeException -> Maybe SomeAsyncException # displayException :: SomeAsyncException -> String # backtraceDesired :: SomeAsyncException -> Bool #
Exception Bug # |
Instance details Defined in Relude.Exception Methods toException :: Bug -> SomeException # fromException :: SomeException -> Maybe Bug # displayException :: Bug -> String # backtraceDesired :: Bug -> Bool #
Exception UnicodeException |
Instance details Defined in Data.Text.Encoding.Error Methods toException :: UnicodeException -> SomeException # fromException :: SomeException -> Maybe UnicodeException # displayException :: UnicodeException -> String # backtraceDesired :: UnicodeException -> Bool #
Exception a => Exception (ExceptionWithContext a) |
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: ExceptionWithContext a -> SomeException # fromException :: SomeException -> Maybe (ExceptionWithContext a) # displayException :: ExceptionWithContext a -> String # backtraceDesired :: ExceptionWithContext a -> Bool #
Exception e => Exception (NoBacktrace e) |
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: NoBacktrace e -> SomeException # fromException :: SomeException -> Maybe (NoBacktrace e) # displayException :: NoBacktrace e -> String # backtraceDesired :: NoBacktrace e -> Bool #

data SomeException #

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

(Exception e, HasExceptionContext) => SomeException e |

#### Instances

Instances details

Exception SomeException | This drops any attached `ExceptionContext`. @since base-3.0
Instance details Defined in GHC.Internal.Exception.Type Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String # backtraceDesired :: SomeException -> Bool #
Show SomeException | Since: ghc-internal-3.0
Instance details Defined in GHC.Internal.Exception.Type Methods showsPrec :: Int -> SomeException -> ShowS # show :: SomeException -> String # showList :: [SomeException] -> ShowS #

# `Bug`s

data Bug #

Type that represents exceptions used in cases when a particular codepath is not meant to be ever executed, but happens to be executed anyway.

Constructors

Bug SomeException CallStack |

#### Instances

Instances details

Exception Bug # |
Instance details Defined in Relude.Exception Methods toException :: Bug -> SomeException # fromException :: SomeException -> Maybe Bug # displayException :: Bug -> String # backtraceDesired :: Bug -> Bool #
Show Bug # |
Instance details Defined in Relude.Exception Methods showsPrec :: Int -> Bug -> ShowS # show :: Bug -> String # showList :: [Bug] -> ShowS #

bug :: (HasCallStack, Exception e) => e -> a #

Generate a pure value which, when forced, will synchronously throw the exception wrapped into `Bug` data type.

pattern Exc :: Exception e => e -> SomeException #

Pattern synonym to easy pattern matching on exceptions. So instead of writing something like this:

    isNonCriticalExc :: SomeException -> Bool
    isNonCriticalExc e
        | Just (_ :: NodeAttackedError) <- fromException e = True
        | Just DialogUnexpected{} <- fromException e = True
        | otherwise = False

you can use `Exc` pattern synonym:

    isNonCriticalExc :: SomeException -> Bool
    isNonCriticalExc = case
        Exc (_ :: NodeAttackedError) -> True  -- matching all exceptions of type NodeAttackedError
        Exc DialogUnexpected{} -> True
        _ -> False

This pattern is bidirectional. You can use `Exc e` instead of `toException e`.