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, showMultiLineString,
27 showParen, showList__, showSpace,
28 showLitChar, showLitString, protectEsc,
29 intToDigit, showSignedInt,
32 -- Character operations
39 import GHC.List ((!!), foldr1, break)
44 %*********************************************************
46 \subsection{The @Show@ class}
48 %*********************************************************
51 -- | The @shows@ functions return a function that prepends the
52 -- output 'String' to an existing 'String'. This allows constant-time
53 -- concatenation of results using function composition.
54 type ShowS = String -> String
56 -- | Conversion of values to readable 'String's.
58 -- Minimal complete definition: 'showsPrec' or 'show'.
60 -- Derived instances of 'Show' have the following properties, which
61 -- are compatible with derived instances of 'Text.Read.Read':
63 -- * The result of 'show' is a syntactically correct Haskell
64 -- expression containing only constants, given the fixity
65 -- declarations in force at the point where the type is declared.
66 -- It contains only the constructor names defined in the data type,
67 -- parentheses, and spaces. When labelled constructor fields are
68 -- used, braces, commas, field names, and equal signs are also used.
70 -- * If the constructor is defined to be an infix operator, then
71 -- 'showsPrec' will produce infix applications of the constructor.
73 -- * the representation will be enclosed in parentheses if the
74 -- precedence of the top-level constructor in @x@ is less than @d@
75 -- (associativity is ignored). Thus, if @d@ is @0@ then the result
76 -- is never surrounded in parentheses; if @d@ is @11@ it is always
77 -- surrounded in parentheses, unless it is an atomic expression.
79 -- * If the constructor is defined using record syntax, then 'show'
80 -- will produce the record-syntax form, with the fields given in the
81 -- same order as the original declaration.
83 -- For example, given the declarations
86 -- > data Tree a = Leaf a | Tree a :^: Tree a
88 -- the derived instance of 'Show' is equivalent to
90 -- > instance (Show a) => Show (Tree a) where
92 -- > showsPrec d (Leaf m) = showParen (d > app_prec) $
93 -- > showString "Leaf " . showsPrec (app_prec+1) m
94 -- > where app_prec = 10
96 -- > showsPrec d (u :^: v) = showParen (d > up_prec) $
97 -- > showsPrec (up_prec+1) u .
98 -- > showString " :^: " .
99 -- > showsPrec (up_prec+1) v
100 -- > where up_prec = 5
102 -- Note that right-associativity of @:^:@ is ignored. For example,
104 -- * @'show' (Leaf 1 :^: Leaf 2 :^: Leaf 3)@ produces the string
105 -- @\"Leaf 1 :^: (Leaf 2 :^: Leaf 3)\"@.
108 -- | Convert a value to a readable 'String'.
110 -- 'showsPrec' should satisfy the law
112 -- > showsPrec d x r ++ s == showsPrec d x (r ++ s)
114 -- Derived instances of 'Text.Read.Read' and 'Show' satisfy the following:
116 -- * @(x,\"\")@ is an element of
117 -- @('Text.Read.readsPrec' d ('showsPrec' d x \"\"))@.
119 -- That is, 'Text.Read.readsPrec' parses the string produced by
120 -- 'showsPrec', and delivers the value that 'showsPrec' started with.
122 showsPrec :: Int -- ^ the operator precedence of the enclosing
123 -- context (a number from @0@ to @11@).
124 -- Function application has precedence @10@.
125 -> a -- ^ the value to be converted to a 'String'
128 -- | A specialised variant of 'showsPrec', using precedence context
129 -- zero, and returning an ordinary 'String'.
132 -- | The method 'showList' is provided to allow the programmer to
133 -- give a specialised way of showing lists of values.
134 -- For example, this is used by the predefined 'Show' instance of
135 -- the 'Char' type, where values of type 'String' should be shown
136 -- in double quotes, rather than between square brackets.
137 showList :: [a] -> ShowS
139 showsPrec _ x s = show x ++ s
141 showList ls s = showList__ shows ls s
143 showList__ :: (a -> ShowS) -> [a] -> ShowS
144 showList__ _ [] s = "[]" ++ s
145 showList__ showx (x:xs) s = '[' : showx x (showl xs)
148 showl (y:ys) = ',' : showx y (showl ys)
150 appPrec, appPrec1 :: Int
151 -- Use unboxed stuff because we don't have overloaded numerics yet
152 appPrec = I# 10# -- Precedence of application:
153 -- one more than the maximum operator precedence of 9
154 appPrec1 = I# 11# -- appPrec + 1
157 %*********************************************************
159 \subsection{Simple Instances}
161 %*********************************************************
165 instance Show () where
166 showsPrec _ () = showString "()"
168 instance Show a => Show [a] where
169 showsPrec _ = showList
171 instance Show Bool where
172 showsPrec _ True = showString "True"
173 showsPrec _ False = showString "False"
175 instance Show Ordering where
176 showsPrec _ LT = showString "LT"
177 showsPrec _ EQ = showString "EQ"
178 showsPrec _ GT = showString "GT"
180 instance Show Char where
181 showsPrec _ '\'' = showString "'\\''"
182 showsPrec _ c = showChar '\'' . showLitChar c . showChar '\''
184 showList cs = showChar '"' . showLitString cs . showChar '"'
186 instance Show Int where
187 showsPrec = showSignedInt
189 instance Show a => Show (Maybe a) where
190 showsPrec _p Nothing s = showString "Nothing" s
191 showsPrec p (Just x) s
192 = (showParen (p > appPrec) $
194 showsPrec appPrec1 x) s
198 %*********************************************************
200 \subsection{Show instances for the first few tuples
202 %*********************************************************
205 -- The explicit 's' parameters are important
206 -- Otherwise GHC thinks that "shows x" might take a lot of work to compute
207 -- and generates defns like
208 -- showsPrec _ (x,y) = let sx = shows x; sy = shows y in
209 -- \s -> showChar '(' (sx (showChar ',' (sy (showChar ')' s))))
211 instance (Show a, Show b) => Show (a,b) where
212 showsPrec _ (a,b) s = show_tuple [shows a, shows b] s
214 instance (Show a, Show b, Show c) => Show (a, b, c) where
215 showsPrec _ (a,b,c) s = show_tuple [shows a, shows b, shows c] s
217 instance (Show a, Show b, Show c, Show d) => Show (a, b, c, d) where
218 showsPrec _ (a,b,c,d) s = show_tuple [shows a, shows b, shows c, shows d] s
220 instance (Show a, Show b, Show c, Show d, Show e) => Show (a, b, c, d, e) where
221 showsPrec _ (a,b,c,d,e) s = show_tuple [shows a, shows b, shows c, shows d, shows e] s
223 instance (Show a, Show b, Show c, Show d, Show e, Show f) => Show (a,b,c,d,e,f) where
224 showsPrec _ (a,b,c,d,e,f) s = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f] s
226 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g)
227 => Show (a,b,c,d,e,f,g) where
228 showsPrec _ (a,b,c,d,e,f,g) s
229 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g] s
231 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h)
232 => Show (a,b,c,d,e,f,g,h) where
233 showsPrec _ (a,b,c,d,e,f,g,h) s
234 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h] s
236 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i)
237 => Show (a,b,c,d,e,f,g,h,i) where
238 showsPrec _ (a,b,c,d,e,f,g,h,i) s
239 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
242 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j)
243 => Show (a,b,c,d,e,f,g,h,i,j) where
244 showsPrec _ (a,b,c,d,e,f,g,h,i,j) s
245 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
248 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k)
249 => Show (a,b,c,d,e,f,g,h,i,j,k) where
250 showsPrec _ (a,b,c,d,e,f,g,h,i,j,k) s
251 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
252 shows i, shows j, shows k] s
254 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
256 => Show (a,b,c,d,e,f,g,h,i,j,k,l) where
257 showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l) s
258 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
259 shows i, shows j, shows k, shows l] s
261 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
263 => Show (a,b,c,d,e,f,g,h,i,j,k,l,m) where
264 showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l,m) s
265 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
266 shows i, shows j, shows k, shows l, shows m] s
268 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
269 Show l, Show m, Show n)
270 => Show (a,b,c,d,e,f,g,h,i,j,k,l,m,n) where
271 showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l,m,n) s
272 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
273 shows i, shows j, shows k, shows l, shows m, shows n] s
275 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
276 Show l, Show m, Show n, Show o)
277 => Show (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) where
278 showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) s
279 = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
280 shows i, shows j, shows k, shows l, shows m, shows n, shows o] s
282 show_tuple :: [ShowS] -> ShowS
283 show_tuple ss = showChar '('
284 . foldr1 (\s r -> s . showChar ',' . r) ss
289 %*********************************************************
291 \subsection{Support code for @Show@}
293 %*********************************************************
296 -- | equivalent to 'showsPrec' with a precedence of 0.
297 shows :: (Show a) => a -> ShowS
298 shows = showsPrec zeroInt
300 -- | utility function converting a 'Char' to a show function that
301 -- simply prepends the character unchanged.
302 showChar :: Char -> ShowS
305 -- | utility function converting a 'String' to a show function that
306 -- simply prepends the string unchanged.
307 showString :: String -> ShowS
310 -- | utility function that surrounds the inner show function with
311 -- parentheses when the 'Bool' parameter is 'True'.
312 showParen :: Bool -> ShowS -> ShowS
313 showParen b p = if b then showChar '(' . p . showChar ')' else p
316 showSpace = {-showChar ' '-} \ xs -> ' ' : xs
319 Code specific for characters
322 -- | Convert a character to a string using only printable characters,
323 -- using Haskell source-language escape conventions. For example:
325 -- > showLitChar '\n' s = "\\n" ++ s
327 showLitChar :: Char -> ShowS
328 showLitChar c s | c > '\DEL' = showChar '\\' (protectEsc isDec (shows (ord c)) s)
329 showLitChar '\DEL' s = showString "\\DEL" s
330 showLitChar '\\' s = showString "\\\\" s
331 showLitChar c s | c >= ' ' = showChar c s
332 showLitChar '\a' s = showString "\\a" s
333 showLitChar '\b' s = showString "\\b" s
334 showLitChar '\f' s = showString "\\f" s
335 showLitChar '\n' s = showString "\\n" s
336 showLitChar '\r' s = showString "\\r" s
337 showLitChar '\t' s = showString "\\t" s
338 showLitChar '\v' s = showString "\\v" s
339 showLitChar '\SO' s = protectEsc (== 'H') (showString "\\SO") s
340 showLitChar c s = showString ('\\' : asciiTab!!ord c) s
341 -- I've done manual eta-expansion here, becuase otherwise it's
342 -- impossible to stop (asciiTab!!ord) getting floated out as an MFE
344 showLitString :: String -> ShowS
345 -- | Same as 'showLitChar', but for strings
346 -- It converts the string to a string using Haskell escape conventions
347 -- for non-printable characters. Does not add double-quotes around the
348 -- whole thing; the caller should do that.
349 -- The main difference from showLitChar (apart from the fact that the
350 -- argument is a string not a list) is that we must escape double-quotes
351 showLitString [] s = s
352 showLitString ('"' : cs) s = showString "\\\"" (showLitString cs s)
353 showLitString (c : cs) s = showLitChar c (showLitString cs s)
354 -- Making 's' an explicit parameter makes it clear to GHC that
355 -- showLitString has arity 2, which avoids it allocating an extra lambda
356 -- The sticking point is the recursive call to (showLitString cs), which
357 -- it can't figure out would be ok with arity 2.
359 showMultiLineString :: String -> [String]
360 -- | Like 'showLitString' (expand escape characters using Haskell
361 -- escape conventions), but
362 -- * break the string into multiple lines
363 -- * wrap the entire thing in double quotes
364 -- Example: @breakMultiLineString "hello\ngoodbye\nblah"@
365 -- returns @["\"hello\\", "\\goodbye\\", "\\blah\"" ]@
366 -- where those "\\" are really just a single backslash
367 -- (but I'm writing them here as Haskell literals)
368 showMultiLineString str
371 go ch s = case break (== '\n') s of
372 (l, _:s'@(_:_)) -> (ch : showLitString l "\\") : go '\\' s'
373 (l, _) -> [ch : showLitString l "\""]
375 isDec :: Char -> Bool
376 isDec c = c >= '0' && c <= '9'
378 protectEsc :: (Char -> Bool) -> ShowS -> ShowS
379 protectEsc p f = f . cont
380 where cont s@(c:_) | p c = "\\&" ++ s
385 asciiTab = -- Using an array drags in the array module. listArray ('\NUL', ' ')
386 ["NUL", "SOH", "STX", "ETX", "EOT", "ENQ", "ACK", "BEL",
387 "BS", "HT", "LF", "VT", "FF", "CR", "SO", "SI",
388 "DLE", "DC1", "DC2", "DC3", "DC4", "NAK", "SYN", "ETB",
389 "CAN", "EM", "SUB", "ESC", "FS", "GS", "RS", "US",
393 Code specific for Ints.
396 -- | Convert an 'Int' in the range @0@..@15@ to the corresponding single
397 -- digit 'Char'. This function fails on other inputs, and generates
398 -- lower-case hexadecimal digits.
399 intToDigit :: Int -> Char
401 | i >=# 0# && i <=# 9# = unsafeChr (ord '0' `plusInt` I# i)
402 | i >=# 10# && i <=# 15# = unsafeChr (ord 'a' `minusInt` ten `plusInt` I# i)
403 | otherwise = error ("Char.intToDigit: not a digit " ++ show (I# i))
408 showSignedInt :: Int -> Int -> ShowS
409 showSignedInt (I# p) (I# n) r
410 | n <# 0# && p ># 6# = '(' : itos n (')' : r)
411 | otherwise = itos n r
413 itos :: Int# -> String -> String
416 let !(I# minInt#) = minInt in
418 -- negateInt# minInt overflows, so we can't do that:
419 then '-' : itos' (negateInt# (n# `quotInt#` 10#))
420 (itos' (negateInt# (n# `remInt#` 10#)) cs)
421 else '-' : itos' (negateInt# n#) cs
422 | otherwise = itos' n# cs
424 itos' :: Int# -> String -> String
426 | x# <# 10# = C# (chr# (ord# '0'# +# x#)) : cs'
427 | otherwise = case chr# (ord# '0'# +# (x# `remInt#` 10#)) of { c# ->
428 itos' (x# `quotInt#` 10#) (C# c# : cs') }