Move GeneralCategory et al to GHC.Unicode
[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
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 deriving instance Read GeneralCategory
316
317 instance Read Char where
318 readPrec =
319 parens
320 ( do L.Char c <- lexP
321 return c
322 )
323
324 readListPrec =
325 parens
326 ( do L.String s <- lexP -- Looks for "foo"
327 return s
328 +++
329 readListPrecDefault -- Looks for ['f','o','o']
330 ) -- (more generous than H2010 spec)
331
332 readList = readListDefault
333
334 instance Read Bool where
335 readPrec =
336 parens
337 ( do L.Ident s <- lexP
338 case s of
339 "True" -> return True
340 "False" -> return False
341 _ -> pfail
342 )
343
344 readListPrec = readListPrecDefault
345 readList = readListDefault
346
347 instance Read Ordering where
348 readPrec =
349 parens
350 ( do L.Ident s <- lexP
351 case s of
352 "LT" -> return LT
353 "EQ" -> return EQ
354 "GT" -> return GT
355 _ -> pfail
356 )
357
358 readListPrec = readListPrecDefault
359 readList = readListDefault
360
361 --------------------------------------------------------------
362 -- Structure instances of Read: Maybe, List etc
363 --------------------------------------------------------------
364
365 {-
366 For structured instances of Read we start using the precedences. The
367 idea is then that 'parens (prec k p)' will fail immediately when trying
368 to parse it in a context with a higher precedence level than k. But if
369 there is one parenthesis parsed, then the required precedence level
370 drops to 0 again, and parsing inside p may succeed.
371
372 'appPrec' is just the precedence level of function application. So,
373 if we are parsing function application, we'd better require the
374 precedence level to be at least 'appPrec'. Otherwise, we have to put
375 parentheses around it.
376
377 'step' is used to increase the precedence levels inside a
378 parser, and can be used to express left- or right- associativity. For
379 example, % is defined to be left associative, so we only increase
380 precedence on the right hand side.
381
382 Note how step is used in for example the Maybe parser to increase the
383 precedence beyond appPrec, so that basically only literals and
384 parenthesis-like objects such as (...) and [...] can be an argument to
385 'Just'.
386 -}
387
388 instance Read a => Read (Maybe a) where
389 readPrec =
390 parens
391 (do expectP (L.Ident "Nothing")
392 return Nothing
393 +++
394 prec appPrec (
395 do expectP (L.Ident "Just")
396 x <- step readPrec
397 return (Just x))
398 )
399
400 readListPrec = readListPrecDefault
401 readList = readListDefault
402
403 instance Read a => Read [a] where
404 {-# SPECIALISE instance Read [String] #-}
405 {-# SPECIALISE instance Read [Char] #-}
406 {-# SPECIALISE instance Read [Int] #-}
407 readPrec = readListPrec
408 readListPrec = readListPrecDefault
409 readList = readListDefault
410
411 instance (Ix a, Read a, Read b) => Read (Array a b) where
412 readPrec = parens $ prec appPrec $
413 do expectP (L.Ident "array")
414 theBounds <- step readPrec
415 vals <- step readPrec
416 return (array theBounds vals)
417
418 readListPrec = readListPrecDefault
419 readList = readListDefault
420
421 instance Read L.Lexeme where
422 readPrec = lexP
423 readListPrec = readListPrecDefault
424 readList = readListDefault
425
426 --------------------------------------------------------------
427 -- Numeric instances of Read
428 --------------------------------------------------------------
429
430 readNumber :: Num a => (L.Lexeme -> ReadPrec a) -> ReadPrec a
431 -- Read a signed number
432 readNumber convert =
433 parens
434 ( do x <- lexP
435 case x of
436 L.Symbol "-" -> do y <- lexP
437 n <- convert y
438 return (negate n)
439
440 _ -> convert x
441 )
442
443
444 convertInt :: Num a => L.Lexeme -> ReadPrec a
445 convertInt (L.Number n)
446 | Just i <- L.numberToInteger n = return (fromInteger i)
447 convertInt _ = pfail
448
449 convertFrac :: forall a . RealFloat a => L.Lexeme -> ReadPrec a
450 convertFrac (L.Ident "NaN") = return (0 / 0)
451 convertFrac (L.Ident "Infinity") = return (1 / 0)
452 convertFrac (L.Number n) = let resRange = floatRange (undefined :: a)
453 in case L.numberToRangedRational resRange n of
454 Nothing -> return (1 / 0)
455 Just rat -> return $ fromRational rat
456 convertFrac _ = pfail
457
458 instance Read Int where
459 readPrec = readNumber convertInt
460 readListPrec = readListPrecDefault
461 readList = readListDefault
462
463 instance Read Word where
464 readsPrec p s = [(fromInteger x, r) | (x, r) <- readsPrec p s]
465
466 instance Read Integer where
467 readPrec = readNumber convertInt
468 readListPrec = readListPrecDefault
469 readList = readListDefault
470
471 instance Read Float where
472 readPrec = readNumber convertFrac
473 readListPrec = readListPrecDefault
474 readList = readListDefault
475
476 instance Read Double where
477 readPrec = readNumber convertFrac
478 readListPrec = readListPrecDefault
479 readList = readListDefault
480
481 instance (Integral a, Read a) => Read (Ratio a) where
482 readPrec =
483 parens
484 ( prec ratioPrec
485 ( do x <- step readPrec
486 expectP (L.Symbol "%")
487 y <- step readPrec
488 return (x % y)
489 )
490 )
491
492 readListPrec = readListPrecDefault
493 readList = readListDefault
494
495
496 ------------------------------------------------------------------------
497 -- Tuple instances of Read, up to size 15
498 ------------------------------------------------------------------------
499
500 instance Read () where
501 readPrec =
502 parens
503 ( paren
504 ( return ()
505 )
506 )
507
508 readListPrec = readListPrecDefault
509 readList = readListDefault
510
511 instance (Read a, Read b) => Read (a,b) where
512 readPrec = wrap_tup read_tup2
513 readListPrec = readListPrecDefault
514 readList = readListDefault
515
516 wrap_tup :: ReadPrec a -> ReadPrec a
517 wrap_tup p = parens (paren p)
518
519 read_comma :: ReadPrec ()
520 read_comma = expectP (L.Punc ",")
521
522 read_tup2 :: (Read a, Read b) => ReadPrec (a,b)
523 -- Reads "a , b" no parens!
524 read_tup2 = do x <- readPrec
525 read_comma
526 y <- readPrec
527 return (x,y)
528
529 read_tup4 :: (Read a, Read b, Read c, Read d) => ReadPrec (a,b,c,d)
530 read_tup4 = do (a,b) <- read_tup2
531 read_comma
532 (c,d) <- read_tup2
533 return (a,b,c,d)
534
535
536 read_tup8 :: (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
537 => ReadPrec (a,b,c,d,e,f,g,h)
538 read_tup8 = do (a,b,c,d) <- read_tup4
539 read_comma
540 (e,f,g,h) <- read_tup4
541 return (a,b,c,d,e,f,g,h)
542
543
544 instance (Read a, Read b, Read c) => Read (a, b, c) where
545 readPrec = wrap_tup (do { (a,b) <- read_tup2; read_comma
546 ; c <- readPrec
547 ; return (a,b,c) })
548 readListPrec = readListPrecDefault
549 readList = readListDefault
550
551 instance (Read a, Read b, Read c, Read d) => Read (a, b, c, d) where
552 readPrec = wrap_tup read_tup4
553 readListPrec = readListPrecDefault
554 readList = readListDefault
555
556 instance (Read a, Read b, Read c, Read d, Read e) => Read (a, b, c, d, e) where
557 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
558 ; e <- readPrec
559 ; return (a,b,c,d,e) })
560 readListPrec = readListPrecDefault
561 readList = readListDefault
562
563 instance (Read a, Read b, Read c, Read d, Read e, Read f)
564 => Read (a, b, c, d, e, f) where
565 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
566 ; (e,f) <- read_tup2
567 ; return (a,b,c,d,e,f) })
568 readListPrec = readListPrecDefault
569 readList = readListDefault
570
571 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g)
572 => Read (a, b, c, d, e, f, g) where
573 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
574 ; (e,f) <- read_tup2; read_comma
575 ; g <- readPrec
576 ; return (a,b,c,d,e,f,g) })
577 readListPrec = readListPrecDefault
578 readList = readListDefault
579
580 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
581 => Read (a, b, c, d, e, f, g, h) where
582 readPrec = wrap_tup read_tup8
583 readListPrec = readListPrecDefault
584 readList = readListDefault
585
586 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
587 Read i)
588 => Read (a, b, c, d, e, f, g, h, i) where
589 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
590 ; i <- readPrec
591 ; return (a,b,c,d,e,f,g,h,i) })
592 readListPrec = readListPrecDefault
593 readList = readListDefault
594
595 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
596 Read i, Read j)
597 => Read (a, b, c, d, e, f, g, h, i, j) where
598 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
599 ; (i,j) <- read_tup2
600 ; return (a,b,c,d,e,f,g,h,i,j) })
601 readListPrec = readListPrecDefault
602 readList = readListDefault
603
604 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
605 Read i, Read j, Read k)
606 => Read (a, b, c, d, e, f, g, h, i, j, k) where
607 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
608 ; (i,j) <- read_tup2; read_comma
609 ; k <- readPrec
610 ; return (a,b,c,d,e,f,g,h,i,j,k) })
611 readListPrec = readListPrecDefault
612 readList = readListDefault
613
614 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
615 Read i, Read j, Read k, Read l)
616 => Read (a, b, c, d, e, f, g, h, i, j, k, l) where
617 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
618 ; (i,j,k,l) <- read_tup4
619 ; return (a,b,c,d,e,f,g,h,i,j,k,l) })
620 readListPrec = readListPrecDefault
621 readList = readListDefault
622
623 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
624 Read i, Read j, Read k, Read l, Read m)
625 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m) where
626 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
627 ; (i,j,k,l) <- read_tup4; read_comma
628 ; m <- readPrec
629 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m) })
630 readListPrec = readListPrecDefault
631 readList = readListDefault
632
633 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
634 Read i, Read j, Read k, Read l, Read m, Read n)
635 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n) where
636 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
637 ; (i,j,k,l) <- read_tup4; read_comma
638 ; (m,n) <- read_tup2
639 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n) })
640 readListPrec = readListPrecDefault
641 readList = readListDefault
642
643 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
644 Read i, Read j, Read k, Read l, Read m, Read n, Read o)
645 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) where
646 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
647 ; (i,j,k,l) <- read_tup4; read_comma
648 ; (m,n) <- read_tup2; read_comma
649 ; o <- readPrec
650 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) })
651 readListPrec = readListPrecDefault
652 readList = readListDefault