GHC/Show.lhs

   1 \begin{code}
   2 {-# OPTIONS_GHC -fno-implicit-prelude #-}
   3 -----------------------------------------------------------------------------
   4 -- |
   5 -- Module      :  GHC.Show
   6 -- Copyright   :  (c) The University of Glasgow, 1992-2002
   7 -- License     :  see libraries/base/LICENSE
   8 --
   9 -- Maintainer  :  cvs-ghc@haskell.org
  10 -- Stability   :  internal
  11 -- Portability :  non-portable (GHC Extensions)
  12 --
  13 -- The 'Show' class, and related operations.
  14 --
  15 -----------------------------------------------------------------------------
  16
  17 -- #hide
  18 module GHC.Show
  19         (
  20         Show(..), ShowS,
  21
  22         -- Instances for Show: (), [], Bool, Ordering, Int, Char
  23
  24         -- Show support code
  25         shows, showChar, showString, showParen, showList__, showSpace,
  26         showLitChar, protectEsc,
  27         intToDigit, showSignedInt,
  28         appPrec, appPrec1,
  29
  30         -- Character operations
  31         asciiTab,
  32   )
  33         where
  34
  35 import GHC.Base
  36 import Data.Maybe
  37 import Data.Either
  38 import GHC.List ( (!!), foldr1
  39 #ifdef USE_REPORT_PRELUDE
  40                 , concatMap
  41 #endif
  42                 )
  43 \end{code}
  44
  45
  46
  47 %*********************************************************
  48 %*                                                      *
  49 \subsection{The @Show@ class}
  50 %*                                                      *
  51 %*********************************************************
  52
  53 \begin{code}
  54 -- | The @shows@ functions return a function that prepends the
  55 -- output 'String' to an existing 'String'.  This allows constant-time
  56 -- concatenation of results using function composition.
  57 type ShowS = String -> String
  58
  59 -- | Conversion of values to readable 'String's.
  60 --
  61 -- Minimal complete definition: 'showsPrec' or 'show'.
  62 --
  63 -- Derived instances of 'Show' have the following properties, which
  64 -- are compatible with derived instances of 'Text.Read.Read':
  65 --
  66 -- * The result of 'show' is a syntactically correct Haskell
  67 --   expression containing only constants, given the fixity
  68 --   declarations in force at the point where the type is declared.
  69 --   It contains only the constructor names defined in the data type,
  70 --   parentheses, and spaces.  When labelled constructor fields are
  71 --   used, braces, commas, field names, and equal signs are also used.
  72 --
  73 -- * If the constructor is defined to be an infix operator, then
  74 --   'showsPrec' will produce infix applications of the constructor.
  75 --
  76 -- * the representation will be enclosed in parentheses if the
  77 --   precedence of the top-level constructor in @x@ is less than @d@
  78 --   (associativity is ignored).  Thus, if @d@ is @0@ then the result
  79 --   is never surrounded in parentheses; if @d@ is @11@ it is always
  80 --   surrounded in parentheses, unless it is an atomic expression.
  81 --
  82 -- * If the constructor is defined using record syntax, then 'show'
  83 --   will produce the record-syntax form, with the fields given in the
  84 --   same order as the original declaration.
  85 --
  86 -- For example, given the declarations
  87 --
  88 -- > infixr 5 :^:
  89 -- > data Tree a =  Leaf a  |  Tree a :^: Tree a
  90 --
  91 -- the derived instance of 'Show' is equivalent to
  92 --
  93 -- > instance (Show a) => Show (Tree a) where
  94 -- >
  95 -- >        showsPrec d (Leaf m) = showParen (d > app_prec) $
  96 -- >             showString "Leaf " . showsPrec (app_prec+1) m
  97 -- >          where app_prec = 10
  98 -- >
  99 -- >        showsPrec d (u :^: v) = showParen (d > up_prec) $
 100 -- >             showsPrec (up_prec+1) u .
 101 -- >             showString " :^: "      .
 102 -- >             showsPrec (up_prec+1) v
 103 -- >          where up_prec = 5
 104 --
 105 -- Note that right-associativity of @:^:@ is ignored.  For example,
 106 --
 107 -- * @'show' (Leaf 1 :^: Leaf 2 :^: Leaf 3)@ produces the string
 108 --   @\"Leaf 1 :^: (Leaf 2 :^: Leaf 3)\"@.
 109
 110 class  Show a  where
 111     -- | Convert a value to a readable 'String'.
 112     --
 113     -- 'showsPrec' should satisfy the law
 114     --
 115     -- > showsPrec d x r ++ s  ==  showsPrec d x (r ++ s)
 116     --
 117     -- Derived instances of 'Text.Read.Read' and 'Show' satisfy the following:
 118     --
 119     -- * @(x,\"\")@ is an element of
 120     --   @('Text.Read.readsPrec' d ('showsPrec' d x \"\"))@.
 121     --
 122     -- That is, 'Text.Read.readsPrec' parses the string produced by
 123     -- 'showsPrec', and delivers the value that 'showsPrec' started with.
 124
 125     showsPrec :: Int    -- ^ the operator precedence of the enclosing
 126                         -- context (a number from @0@ to @11@).
 127                         -- Function application has precedence @10@.
 128               -> a      -- ^ the value to be converted to a 'String'
 129               -> ShowS
 130
 131     -- | A specialised variant of 'showsPrec', using precedence context
 132     -- zero, and returning an ordinary 'String'.
 133     show      :: a   -> String
 134
 135     -- | The method 'showList' is provided to allow the programmer to
 136     -- give a specialised way of showing lists of values.
 137     -- For example, this is used by the predefined 'Show' instance of
 138     -- the 'Char' type, where values of type 'String' should be shown
 139     -- in double quotes, rather than between square brackets.
 140     showList  :: [a] -> ShowS
 141
 142     showsPrec _ x s = show x ++ s
 143     show x          = shows x ""
 144     showList ls   s = showList__ shows ls s
 145
 146 showList__ :: (a -> ShowS) ->  [a] -> ShowS
 147 showList__ _     []     s = "[]" ++ s
 148 showList__ showx (x:xs) s = '[' : showx x (showl xs)
 149   where
 150     showl []     = ']' : s
 151     showl (y:ys) = ',' : showx y (showl ys)
 152
 153 appPrec, appPrec1 :: Int
 154         -- Use unboxed stuff because we don't have overloaded numerics yet
 155 appPrec = I# 10#        -- Precedence of application:
 156                         --   one more than the maximum operator precedence of 9
 157 appPrec1 = I# 11#       -- appPrec + 1
 158 \end{code}
 159
 160 %*********************************************************
 161 %*                                                      *
 162 \subsection{Simple Instances}
 163 %*                                                      *
 164 %*********************************************************
 165
 166 \begin{code}
 167
 168 instance  Show ()  where
 169     showsPrec _ () = showString "()"
 170
 171 instance Show a => Show [a]  where
 172     showsPrec _         = showList
 173
 174 instance Show Bool where
 175   showsPrec _ True  = showString "True"
 176   showsPrec _ False = showString "False"
 177
 178 instance Show Ordering where
 179   showsPrec _ LT = showString "LT"
 180   showsPrec _ EQ = showString "EQ"
 181   showsPrec _ GT = showString "GT"
 182
 183 instance  Show Char  where
 184     showsPrec _ '\'' = showString "'\\''"
 185     showsPrec _ c    = showChar '\'' . showLitChar c . showChar '\''
 186
 187     showList cs = showChar '"' . showl cs
 188                  where showl ""       s = showChar '"' s
 189                        showl ('"':xs) s = showString "\\\"" (showl xs s)
 190                        showl (x:xs)   s = showLitChar x (showl xs s)
 191                 -- Making 's' an explicit parameter makes it clear to GHC
 192                 -- that showl has arity 2, which avoids it allocating an extra lambda
 193                 -- The sticking point is the recursive call to (showl xs), which
 194                 -- it can't figure out would be ok with arity 2.
 195
 196 instance Show Int where
 197     showsPrec = showSignedInt
 198
 199 instance Show a => Show (Maybe a) where
 200     showsPrec _p Nothing s = showString "Nothing" s
 201     showsPrec p (Just x) s
 202                           = (showParen (p > appPrec) $
 203                              showString "Just " .
 204                              showsPrec appPrec1 x) s
 205
 206 instance (Show a, Show b) => Show (Either a b) where
 207     showsPrec p e s =
 208        (showParen (p > appPrec) $
 209         case e of
 210          Left  a -> showString "Left "  . showsPrec appPrec1 a
 211          Right b -> showString "Right " . showsPrec appPrec1 b)
 212        s
 213 \end{code}
 214
 215
 216 %*********************************************************
 217 %*                                                      *
 218 \subsection{Show instances for the first few tuples
 219 %*                                                      *
 220 %*********************************************************
 221
 222 \begin{code}
 223 -- The explicit 's' parameters are important
 224 -- Otherwise GHC thinks that "shows x" might take a lot of work to compute
 225 -- and generates defns like
 226 --      showsPrec _ (x,y) = let sx = shows x; sy = shows y in
 227 --                          \s -> showChar '(' (sx (showChar ',' (sy (showChar ')' s))))
 228
 229 instance  (Show a, Show b) => Show (a,b)  where
 230   showsPrec _ (a,b) s = show_tuple [shows a, shows b] s
 231
 232 instance (Show a, Show b, Show c) => Show (a, b, c) where
 233   showsPrec _ (a,b,c) s = show_tuple [shows a, shows b, shows c] s
 234
 235 instance (Show a, Show b, Show c, Show d) => Show (a, b, c, d) where
 236   showsPrec _ (a,b,c,d) s = show_tuple [shows a, shows b, shows c, shows d] s
 237
 238 instance (Show a, Show b, Show c, Show d, Show e) => Show (a, b, c, d, e) where
 239   showsPrec _ (a,b,c,d,e) s = show_tuple [shows a, shows b, shows c, shows d, shows e] s
 240
 241 instance (Show a, Show b, Show c, Show d, Show e, Show f) => Show (a,b,c,d,e,f) where
 242   showsPrec _ (a,b,c,d,e,f) s = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f] s
 243
 244 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g)
 245         => Show (a,b,c,d,e,f,g) where
 246   showsPrec _ (a,b,c,d,e,f,g) s
 247         = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g] s
 248
 249 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h)
 250          => Show (a,b,c,d,e,f,g,h) where
 251   showsPrec _ (a,b,c,d,e,f,g,h) s
 252         = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h] s
 253
 254 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i)
 255          => Show (a,b,c,d,e,f,g,h,i) where
 256   showsPrec _ (a,b,c,d,e,f,g,h,i) s
 257         = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
 258                       shows i] s
 259
 260 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j)
 261          => Show (a,b,c,d,e,f,g,h,i,j) where
 262   showsPrec _ (a,b,c,d,e,f,g,h,i,j) s
 263         = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
 264                       shows i, shows j] s
 265
 266 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k)
 267          => Show (a,b,c,d,e,f,g,h,i,j,k) where
 268   showsPrec _ (a,b,c,d,e,f,g,h,i,j,k) s
 269         = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
 270                       shows i, shows j, shows k] s
 271
 272 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
 273           Show l)
 274          => Show (a,b,c,d,e,f,g,h,i,j,k,l) where
 275   showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l) s
 276         = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
 277                       shows i, shows j, shows k, shows l] s
 278
 279 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
 280           Show l, Show m)
 281          => Show (a,b,c,d,e,f,g,h,i,j,k,l,m) where
 282   showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l,m) s
 283         = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
 284                       shows i, shows j, shows k, shows l, shows m] s
 285
 286 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
 287           Show l, Show m, Show n)
 288          => Show (a,b,c,d,e,f,g,h,i,j,k,l,m,n) where
 289   showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l,m,n) s
 290         = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
 291                       shows i, shows j, shows k, shows l, shows m, shows n] s
 292
 293 instance (Show a, Show b, Show c, Show d, Show e, Show f, Show g, Show h, Show i, Show j, Show k,
 294           Show l, Show m, Show n, Show o)
 295          => Show (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) where
 296   showsPrec _ (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) s
 297         = show_tuple [shows a, shows b, shows c, shows d, shows e, shows f, shows g, shows h,
 298                       shows i, shows j, shows k, shows l, shows m, shows n, shows o] s
 299
 300 show_tuple :: [ShowS] -> ShowS
 301 show_tuple ss = showChar '('
 302               . foldr1 (\s r -> s . showChar ',' . r) ss
 303               . showChar ')'
 304 \end{code}
 305
 306
 307 %*********************************************************
 308 %*                                                      *
 309 \subsection{Support code for @Show@}
 310 %*                                                      *
 311 %*********************************************************
 312
 313 \begin{code}
 314 -- | equivalent to 'showsPrec' with a precedence of 0.
 315 shows           :: (Show a) => a -> ShowS
 316 shows           =  showsPrec zeroInt
 317
 318 -- | utility function converting a 'Char' to a show function that
 319 -- simply prepends the character unchanged.
 320 showChar        :: Char -> ShowS
 321 showChar        =  (:)
 322
 323 -- | utility function converting a 'String' to a show function that
 324 -- simply prepends the string unchanged.
 325 showString      :: String -> ShowS
 326 showString      =  (++)
 327
 328 -- | utility function that surrounds the inner show function with
 329 -- parentheses when the 'Bool' parameter is 'True'.
 330 showParen       :: Bool -> ShowS -> ShowS
 331 showParen b p   =  if b then showChar '(' . p . showChar ')' else p
 332
 333 showSpace :: ShowS
 334 showSpace = {-showChar ' '-} \ xs -> ' ' : xs
 335 \end{code}
 336
 337 Code specific for characters
 338
 339 \begin{code}
 340 -- | Convert a character to a string using only printable characters,
 341 -- using Haskell source-language escape conventions.  For example:
 342 --
 343 -- > showLitChar '\n' s  =  "\\n" ++ s
 344 --
 345 showLitChar                :: Char -> ShowS
 346 showLitChar c s | c > '\DEL' =  showChar '\\' (protectEsc isDec (shows (ord c)) s)
 347 showLitChar '\DEL'         s =  showString "\\DEL" s
 348 showLitChar '\\'           s =  showString "\\\\" s
 349 showLitChar c s | c >= ' '   =  showChar c s
 350 showLitChar '\a'           s =  showString "\\a" s
 351 showLitChar '\b'           s =  showString "\\b" s
 352 showLitChar '\f'           s =  showString "\\f" s
 353 showLitChar '\n'           s =  showString "\\n" s
 354 showLitChar '\r'           s =  showString "\\r" s
 355 showLitChar '\t'           s =  showString "\\t" s
 356 showLitChar '\v'           s =  showString "\\v" s
 357 showLitChar '\SO'          s =  protectEsc (== 'H') (showString "\\SO") s
 358 showLitChar c              s =  showString ('\\' : asciiTab!!ord c) s
 359         -- I've done manual eta-expansion here, becuase otherwise it's
 360         -- impossible to stop (asciiTab!!ord) getting floated out as an MFE
 361
 362 isDec c = c >= '0' && c <= '9'
 363
 364 protectEsc :: (Char -> Bool) -> ShowS -> ShowS
 365 protectEsc p f             = f . cont
 366                              where cont s@(c:_) | p c = "\\&" ++ s
 367                                    cont s             = s
 368
 369
 370 asciiTab :: [String]
 371 asciiTab = -- Using an array drags in the array module.  listArray ('\NUL', ' ')
 372            ["NUL", "SOH", "STX", "ETX", "EOT", "ENQ", "ACK", "BEL",
 373             "BS",  "HT",  "LF",  "VT",  "FF",  "CR",  "SO",  "SI",
 374             "DLE", "DC1", "DC2", "DC3", "DC4", "NAK", "SYN", "ETB",
 375             "CAN", "EM",  "SUB", "ESC", "FS",  "GS",  "RS",  "US",
 376             "SP"]
 377 \end{code}
 378
 379 Code specific for Ints.
 380
 381 \begin{code}
 382 -- | Convert an 'Int' in the range @0@..@15@ to the corresponding single
 383 -- digit 'Char'.  This function fails on other inputs, and generates
 384 -- lower-case hexadecimal digits.
 385 intToDigit :: Int -> Char
 386 intToDigit (I# i)
 387     | i >=# 0#  && i <=#  9# =  unsafeChr (ord '0' `plusInt` I# i)
 388     | i >=# 10# && i <=# 15# =  unsafeChr (ord 'a' `minusInt` ten `plusInt` I# i)
 389     | otherwise           =  error ("Char.intToDigit: not a digit " ++ show (I# i))
 390
 391 ten = I# 10#
 392
 393 showSignedInt :: Int -> Int -> ShowS
 394 showSignedInt (I# p) (I# n) r
 395     | n <# 0# && p ># 6# = '(' : itos n (')' : r)
 396     | otherwise          = itos n r
 397
 398 itos :: Int# -> String -> String
 399 itos n# cs
 400     | n# <# 0# =
 401         let I# minInt# = minInt in
 402         if n# ==# minInt#
 403                 -- negateInt# minInt overflows, so we can't do that:
 404            then '-' : itos' (negateInt# (n# `quotInt#` 10#))
 405                              (itos' (negateInt# (n# `remInt#` 10#)) cs)
 406            else '-' : itos' (negateInt# n#) cs
 407     | otherwise = itos' n# cs
 408     where
 409     itos' :: Int# -> String -> String
 410     itos' n# cs
 411         | n# <# 10#  = C# (chr# (ord# '0'# +# n#)) : cs
 412         | otherwise = case chr# (ord# '0'# +# (n# `remInt#` 10#)) of { c# ->
 413                       itos' (n# `quotInt#` 10#) (C# c# : cs) }
 414 \end{code}