2 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
3 {-# OPTIONS_HADDOCK hide #-}
4 -----------------------------------------------------------------------------
7 -- Copyright : (c) The University of Glasgow, 1992-2002
8 -- License : see libraries/base/LICENSE
10 -- Maintainer : cvs-ghc@haskell.org
11 -- Stability : internal
12 -- Portability : non-portable (GHC Extensions)
14 -- The 'Show' class, and related operations.
16 -----------------------------------------------------------------------------
23 -- Instances for Show: (), [], Bool, Ordering, Int, Char
26 shows, showChar, showString, showParen, showList__, showSpace,
27 showLitChar, protectEsc,
28 intToDigit, showSignedInt,
31 -- Character operations
39 import GHC.List ( (!!), foldr1
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 _ (a,b) s = show_tuple [shows a, shows b] s
233 instance (Show a, Show b, Show c) => Show (a, b, c) where
234 showsPrec _ (a,b,c) s = show_tuple [shows a, shows b, shows c] s
236 instance (Show a, Show b, Show c, Show d) => Show (a, b, c, d) where
237 showsPrec _ (a,b,c,d) s = show_tuple [shows a, shows b, shows c, shows d] s
239 instance (Show a, Show b, Show c, Show d, Show e) => Show (a, b, c, d, e) where
240 showsPrec _ (a,b,c,d,e) s = show_tuple [shows a, shows b, shows c, shows d, shows e] s
242 instance (Show a, Show b, Show c, Show d, Show e, Show f) => Show (a,b,c,d,e,f) where
243 showsPrec _ (a,b,c,d,e,f) s = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f] s
245 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g)
246 => Show (a,b,c,d,e,f,g) where
247 showsPrec _ (a,b,c,d,e,f,g) s
248 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g] s
250 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h)
251 => Show (a,b,c,d,e,f,g,h) where
252 showsPrec _ (a,b,c,d,e,f,g,h) s
253 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h] s
255 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i)
256 => Show (a,b,c,d,e,f,g,h,i) where
257 showsPrec _ (a,b,c,d,e,f,g,h,i) s
258 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
261 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j)
262 => Show (a,b,c,d,e,f,g,h,i,j) where
263 showsPrec _ (a,b,c,d,e,f,g,h,i,j) s
264 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
267 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k)
268 => Show (a,b,c,d,e,f,g,h,i,j,k) where
269 showsPrec _ (a,b,c,d,e,f,g,h,i,j,k) s
270 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
271 shows i, shows j, shows k] s
273 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
275 => Show (a,b,c,d,e,f,g,h,i,j,k,l) where
276 showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l) s
277 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
278 shows i, shows j, shows k, shows l] s
280 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
282 => Show (a,b,c,d,e,f,g,h,i,j,k,l,m) where
283 showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l,m) s
284 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
285 shows i, shows j, shows k, shows l, shows m] s
287 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
288 Show l, Show m, Show n)
289 => Show (a,b,c,d,e,f,g,h,i,j,k,l,m,n) where
290 showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l,m,n) s
291 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
292 shows i, shows j, shows k, shows l, shows m, shows n] s
294 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
295 Show l, Show m, Show n, Show o)
296 => Show (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) where
297 showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) s
298 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
299 shows i, shows j, shows k, shows l, shows m, shows n, shows o] s
301 show_tuple :: [ShowS] -> ShowS
302 show_tuple ss = showChar '('
303 . foldr1 (\s r -> s . showChar ',' . r) ss
308 %*********************************************************
310 \subsection{Support code for @Show@}
312 %*********************************************************
315 -- | equivalent to 'showsPrec' with a precedence of 0.
316 shows :: (Show a) => a -> ShowS
317 shows = showsPrec zeroInt
319 -- | utility function converting a 'Char' to a show function that
320 -- simply prepends the character unchanged.
321 showChar :: Char -> ShowS
324 -- | utility function converting a 'String' to a show function that
325 -- simply prepends the string unchanged.
326 showString :: String -> ShowS
329 -- | utility function that surrounds the inner show function with
330 -- parentheses when the 'Bool' parameter is 'True'.
331 showParen :: Bool -> ShowS -> ShowS
332 showParen b p = if b then showChar '(' . p . showChar ')' else p
335 showSpace = {-showChar ' '-} \ xs -> ' ' : xs
338 Code specific for characters
341 -- | Convert a character to a string using only printable characters,
342 -- using Haskell source-language escape conventions. For example:
344 -- > showLitChar '\n' s = "\\n" ++ s
346 showLitChar :: Char -> ShowS
347 showLitChar c s | c > '\DEL' = showChar '\\' (protectEsc isDec (shows (ord c)) s)
348 showLitChar '\DEL' s = showString "\\DEL" s
349 showLitChar '\\' s = showString "\\\\" s
350 showLitChar c s | c >= ' ' = showChar c s
351 showLitChar '\a' s = showString "\\a" s
352 showLitChar '\b' s = showString "\\b" s
353 showLitChar '\f' s = showString "\\f" s
354 showLitChar '\n' s = showString "\\n" s
355 showLitChar '\r' s = showString "\\r" s
356 showLitChar '\t' s = showString "\\t" s
357 showLitChar '\v' s = showString "\\v" s
358 showLitChar '\SO' s = protectEsc (== 'H') (showString "\\SO") s
359 showLitChar c s = showString ('\\' : asciiTab!!ord c) s
360 -- I've done manual eta-expansion here, becuase otherwise it's
361 -- impossible to stop (asciiTab!!ord) getting floated out as an MFE
363 isDec c = c >= '0' && c <= '9'
365 protectEsc :: (Char -> Bool) -> ShowS -> ShowS
366 protectEsc p f = f . cont
367 where cont s@(c:_) | p c = "\\&" ++ s
372 asciiTab = -- Using an array drags in the array module. listArray ('\NUL', ' ')
373 ["NUL", "SOH", "STX", "ETX", "EOT", "ENQ", "ACK", "BEL",
374 "BS", "HT", "LF", "VT", "FF", "CR", "SO", "SI",
375 "DLE", "DC1", "DC2", "DC3", "DC4", "NAK", "SYN", "ETB",
376 "CAN", "EM", "SUB", "ESC", "FS", "GS", "RS", "US",
380 Code specific for Ints.
383 -- | Convert an 'Int' in the range @0@..@15@ to the corresponding single
384 -- digit 'Char'. This function fails on other inputs, and generates
385 -- lower-case hexadecimal digits.
386 intToDigit :: Int -> Char
388 | i >=# 0# && i <=# 9# = unsafeChr (ord '0' `plusInt` I# i)
389 | i >=# 10# && i <=# 15# = unsafeChr (ord 'a' `minusInt` ten `plusInt` I# i)
390 | otherwise = error ("Char.intToDigit: not a digit " ++ show (I# i))
394 showSignedInt :: Int -> Int -> ShowS
395 showSignedInt (I# p) (I# n) r
396 | n <# 0# && p ># 6# = '(' : itos n (')' : r)
397 | otherwise = itos n r
399 itos :: Int# -> String -> String
402 let I# minInt# = minInt in
404 -- negateInt# minInt overflows, so we can't do that:
405 then '-' : itos' (negateInt# (n# `quotInt#` 10#))
406 (itos' (negateInt# (n# `remInt#` 10#)) cs)
407 else '-' : itos' (negateInt# n#) cs
408 | otherwise = itos' n# cs
410 itos' :: Int# -> String -> String
412 | n# <# 10# = C# (chr# (ord# '0'# +# n#)) : cs
413 | otherwise = case chr# (ord# '0'# +# (n# `remInt#` 10#)) of { c# ->
414 itos' (n# `quotInt#` 10#) (C# c# : cs) }