Built-in Natural literals in Core
[ghc.git] / libraries / base / GHC / Exception / Type.hs
1 {-# LANGUAGE Trustworthy #-}
2 {-# LANGUAGE NoImplicitPrelude
3 , ExistentialQuantification
4 , MagicHash
5 , RecordWildCards
6 , PatternSynonyms
7 #-}
8 {-# OPTIONS_HADDOCK hide #-}
9
10 -----------------------------------------------------------------------------
11 -- |
12 -- Module : GHC.Exception.Type
13 -- Copyright : (c) The University of Glasgow, 1998-2002
14 -- License : see libraries/base/LICENSE
15 --
16 -- Maintainer : cvs-ghc@haskell.org
17 -- Stability : internal
18 -- Portability : non-portable (GHC extensions)
19 --
20 -- Exceptions and exception-handling functions.
21 --
22 -----------------------------------------------------------------------------
23
24 module GHC.Exception.Type
25 ( Exception(..) -- Class
26 , SomeException(..), ArithException(..)
27 , divZeroException, overflowException, ratioZeroDenomException
28 , underflowException
29 ) where
30
31 import Data.Maybe
32 import Data.Typeable (Typeable, cast)
33 -- loop: Data.Typeable -> GHC.Err -> GHC.Exception
34 import GHC.Base
35 import GHC.Show
36
37 {- |
38 The @SomeException@ type is the root of the exception type hierarchy.
39 When an exception of type @e@ is thrown, behind the scenes it is
40 encapsulated in a @SomeException@.
41 -}
42 data SomeException = forall e . Exception e => SomeException e
43
44 -- | @since 3.0
45 instance Show SomeException where
46 showsPrec p (SomeException e) = showsPrec p e
47
48 {- |
49 Any type that you wish to throw or catch as an exception must be an
50 instance of the @Exception@ class. The simplest case is a new exception
51 type directly below the root:
52
53 > data MyException = ThisException | ThatException
54 > deriving Show
55 >
56 > instance Exception MyException
57
58 The default method definitions in the @Exception@ class do what we need
59 in this case. You can now throw and catch @ThisException@ and
60 @ThatException@ as exceptions:
61
62 @
63 *Main> throw ThisException \`catch\` \\e -> putStrLn (\"Caught \" ++ show (e :: MyException))
64 Caught ThisException
65 @
66
67 In more complicated examples, you may wish to define a whole hierarchy
68 of exceptions:
69
70 > ---------------------------------------------------------------------
71 > -- Make the root exception type for all the exceptions in a compiler
72 >
73 > data SomeCompilerException = forall e . Exception e => SomeCompilerException e
74 >
75 > instance Show SomeCompilerException where
76 > show (SomeCompilerException e) = show e
77 >
78 > instance Exception SomeCompilerException
79 >
80 > compilerExceptionToException :: Exception e => e -> SomeException
81 > compilerExceptionToException = toException . SomeCompilerException
82 >
83 > compilerExceptionFromException :: Exception e => SomeException -> Maybe e
84 > compilerExceptionFromException x = do
85 > SomeCompilerException a <- fromException x
86 > cast a
87 >
88 > ---------------------------------------------------------------------
89 > -- Make a subhierarchy for exceptions in the frontend of the compiler
90 >
91 > data SomeFrontendException = forall e . Exception e => SomeFrontendException e
92 >
93 > instance Show SomeFrontendException where
94 > show (SomeFrontendException e) = show e
95 >
96 > instance Exception SomeFrontendException where
97 > toException = compilerExceptionToException
98 > fromException = compilerExceptionFromException
99 >
100 > frontendExceptionToException :: Exception e => e -> SomeException
101 > frontendExceptionToException = toException . SomeFrontendException
102 >
103 > frontendExceptionFromException :: Exception e => SomeException -> Maybe e
104 > frontendExceptionFromException x = do
105 > SomeFrontendException a <- fromException x
106 > cast a
107 >
108 > ---------------------------------------------------------------------
109 > -- Make an exception type for a particular frontend compiler exception
110 >
111 > data MismatchedParentheses = MismatchedParentheses
112 > deriving Show
113 >
114 > instance Exception MismatchedParentheses where
115 > toException = frontendExceptionToException
116 > fromException = frontendExceptionFromException
117
118 We can now catch a @MismatchedParentheses@ exception as
119 @MismatchedParentheses@, @SomeFrontendException@ or
120 @SomeCompilerException@, but not other types, e.g. @IOException@:
121
122 @
123 *Main> throw MismatchedParentheses \`catch\` \\e -> putStrLn (\"Caught \" ++ show (e :: MismatchedParentheses))
124 Caught MismatchedParentheses
125 *Main> throw MismatchedParentheses \`catch\` \\e -> putStrLn (\"Caught \" ++ show (e :: SomeFrontendException))
126 Caught MismatchedParentheses
127 *Main> throw MismatchedParentheses \`catch\` \\e -> putStrLn (\"Caught \" ++ show (e :: SomeCompilerException))
128 Caught MismatchedParentheses
129 *Main> throw MismatchedParentheses \`catch\` \\e -> putStrLn (\"Caught \" ++ show (e :: IOException))
130 *** Exception: MismatchedParentheses
131 @
132
133 -}
134 class (Typeable e, Show e) => Exception e where
135 toException :: e -> SomeException
136 fromException :: SomeException -> Maybe e
137
138 toException = SomeException
139 fromException (SomeException e) = cast e
140
141 -- | Render this exception value in a human-friendly manner.
142 --
143 -- Default implementation: @'show'@.
144 --
145 -- @since 4.8.0.0
146 displayException :: e -> String
147 displayException = show
148
149 -- | @since 3.0
150 instance Exception SomeException where
151 toException se = se
152 fromException = Just
153 displayException (SomeException e) = displayException e
154
155 -- |Arithmetic exceptions.
156 data ArithException
157 = Overflow
158 | Underflow
159 | LossOfPrecision
160 | DivideByZero
161 | Denormal
162 | RatioZeroDenominator -- ^ @since 4.6.0.0
163 deriving ( Eq -- ^ @since 3.0
164 , Ord -- ^ @since 3.0
165 )
166
167 divZeroException, overflowException, ratioZeroDenomException, underflowException :: SomeException
168 divZeroException = toException DivideByZero
169 overflowException = toException Overflow
170 ratioZeroDenomException = toException RatioZeroDenominator
171 underflowException = toException Underflow
172
173 -- | @since 4.0.0.0
174 instance Exception ArithException
175
176 -- | @since 4.0.0.0
177 instance Show ArithException where
178 showsPrec _ Overflow = showString "arithmetic overflow"
179 showsPrec _ Underflow = showString "arithmetic underflow"
180 showsPrec _ LossOfPrecision = showString "loss of precision"
181 showsPrec _ DivideByZero = showString "divide by zero"
182 showsPrec _ Denormal = showString "denormal"
183 showsPrec _ RatioZeroDenominator = showString "Ratio has zero denominator"