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