2 {-# OPTIONS -fno-implicit-prelude #-}
3 -----------------------------------------------------------------------------
6 -- Copyright : (c) The University of Glasgow, 1992-2002
7 -- License : see libraries/base/LICENSE
9 -- Maintainer : cvs-ghc@haskell.org
10 -- Stability : internal
11 -- Portability : non-portable (GHC Extensions)
13 -- The 'Show' class, and related operations.
15 -----------------------------------------------------------------------------
21 -- Instances for Show: (), [], Bool, Ordering, Int, Char
24 shows, showChar, showString, showParen, showList__, showSpace,
25 showLitChar, protectEsc,
26 intToDigit, showSignedInt,
29 -- Character operations
34 import {-# SOURCE #-} GHC.Err ( error )
39 import GHC.List ( (!!),
40 #ifdef USE_REPORT_PRELUDE
48 %*********************************************************
50 \subsection{The @Show@ class}
52 %*********************************************************
55 -- | The @shows@ functions return a function that prepends the
56 -- output 'String' to an existing 'String'. This allows constant-time
57 -- concatenation of results using function composition.
58 type ShowS = String -> String
60 -- | Conversion of values to readable 'String's.
62 -- Minimal complete definition: 'showsPrec' or 'show'.
64 -- Derived instances of 'Show' have the following properties, which
65 -- are compatible with derived instances of 'Text.Read.Read':
67 -- * The result of 'show' is a syntactically correct Haskell
68 -- expression containing only constants, given the fixity
69 -- declarations in force at the point where the type is declared.
70 -- It contains only the constructor names defined in the data type,
71 -- parentheses, and spaces. When labelled constructor fields are
72 -- used, braces, commas, field names, and equal signs are also used.
74 -- * If the constructor is defined to be an infix operator, then
75 -- 'showsPrec' will produce infix applications of the constructor.
77 -- * the representation will be enclosed in parentheses if the
78 -- precedence of the top-level constructor in @x@ is less than @d@
79 -- (associativity is ignored). Thus, if @d@ is @0@ then the result
80 -- is never surrounded in parentheses; if @d@ is @11@ it is always
81 -- surrounded in parentheses, unless it is an atomic expression.
83 -- * If the constructor is defined using record syntax, then 'show'
84 -- will produce the record-syntax form, with the fields given in the
85 -- same order as the original declaration.
87 -- For example, given the declarations
90 -- > data Tree a = Leaf a | Tree a :^: Tree a
92 -- the derived instance of 'Show' is equivalent to
94 -- > instance (Show a) => Show (Tree a) where
96 -- > showsPrec d (Leaf m) = showParen (d > app_prec) $
97 -- > showString "Leaf " . showsPrec (app_prec+1) m
98 -- > where app_prec = 10
100 -- > showsPrec d (u :^: v) = showParen (d > up_prec) $
101 -- > showsPrec (up_prec+1) u .
102 -- > showString " :^: " .
103 -- > showsPrec (up_prec+1) v
104 -- > where up_prec = 5
106 -- Note that right-associativity of @:^:@ is ignored. For example,
108 -- * @'show' (Leaf 1 :^: Leaf 2 :^: Leaf 3)@ produces the string
109 -- @\"Leaf 1 :^: (Leaf 2 :^: Leaf 3)\"@.
112 -- | Convert a value to a readable 'String'.
114 -- 'showsPrec' should satisfy the law
116 -- > showsPrec d x r ++ s == showsPrec d x (r ++ s)
118 -- Derived instances of 'Text.Read.Read' and 'Show' satisfy the following:
120 -- * @(x,\"\")@ is an element of
121 -- @('Text.Read.readsPrec' d ('showsPrec' d x \"\"))@.
123 -- That is, 'Text.Read.readsPrec' parses the string produced by
124 -- 'showsPrec', and delivers the value that 'showsPrec' started with.
126 showsPrec :: Int -- ^ the operator precedence of the enclosing
127 -- context (a number from @0@ to @11@).
128 -- Function application has precedence @10@.
129 -> a -- ^ the value to be converted to a 'String'
132 -- | A specialised variant of 'showsPrec', using precedence context
133 -- zero, and returning an ordinary 'String'.
136 -- | The method 'showList' is provided to allow the programmer to
137 -- give a specialised way of showing lists of values.
138 -- For example, this is used by the predefined 'Show' instance of
139 -- the 'Char' type, where values of type 'String' should be shown
140 -- in double quotes, rather than between square brackets.
141 showList :: [a] -> ShowS
143 showsPrec _ x s = show x ++ s
145 showList ls s = showList__ shows ls s
147 showList__ :: (a -> ShowS) -> [a] -> ShowS
148 showList__ _ [] s = "[]" ++ s
149 showList__ showx (x:xs) s = '[' : showx x (showl xs)
152 showl (y:ys) = ',' : showx y (showl ys)
154 appPrec, appPrec1 :: Int
155 -- Use unboxed stuff because we don't have overloaded numerics yet
156 appPrec = I# 10# -- Precedence of application:
157 -- one more than the maximum operator precedence of 9
158 appPrec1 = I# 11# -- appPrec + 1
161 %*********************************************************
163 \subsection{Simple Instances}
165 %*********************************************************
169 instance Show () where
170 showsPrec _ () = showString "()"
172 instance Show a => Show [a] where
173 showsPrec _ = showList
175 instance Show Bool where
176 showsPrec _ True = showString "True"
177 showsPrec _ False = showString "False"
179 instance Show Ordering where
180 showsPrec _ LT = showString "LT"
181 showsPrec _ EQ = showString "EQ"
182 showsPrec _ GT = showString "GT"
184 instance Show Char where
185 showsPrec _ '\'' = showString "'\\''"
186 showsPrec _ c = showChar '\'' . showLitChar c . showChar '\''
188 showList cs = showChar '"' . showl cs
189 where showl "" s = showChar '"' s
190 showl ('"':xs) s = showString "\\\"" (showl xs s)
191 showl (x:xs) s = showLitChar x (showl xs s)
192 -- Making 's' an explicit parameter makes it clear to GHC
193 -- that showl has arity 2, which avoids it allocating an extra lambda
194 -- The sticking point is the recursive call to (showl xs), which
195 -- it can't figure out would be ok with arity 2.
197 instance Show Int where
198 showsPrec = showSignedInt
200 instance Show a => Show (Maybe a) where
201 showsPrec _p Nothing s = showString "Nothing" s
202 showsPrec p (Just x) s
203 = (showParen (p > appPrec) $
205 showsPrec appPrec1 x) s
207 instance (Show a, Show b) => Show (Either a b) where
209 (showParen (p > appPrec) $
211 Left a -> showString "Left " . showsPrec appPrec1 a
212 Right b -> showString "Right " . showsPrec appPrec1 b)
217 %*********************************************************
219 \subsection{Show instances for the first few tuples
221 %*********************************************************
224 -- The explicit 's' parameters are important
225 -- Otherwise GHC thinks that "shows x" might take a lot of work to compute
226 -- and generates defns like
227 -- showsPrec _ (x,y) = let sx = shows x; sy = shows y in
228 -- \s -> showChar '(' (sx (showChar ',' (sy (showChar ')' s))))
230 instance (Show a, Show b) => Show (a,b) where
231 showsPrec _ (x,y) s = (showChar '(' . shows x . showChar ',' .
232 shows y . showChar ')')
235 instance (Show a, Show b, Show c) => Show (a, b, c) where
236 showsPrec _ (x,y,z) s = (showChar '(' . shows x . showChar ',' .
237 shows y . showChar ',' .
238 shows z . showChar ')')
241 instance (Show a, Show b, Show c, Show d) => Show (a, b, c, d) where
242 showsPrec _ (w,x,y,z) s = (showChar '(' . shows w . showChar ',' .
243 shows x . showChar ',' .
244 shows y . showChar ',' .
245 shows z . showChar ')')
248 instance (Show a, Show b, Show c, Show d, Show e) => Show (a, b, c, d, e) where
249 showsPrec _ (v,w,x,y,z) s = (showChar '(' . shows v . showChar ',' .
250 shows w . showChar ',' .
251 shows x . showChar ',' .
252 shows y . showChar ',' .
253 shows z . showChar ')')
258 %*********************************************************
260 \subsection{Support code for @Show@}
262 %*********************************************************
265 -- | equivalent to 'showsPrec' with a precedence of 0.
266 shows :: (Show a) => a -> ShowS
267 shows = showsPrec zeroInt
269 -- | utility function converting a 'Char' to a show function that
270 -- simply prepends the character unchanged.
271 showChar :: Char -> ShowS
274 -- | utility function converting a 'String' to a show function that
275 -- simply prepends the string unchanged.
276 showString :: String -> ShowS
279 -- | utility function that surrounds the inner show function with
280 -- parentheses when the 'Bool' parameter is 'True'.
281 showParen :: Bool -> ShowS -> ShowS
282 showParen b p = if b then showChar '(' . p . showChar ')' else p
285 showSpace = {-showChar ' '-} \ xs -> ' ' : xs
288 Code specific for characters
291 -- | Convert a character to a string using only printable characters,
292 -- using Haskell source-language escape conventions. For example:
294 -- > showLitChar '\n' s = "\\n" ++ s
296 showLitChar :: Char -> ShowS
297 showLitChar c s | c > '\DEL' = showChar '\\' (protectEsc isDec (shows (ord c)) s)
298 showLitChar '\DEL' s = showString "\\DEL" s
299 showLitChar '\\' s = showString "\\\\" s
300 showLitChar c s | c >= ' ' = showChar c s
301 showLitChar '\a' s = showString "\\a" s
302 showLitChar '\b' s = showString "\\b" s
303 showLitChar '\f' s = showString "\\f" s
304 showLitChar '\n' s = showString "\\n" s
305 showLitChar '\r' s = showString "\\r" s
306 showLitChar '\t' s = showString "\\t" s
307 showLitChar '\v' s = showString "\\v" s
308 showLitChar '\SO' s = protectEsc (== 'H') (showString "\\SO") s
309 showLitChar c s = showString ('\\' : asciiTab!!ord c) s
310 -- I've done manual eta-expansion here, becuase otherwise it's
311 -- impossible to stop (asciiTab!!ord) getting floated out as an MFE
313 isDec c = c >= '0' && c <= '9'
315 protectEsc :: (Char -> Bool) -> ShowS -> ShowS
316 protectEsc p f = f . cont
317 where cont s@(c:_) | p c = "\\&" ++ s
322 asciiTab = -- Using an array drags in the array module. listArray ('\NUL', ' ')
323 ["NUL", "SOH", "STX", "ETX", "EOT", "ENQ", "ACK", "BEL",
324 "BS", "HT", "LF", "VT", "FF", "CR", "SO", "SI",
325 "DLE", "DC1", "DC2", "DC3", "DC4", "NAK", "SYN", "ETB",
326 "CAN", "EM", "SUB", "ESC", "FS", "GS", "RS", "US",
330 Code specific for Ints.
333 -- | Convert an 'Int' in the range @0@..@15@ to the corresponding single
334 -- digit 'Char'. This function fails on other inputs, and generates
335 -- lower-case hexadecimal digits.
336 intToDigit :: Int -> Char
338 | i >=# 0# && i <=# 9# = unsafeChr (ord '0' `plusInt` I# i)
339 | i >=# 10# && i <=# 15# = unsafeChr (ord 'a' `minusInt` ten `plusInt` I# i)
340 | otherwise = error ("Char.intToDigit: not a digit " ++ show (I# i))
344 showSignedInt :: Int -> Int -> ShowS
345 showSignedInt (I# p) (I# n) r
346 | n <# 0# && p ># 6# = '(' : itos n (')' : r)
347 | otherwise = itos n r
349 itos :: Int# -> String -> String
353 in if n'# <# 0# -- minInt?
354 then '-' : itos' (negateInt# (n'# `quotInt#` 10#))
355 (itos' (negateInt# (n'# `remInt#` 10#)) cs)
356 else '-' : itos' n'# cs
357 | otherwise = itos' n# cs
359 itos' :: Int# -> String -> String
361 | n# <# 10# = C# (chr# (ord# '0'# +# n#)) : cs
362 | otherwise = case chr# (ord# '0'# +# (n# `remInt#` 10#)) of { c# ->
363 itos' (n# `quotInt#` 10#) (C# c# : cs) }