GHC/Read.lhs

   1 \begin{code}
   2 {-# OPTIONS_GHC -fno-implicit-prelude #-}
   3 -----------------------------------------------------------------------------
   4 -- |
   5 -- Module      :  GHC.Read
   6 -- Copyright   :  (c) The University of Glasgow, 1994-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 'Read' class and instances for basic data types.
  14 --
  15 -----------------------------------------------------------------------------
  16
  17 -- #hide
  18 module GHC.Read
  19   ( Read(..)   -- class
  20
  21   -- ReadS type
  22   , ReadS      -- :: *; = String -> [(a,String)]
  23
  24   -- utility functions
  25   , reads      -- :: Read a => ReadS a
  26   , readp      -- :: Read a => ReadP a
  27   , readEither -- :: Read a => String -> Either String a
  28   , read       -- :: Read a => String -> a
  29
  30   -- H98 compatibility
  31   , lex         -- :: ReadS String
  32   , lexLitChar  -- :: ReadS String
  33   , readLitChar -- :: ReadS Char
  34   , lexDigits   -- :: ReadS String
  35
  36   -- defining readers
  37   , lexP       -- :: ReadPrec Lexeme
  38   , paren      -- :: ReadPrec a -> ReadPrec a
  39   , parens     -- :: ReadPrec a -> ReadPrec a
  40   , list       -- :: ReadPrec a -> ReadPrec [a]
  41   , choose     -- :: [(String, ReadPrec a)] -> ReadPrec a
  42   , readListDefault, readListPrecDefault
  43
  44   -- Temporary
  45   , readParen
  46   )
  47  where
  48
  49 import qualified Text.ParserCombinators.ReadP as P
  50
  51 import Text.ParserCombinators.ReadP
  52   ( ReadP
  53   , ReadS
  54   , readP_to_S
  55   )
  56
  57 import qualified Text.Read.Lex as L
  58 -- Lex exports 'lex', which is also defined here,
  59 -- hence the qualified import.
  60 -- We can't import *anything* unqualified, because that
  61 -- confuses Haddock.
  62
  63 import Text.ParserCombinators.ReadPrec
  64
  65 import Data.Maybe
  66 import Data.Either
  67
  68 import {-# SOURCE #-} GHC.Err           ( error )
  69 #ifndef __HADDOCK__
  70 import {-# SOURCE #-} GHC.Unicode       ( isDigit )
  71 #endif
  72 import GHC.Num
  73 import GHC.Real
  74 import GHC.Float
  75 import GHC.List
  76 import GHC.Show
  77 import GHC.Base
  78 import GHC.Arr
  79 \end{code}
  80
  81
  82 \begin{code}
  83 -- | @'readParen' 'True' p@ parses what @p@ parses, but surrounded with
  84 -- parentheses.
  85 --
  86 -- @'readParen' 'False' p@ parses what @p@ parses, but optionally
  87 -- surrounded with parentheses.
  88 readParen       :: Bool -> ReadS a -> ReadS a
  89 -- A Haskell 98 function
  90 readParen b g   =  if b then mandatory else optional
  91                    where optional r  = g r ++ mandatory r
  92                          mandatory r = do
  93                                 ("(",s) <- lex r
  94                                 (x,t)   <- optional s
  95                                 (")",u) <- lex t
  96                                 return (x,u)
  97 \end{code}
  98
  99
 100 %*********************************************************
 101 %*                                                      *
 102 \subsection{The @Read@ class}
 103 %*                                                      *
 104 %*********************************************************
 105
 106 \begin{code}
 107 ------------------------------------------------------------------------
 108 -- class Read
 109
 110 -- | Parsing of 'String's, producing values.
 111 --
 112 -- Minimal complete definition: 'readsPrec' (or, for GHC only, 'readPrec')
 113 --
 114 -- Derived instances of 'Read' make the following assumptions, which
 115 -- derived instances of 'Text.Show.Show' obey:
 116 --
 117 -- * If the constructor is defined to be an infix operator, then the
 118 --   derived 'Read' instance will parse only infix applications of
 119 --   the constructor (not the prefix form).
 120 --
 121 -- * Associativity is not used to reduce the occurrence of parentheses,
 122 --   although precedence may be.
 123 --
 124 -- * If the constructor is defined using record syntax, the derived 'Read'
 125 --   will parse only the record-syntax form, and furthermore, the fields
 126 --   must be given in the same order as the original declaration.
 127 --
 128 -- * The derived 'Read' instance allows arbitrary Haskell whitespace
 129 --   between tokens of the input string.  Extra parentheses are also
 130 --   allowed.
 131 --
 132 -- For example, given the declarations
 133 --
 134 -- > infixr 5 :^:
 135 -- > data Tree a =  Leaf a  |  Tree a :^: Tree a
 136 --
 137 -- the derived instance of 'Read' is equivalent to
 138 --
 139 -- > instance (Read a) => Read (Tree a) where
 140 -- >
 141 -- >         readsPrec d r =  readParen (d > up_prec)
 142 -- >                          (\r -> [(u:^:v,w) |
 143 -- >                                  (u,s) <- readsPrec (up_prec+1) r,
 144 -- >                                  (":^:",t) <- lex s,
 145 -- >                                  (v,w) <- readsPrec (up_prec+1) t]) r
 146 -- >
 147 -- >                       ++ readParen (d > app_prec)
 148 -- >                          (\r -> [(Leaf m,t) |
 149 -- >                                  ("Leaf",s) <- lex r,
 150 -- >                                  (m,t) <- readsPrec (app_prec+1) s]) r
 151 -- >
 152 -- >           where up_prec = 5
 153 -- >                 app_prec = 10
 154 --
 155 -- Note that right-associativity of @:^:@ is unused.
 156
 157 class Read a where
 158   -- | attempts to parse a value from the front of the string, returning
 159   -- a list of (parsed value, remaining string) pairs.  If there is no
 160   -- successful parse, the returned list is empty.
 161   --
 162   -- Derived instances of 'Read' and 'Text.Show.Show' satisfy the following:
 163   --
 164   -- * @(x,\"\")@ is an element of
 165   --   @('readsPrec' d ('Text.Show.showsPrec' d x \"\"))@.
 166   --
 167   -- That is, 'readsPrec' parses the string produced by
 168   -- 'Text.Show.showsPrec', and delivers the value that
 169   -- 'Text.Show.showsPrec' started with.
 170
 171   readsPrec    :: Int   -- ^ the operator precedence of the enclosing
 172                         -- context (a number from @0@ to @11@).
 173                         -- Function application has precedence @10@.
 174                 -> ReadS a
 175
 176   -- | The method 'readList' is provided to allow the programmer to
 177   -- give a specialised way of parsing lists of values.
 178   -- For example, this is used by the predefined 'Read' instance of
 179   -- the 'Char' type, where values of type 'String' should be are
 180   -- expected to use double quotes, rather than square brackets.
 181   readList     :: ReadS [a]
 182
 183   -- | Proposed replacement for 'readsPrec' using new-style parsers (GHC only).
 184   readPrec     :: ReadPrec a
 185
 186   -- | Proposed replacement for 'readList' using new-style parsers (GHC only).
 187   readListPrec :: ReadPrec [a]
 188
 189   -- default definitions
 190   readsPrec    = readPrec_to_S readPrec
 191   readList     = readPrec_to_S (list readPrec) 0
 192   readPrec     = readS_to_Prec readsPrec
 193   readListPrec = readS_to_Prec (\_ -> readList)
 194
 195 readListDefault :: Read a => ReadS [a]
 196 -- ^ Use this to define the 'readList' method, if you don't want a special
 197 --   case (GHC only; for other systems the default suffices).
 198 readListDefault = readPrec_to_S readListPrec 0
 199
 200 readListPrecDefault :: Read a => ReadPrec [a]
 201 -- ^ Use this to define the 'readListPrec' method, if you
 202 --   don't want a special case (GHC only).
 203 readListPrecDefault = list readPrec
 204
 205 ------------------------------------------------------------------------
 206 -- utility functions
 207
 208 -- | equivalent to 'readsPrec' with a precedence of 0.
 209 reads :: Read a => ReadS a
 210 reads = readsPrec minPrec
 211
 212 readp :: Read a => ReadP a
 213 readp = readPrec_to_P readPrec minPrec
 214
 215 readEither :: Read a => String -> Either String a
 216 readEither s =
 217   case [ x | (x,"") <- readPrec_to_S read' minPrec s ] of
 218     [x] -> Right x
 219     []  -> Left "Prelude.read: no parse"
 220     _   -> Left "Prelude.read: ambiguous parse"
 221  where
 222   read' =
 223     do x <- readPrec
 224        lift P.skipSpaces
 225        return x
 226
 227 -- | The 'read' function reads input from a string, which must be
 228 -- completely consumed by the input process.
 229 read :: Read a => String -> a
 230 read s = either error id (readEither s)
 231
 232 ------------------------------------------------------------------------
 233 -- H98 compatibility
 234
 235 -- | The 'lex' function reads a single lexeme from the input, discarding
 236 -- initial white space, and returning the characters that constitute the
 237 -- lexeme.  If the input string contains only white space, 'lex' returns a
 238 -- single successful \`lexeme\' consisting of the empty string.  (Thus
 239 -- @'lex' \"\" = [(\"\",\"\")]@.)  If there is no legal lexeme at the
 240 -- beginning of the input string, 'lex' fails (i.e. returns @[]@).
 241 --
 242 -- This lexer is not completely faithful to the Haskell lexical syntax
 243 -- in the following respects:
 244 --
 245 -- * Qualified names are not handled properly
 246 --
 247 -- * Octal and hexadecimal numerics are not recognized as a single token
 248 --
 249 -- * Comments are not treated properly
 250 lex :: ReadS String             -- As defined by H98
 251 lex s  = readP_to_S L.hsLex s
 252
 253 -- | Read a string representation of a character, using Haskell
 254 -- source-language escape conventions.  For example:
 255 --
 256 -- > lexLitChar  "\\nHello"  =  [("\\n", "Hello")]
 257 --
 258 lexLitChar :: ReadS String      -- As defined by H98
 259 lexLitChar = readP_to_S (do { (s, _) <- P.gather L.lexChar ;
 260                               return s })
 261         -- There was a skipSpaces before the P.gather L.lexChar,
 262         -- but that seems inconsistent with readLitChar
 263
 264 -- | Read a string representation of a character, using Haskell
 265 -- source-language escape conventions, and convert it to the character
 266 -- that it encodes.  For example:
 267 --
 268 -- > readLitChar "\\nHello"  =  [('\n', "Hello")]
 269 --
 270 readLitChar :: ReadS Char       -- As defined by H98
 271 readLitChar = readP_to_S L.lexChar
 272
 273 -- | Reads a non-empty string of decimal digits.
 274 lexDigits :: ReadS String
 275 lexDigits = readP_to_S (P.munch1 isDigit)
 276
 277 ------------------------------------------------------------------------
 278 -- utility parsers
 279
 280 lexP :: ReadPrec L.Lexeme
 281 -- ^ Parse a single lexeme
 282 lexP = lift L.lex
 283
 284 paren :: ReadPrec a -> ReadPrec a
 285 -- ^ @(paren p)@ parses \"(P0)\"
 286 --      where @p@ parses \"P0\" in precedence context zero
 287 paren p = do L.Punc "(" <- lexP
 288              x          <- reset p
 289              L.Punc ")" <- lexP
 290              return x
 291
 292 parens :: ReadPrec a -> ReadPrec a
 293 -- ^ @(parens p)@ parses \"P\", \"(P0)\", \"((P0))\", etc,
 294 --      where @p@ parses \"P\"  in the current precedence context
 295 --              parses \"P0\" in precedence context zero
 296 parens p = optional
 297  where
 298   optional  = p +++ mandatory
 299   mandatory = paren optional
 300
 301 list :: ReadPrec a -> ReadPrec [a]
 302 -- ^ @(list p)@ parses a list of things parsed by @p@,
 303 -- using the usual square-bracket syntax.
 304 list readx =
 305   parens
 306   ( do L.Punc "[" <- lexP
 307        (listRest False +++ listNext)
 308   )
 309  where
 310   listRest started =
 311     do L.Punc c <- lexP
 312        case c of
 313          "]"           -> return []
 314          "," | started -> listNext
 315          _             -> pfail
 316
 317   listNext =
 318     do x  <- reset readx
 319        xs <- listRest True
 320        return (x:xs)
 321
 322 choose :: [(String, ReadPrec a)] -> ReadPrec a
 323 -- ^ Parse the specified lexeme and continue as specified.
 324 -- Esp useful for nullary constructors; e.g.
 325 --    @choose [(\"A\", return A), (\"B\", return B)]@
 326 choose sps = foldr ((+++) . try_one) pfail sps
 327            where
 328              try_one (s,p) = do { L.Ident s' <- lexP ;
 329                                   if s == s' then p else pfail }
 330 \end{code}
 331
 332
 333 %*********************************************************
 334 %*                                                      *
 335 \subsection{Simple instances of Read}
 336 %*                                                      *
 337 %*********************************************************
 338
 339 \begin{code}
 340 instance Read Char where
 341   readPrec =
 342     parens
 343     ( do L.Char c <- lexP
 344          return c
 345     )
 346
 347   readListPrec =
 348     parens
 349     ( do L.String s <- lexP     -- Looks for "foo"
 350          return s
 351      +++
 352       readListPrecDefault       -- Looks for ['f','o','o']
 353     )                           -- (more generous than H98 spec)
 354
 355   readList = readListDefault
 356
 357 instance Read Bool where
 358   readPrec =
 359     parens
 360     ( do L.Ident s <- lexP
 361          case s of
 362            "True"  -> return True
 363            "False" -> return False
 364            _       -> pfail
 365     )
 366
 367   readListPrec = readListPrecDefault
 368   readList     = readListDefault
 369
 370 instance Read Ordering where
 371   readPrec =
 372     parens
 373     ( do L.Ident s <- lexP
 374          case s of
 375            "LT" -> return LT
 376            "EQ" -> return EQ
 377            "GT" -> return GT
 378            _    -> pfail
 379     )
 380
 381   readListPrec = readListPrecDefault
 382   readList     = readListDefault
 383 \end{code}
 384
 385
 386 %*********************************************************
 387 %*                                                      *
 388 \subsection{Structure instances of Read: Maybe, List etc}
 389 %*                                                      *
 390 %*********************************************************
 391
 392 For structured instances of Read we start using the precedences.  The
 393 idea is then that 'parens (prec k p)' will fail immediately when trying
 394 to parse it in a context with a higher precedence level than k. But if
 395 there is one parenthesis parsed, then the required precedence level
 396 drops to 0 again, and parsing inside p may succeed.
 397
 398 'appPrec' is just the precedence level of function application.  So,
 399 if we are parsing function application, we'd better require the
 400 precedence level to be at least 'appPrec'. Otherwise, we have to put
 401 parentheses around it.
 402
 403 'step' is used to increase the precedence levels inside a
 404 parser, and can be used to express left- or right- associativity. For
 405 example, % is defined to be left associative, so we only increase
 406 precedence on the right hand side.
 407
 408 Note how step is used in for example the Maybe parser to increase the
 409 precedence beyond appPrec, so that basically only literals and
 410 parenthesis-like objects such as (...) and [...] can be an argument to
 411 'Just'.
 412
 413 \begin{code}
 414 instance Read a => Read (Maybe a) where
 415   readPrec =
 416     parens
 417     (do L.Ident "Nothing" <- lexP
 418         return Nothing
 419      +++
 420      prec appPrec (
 421         do L.Ident "Just" <- lexP
 422            x              <- step readPrec
 423            return (Just x))
 424     )
 425
 426   readListPrec = readListPrecDefault
 427   readList     = readListDefault
 428
 429 instance (Read a, Read b) => Read (Either a b) where
 430   readPrec =
 431     parens
 432     ( prec appPrec
 433       ( do L.Ident "Left" <- lexP
 434            x            <- step readPrec
 435            return (Left x)
 436        +++
 437         do L.Ident "Right" <- lexP
 438            y             <- step readPrec
 439            return (Right y)
 440       )
 441     )
 442
 443   readListPrec = readListPrecDefault
 444   readList     = readListDefault
 445
 446 instance Read a => Read [a] where
 447   readPrec     = readListPrec
 448   readListPrec = readListPrecDefault
 449   readList     = readListDefault
 450
 451 instance  (Ix a, Read a, Read b) => Read (Array a b)  where
 452     readPrec = parens $ prec appPrec $
 453                do L.Ident "array" <- lexP
 454                   bounds <- step readPrec
 455                   vals   <- step readPrec
 456                   return (array bounds vals)
 457
 458     readListPrec = readListPrecDefault
 459     readList     = readListDefault
 460
 461 instance Read L.Lexeme where
 462   readPrec     = lexP
 463   readListPrec = readListPrecDefault
 464   readList     = readListDefault
 465 \end{code}
 466
 467
 468 %*********************************************************
 469 %*                                                      *
 470 \subsection{Numeric instances of Read}
 471 %*                                                      *
 472 %*********************************************************
 473
 474 \begin{code}
 475 readNumber :: Num a => (L.Lexeme -> Maybe a) -> ReadPrec a
 476 -- Read a signed number
 477 readNumber convert =
 478   parens
 479   ( do x <- lexP
 480        case x of
 481          L.Symbol "-" -> do n <- readNumber convert
 482                             return (negate n)
 483
 484          _   -> case convert x of
 485                    Just n  -> return n
 486                    Nothing -> pfail
 487   )
 488
 489 convertInt :: Num a => L.Lexeme -> Maybe a
 490 convertInt (L.Int i) = Just (fromInteger i)
 491 convertInt _         = Nothing
 492
 493 convertFrac :: Fractional a => L.Lexeme -> Maybe a
 494 convertFrac (L.Int i) = Just (fromInteger i)
 495 convertFrac (L.Rat r) = Just (fromRational r)
 496 convertFrac _         = Nothing
 497
 498 instance Read Int where
 499   readPrec     = readNumber convertInt
 500   readListPrec = readListPrecDefault
 501   readList     = readListDefault
 502
 503 instance Read Integer where
 504   readPrec     = readNumber convertInt
 505   readListPrec = readListPrecDefault
 506   readList     = readListDefault
 507
 508 instance Read Float where
 509   readPrec     = readNumber convertFrac
 510   readListPrec = readListPrecDefault
 511   readList     = readListDefault
 512
 513 instance Read Double where
 514   readPrec     = readNumber convertFrac
 515   readListPrec = readListPrecDefault
 516   readList     = readListDefault
 517
 518 instance (Integral a, Read a) => Read (Ratio a) where
 519   readPrec =
 520     parens
 521     ( prec ratioPrec
 522       ( do x            <- step readPrec
 523            L.Symbol "%" <- lexP
 524            y            <- step readPrec
 525            return (x % y)
 526       )
 527     )
 528
 529   readListPrec = readListPrecDefault
 530   readList     = readListDefault
 531 \end{code}
 532
 533
 534 %*********************************************************
 535 %*                                                      *
 536 \subsection{Tuple instances of Read}
 537 %*                                                      *
 538 %*********************************************************
 539
 540 \begin{code}
 541 instance Read () where
 542   readPrec =
 543     parens
 544     ( paren
 545       ( return ()
 546       )
 547     )
 548
 549   readListPrec = readListPrecDefault
 550   readList     = readListDefault
 551
 552 instance (Read a, Read b) => Read (a,b) where
 553   readPrec =
 554     parens
 555     ( paren
 556       ( do x <- readPrec
 557            L.Punc "," <- lexP
 558            y <- readPrec
 559            return (x,y)
 560       )
 561     )
 562
 563   readListPrec = readListPrecDefault
 564   readList     = readListDefault
 565
 566
 567 instance (Read a, Read b, Read c) => Read (a, b, c) where
 568   readPrec =
 569     parens
 570     ( paren
 571       ( do x <- readPrec
 572            L.Punc "," <- lexP
 573            y <- readPrec
 574            L.Punc "," <- lexP
 575            z <- readPrec
 576            return (x,y,z)
 577       )
 578     )
 579
 580   readListPrec = readListPrecDefault
 581   readList     = readListDefault
 582
 583 instance (Read a, Read b, Read c, Read d) => Read (a, b, c, d) where
 584   readPrec =
 585     parens
 586     ( paren
 587       ( do w <- readPrec
 588            L.Punc "," <- lexP
 589            x <- readPrec
 590            L.Punc "," <- lexP
 591            y <- readPrec
 592            L.Punc "," <- lexP
 593            z <- readPrec
 594            return (w,x,y,z)
 595       )
 596     )
 597
 598   readListPrec = readListPrecDefault
 599   readList     = readListDefault
 600
 601 instance (Read a, Read b, Read c, Read d, Read e) => Read (a, b, c, d, e) where
 602   readPrec =
 603     parens
 604     ( paren
 605       ( do v <- readPrec
 606            L.Punc "," <- lexP
 607            w <- readPrec
 608            L.Punc "," <- lexP
 609            x <- readPrec
 610            L.Punc "," <- lexP
 611            y <- readPrec
 612            L.Punc "," <- lexP
 613            z <- readPrec
 614            return (v,w,x,y,z)
 615       )
 616     )
 617
 618   readListPrec = readListPrecDefault
 619   readList     = readListDefault
 620 \end{code}