2 {-# OPTIONS_GHC -fno-implicit-prelude #-}
3 -----------------------------------------------------------------------------
6 -- Copyright : (c) The University of Glasgow, 1994-2002
7 -- License : see libraries/base/LICENSE
9 -- Maintainer : cvs-ghc@haskell.org
10 -- Stability : internal
11 -- Portability : non-portable (GHC Extensions)
13 -- The 'Read' class and instances for basic data types.
15 -----------------------------------------------------------------------------
22 , ReadS -- :: *; = String -> [(a,String)]
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
31 , lex -- :: ReadS String
32 , lexLitChar -- :: ReadS String
33 , readLitChar -- :: ReadS Char
34 , lexDigits -- :: ReadS String
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
49 import qualified Text.ParserCombinators.ReadP as P
51 import Text.ParserCombinators.ReadP
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
63 import Text.ParserCombinators.ReadPrec
68 import {-# SOURCE #-} GHC.Err ( error )
70 import {-# SOURCE #-} GHC.Unicode ( isDigit )
82 -- | @'readParen' 'True' p@ parses what @p@ parses, but surrounded with
85 -- @'readParen' 'False' p@ parses what @p@ parses, but optionally
86 -- surrounded with parentheses.
87 readParen :: Bool -> ReadS a -> ReadS a
88 -- A Haskell 98 function
89 readParen b g = if b then mandatory else optional
90 where optional r = g r ++ mandatory r
99 %*********************************************************
101 \subsection{The @Read@ class}
103 %*********************************************************
106 ------------------------------------------------------------------------
109 -- | Parsing of 'String's, producing values.
111 -- Minimal complete definition: 'readsPrec' (or, for GHC only, 'readPrec')
113 -- Derived instances of 'Read' make the following assumptions, which
114 -- derived instances of 'Text.Show.Show' obey:
116 -- * If the constructor is defined to be an infix operator, then the
117 -- derived 'Read' instance will parse only infix applications of
118 -- the constructor (not the prefix form).
120 -- * Associativity is not used to reduce the occurrence of parentheses,
121 -- although precedence may be.
123 -- * If the constructor is defined using record syntax, the derived 'Read'
124 -- will parse only the record-syntax form, and furthermore, the fields
125 -- must be given in the same order as the original declaration.
127 -- * The derived 'Read' instance allows arbitrary Haskell whitespace
128 -- between tokens of the input string. Extra parentheses are also
131 -- For example, given the declarations
134 -- > data Tree a = Leaf a | Tree a :^: Tree a
136 -- the derived instance of 'Read' in Haskell 98 is equivalent to
138 -- > instance (Read a) => Read (Tree a) where
140 -- > readsPrec d r = readParen (d > app_prec)
141 -- > (\r -> [(Leaf m,t) |
142 -- > ("Leaf",s) <- lex r,
143 -- > (m,t) <- readsPrec (app_prec+1) s]) r
145 -- > ++ readParen (d > up_prec)
146 -- > (\r -> [(u:^:v,w) |
147 -- > (u,s) <- readsPrec (up_prec+1) r,
148 -- > (":^:",t) <- lex s,
149 -- > (v,w) <- readsPrec (up_prec+1) t]) r
151 -- > where app_prec = 10
154 -- Note that right-associativity of @:^:@ is unused.
156 -- The derived instance in GHC is equivalent to
158 -- > instance (Read a) => Read (Tree a) where
160 -- > readPrec = parens $ (prec app_prec $ do
161 -- > Ident "Leaf" <- lexP
162 -- > m <- step readPrec
163 -- > return (Leaf m))
165 -- > +++ (prec up_prec $ do
166 -- > u <- step readPrec
167 -- > Symbol ":^:" <- lexP
168 -- > v <- step readPrec
169 -- > return (u :^: v))
171 -- > where app_prec = 10
174 -- > readListPrec = readListPrecDefault
177 -- | attempts to parse a value from the front of the string, returning
178 -- a list of (parsed value, remaining string) pairs. If there is no
179 -- successful parse, the returned list is empty.
181 -- Derived instances of 'Read' and 'Text.Show.Show' satisfy the following:
183 -- * @(x,\"\")@ is an element of
184 -- @('readsPrec' d ('Text.Show.showsPrec' d x \"\"))@.
186 -- That is, 'readsPrec' parses the string produced by
187 -- 'Text.Show.showsPrec', and delivers the value that
188 -- 'Text.Show.showsPrec' started with.
190 readsPrec :: Int -- ^ the operator precedence of the enclosing
191 -- context (a number from @0@ to @11@).
192 -- Function application has precedence @10@.
195 -- | The method 'readList' is provided to allow the programmer to
196 -- give a specialised way of parsing lists of values.
197 -- For example, this is used by the predefined 'Read' instance of
198 -- the 'Char' type, where values of type 'String' should be are
199 -- expected to use double quotes, rather than square brackets.
200 readList :: ReadS [a]
202 -- | Proposed replacement for 'readsPrec' using new-style parsers (GHC only).
203 readPrec :: ReadPrec a
205 -- | Proposed replacement for 'readList' using new-style parsers (GHC only).
206 -- The default definition uses 'readList'. Instances that define 'readPrec'
207 -- should also define 'readListPrec' as 'readListPrecDefault'.
208 readListPrec :: ReadPrec [a]
210 -- default definitions
211 readsPrec = readPrec_to_S readPrec
212 readList = readPrec_to_S (list readPrec) 0
213 readPrec = readS_to_Prec readsPrec
214 readListPrec = readS_to_Prec (\_ -> readList)
216 readListDefault :: Read a => ReadS [a]
217 -- ^ A possible replacement definition for the 'readList' method (GHC only).
218 -- This is only needed for GHC, and even then only for 'Read' instances
219 -- where 'readListPrec' isn't defined as 'readListPrecDefault'.
220 readListDefault = readPrec_to_S readListPrec 0
222 readListPrecDefault :: Read a => ReadPrec [a]
223 -- ^ A possible replacement definition for the 'readListPrec' method,
224 -- defined using 'readPrec' (GHC only).
225 readListPrecDefault = list readPrec
227 ------------------------------------------------------------------------
230 -- | equivalent to 'readsPrec' with a precedence of 0.
231 reads :: Read a => ReadS a
232 reads = readsPrec minPrec
234 readp :: Read a => ReadP a
235 readp = readPrec_to_P readPrec minPrec
237 readEither :: Read a => String -> Either String a
239 case [ x | (x,"") <- readPrec_to_S read' minPrec s ] of
241 [] -> Left "Prelude.read: no parse"
242 _ -> Left "Prelude.read: ambiguous parse"
249 -- | The 'read' function reads input from a string, which must be
250 -- completely consumed by the input process.
251 read :: Read a => String -> a
252 read s = either error id (readEither s)
254 ------------------------------------------------------------------------
257 -- | The 'lex' function reads a single lexeme from the input, discarding
258 -- initial white space, and returning the characters that constitute the
259 -- lexeme. If the input string contains only white space, 'lex' returns a
260 -- single successful \`lexeme\' consisting of the empty string. (Thus
261 -- @'lex' \"\" = [(\"\",\"\")]@.) If there is no legal lexeme at the
262 -- beginning of the input string, 'lex' fails (i.e. returns @[]@).
264 -- This lexer is not completely faithful to the Haskell lexical syntax
265 -- in the following respects:
267 -- * Qualified names are not handled properly
269 -- * Octal and hexadecimal numerics are not recognized as a single token
271 -- * Comments are not treated properly
272 lex :: ReadS String -- As defined by H98
273 lex s = readP_to_S L.hsLex s
275 -- | Read a string representation of a character, using Haskell
276 -- source-language escape conventions. For example:
278 -- > lexLitChar "\\nHello" = [("\\n", "Hello")]
280 lexLitChar :: ReadS String -- As defined by H98
281 lexLitChar = readP_to_S (do { (s, _) <- P.gather L.lexChar ;
283 -- There was a skipSpaces before the P.gather L.lexChar,
284 -- but that seems inconsistent with readLitChar
286 -- | Read a string representation of a character, using Haskell
287 -- source-language escape conventions, and convert it to the character
288 -- that it encodes. For example:
290 -- > readLitChar "\\nHello" = [('\n', "Hello")]
292 readLitChar :: ReadS Char -- As defined by H98
293 readLitChar = readP_to_S L.lexChar
295 -- | Reads a non-empty string of decimal digits.
296 lexDigits :: ReadS String
297 lexDigits = readP_to_S (P.munch1 isDigit)
299 ------------------------------------------------------------------------
302 lexP :: ReadPrec L.Lexeme
303 -- ^ Parse a single lexeme
306 paren :: ReadPrec a -> ReadPrec a
307 -- ^ @(paren p)@ parses \"(P0)\"
308 -- where @p@ parses \"P0\" in precedence context zero
309 paren p = do L.Punc "(" <- lexP
314 parens :: ReadPrec a -> ReadPrec a
315 -- ^ @(parens p)@ parses \"P\", \"(P0)\", \"((P0))\", etc,
316 -- where @p@ parses \"P\" in the current precedence context
317 -- and parses \"P0\" in precedence context zero
320 optional = p +++ mandatory
321 mandatory = paren optional
323 list :: ReadPrec a -> ReadPrec [a]
324 -- ^ @(list p)@ parses a list of things parsed by @p@,
325 -- using the usual square-bracket syntax.
328 ( do L.Punc "[" <- lexP
329 (listRest False +++ listNext)
336 "," | started -> listNext
344 choose :: [(String, ReadPrec a)] -> ReadPrec a
345 -- ^ Parse the specified lexeme and continue as specified.
346 -- Esp useful for nullary constructors; e.g.
347 -- @choose [(\"A\", return A), (\"B\", return B)]@
348 choose sps = foldr ((+++) . try_one) pfail sps
350 try_one (s,p) = do { L.Ident s' <- lexP ;
351 if s == s' then p else pfail }
355 %*********************************************************
357 \subsection{Simple instances of Read}
359 %*********************************************************
362 instance Read Char where
365 ( do L.Char c <- lexP
371 ( do L.String s <- lexP -- Looks for "foo"
374 readListPrecDefault -- Looks for ['f','o','o']
375 ) -- (more generous than H98 spec)
377 readList = readListDefault
379 instance Read Bool where
382 ( do L.Ident s <- lexP
384 "True" -> return True
385 "False" -> return False
389 readListPrec = readListPrecDefault
390 readList = readListDefault
392 instance Read Ordering where
395 ( do L.Ident s <- lexP
403 readListPrec = readListPrecDefault
404 readList = readListDefault
408 %*********************************************************
410 \subsection{Structure instances of Read: Maybe, List etc}
412 %*********************************************************
414 For structured instances of Read we start using the precedences. The
415 idea is then that 'parens (prec k p)' will fail immediately when trying
416 to parse it in a context with a higher precedence level than k. But if
417 there is one parenthesis parsed, then the required precedence level
418 drops to 0 again, and parsing inside p may succeed.
420 'appPrec' is just the precedence level of function application. So,
421 if we are parsing function application, we'd better require the
422 precedence level to be at least 'appPrec'. Otherwise, we have to put
423 parentheses around it.
425 'step' is used to increase the precedence levels inside a
426 parser, and can be used to express left- or right- associativity. For
427 example, % is defined to be left associative, so we only increase
428 precedence on the right hand side.
430 Note how step is used in for example the Maybe parser to increase the
431 precedence beyond appPrec, so that basically only literals and
432 parenthesis-like objects such as (...) and [...] can be an argument to
436 instance Read a => Read (Maybe a) where
439 (do L.Ident "Nothing" <- lexP
443 do L.Ident "Just" <- lexP
448 readListPrec = readListPrecDefault
449 readList = readListDefault
451 instance (Read a, Read b) => Read (Either a b) where
455 ( do L.Ident "Left" <- lexP
459 do L.Ident "Right" <- lexP
465 readListPrec = readListPrecDefault
466 readList = readListDefault
468 instance Read a => Read [a] where
469 readPrec = readListPrec
470 readListPrec = readListPrecDefault
471 readList = readListDefault
473 instance (Ix a, Read a, Read b) => Read (Array a b) where
474 readPrec = parens $ prec appPrec $
475 do L.Ident "array" <- lexP
476 bounds <- step readPrec
477 vals <- step readPrec
478 return (array bounds vals)
480 readListPrec = readListPrecDefault
481 readList = readListDefault
483 instance Read L.Lexeme where
485 readListPrec = readListPrecDefault
486 readList = readListDefault
490 %*********************************************************
492 \subsection{Numeric instances of Read}
494 %*********************************************************
497 readNumber :: Num a => (L.Lexeme -> Maybe a) -> ReadPrec a
498 -- Read a signed number
503 L.Symbol "-" -> do n <- readNumber convert
506 _ -> case convert x of
511 convertInt :: Num a => L.Lexeme -> Maybe a
512 convertInt (L.Int i) = Just (fromInteger i)
513 convertInt _ = Nothing
515 convertFrac :: Fractional a => L.Lexeme -> Maybe a
516 convertFrac (L.Int i) = Just (fromInteger i)
517 convertFrac (L.Rat r) = Just (fromRational r)
518 convertFrac _ = Nothing
520 instance Read Int where
521 readPrec = readNumber convertInt
522 readListPrec = readListPrecDefault
523 readList = readListDefault
525 instance Read Integer where
526 readPrec = readNumber convertInt
527 readListPrec = readListPrecDefault
528 readList = readListDefault
530 instance Read Float where
531 readPrec = readNumber convertFrac
532 readListPrec = readListPrecDefault
533 readList = readListDefault
535 instance Read Double where
536 readPrec = readNumber convertFrac
537 readListPrec = readListPrecDefault
538 readList = readListDefault
540 instance (Integral a, Read a) => Read (Ratio a) where
544 ( do x <- step readPrec
551 readListPrec = readListPrecDefault
552 readList = readListDefault
556 %*********************************************************
558 Tuple instances of Read, up to size 15
560 %*********************************************************
563 instance Read () where
571 readListPrec = readListPrecDefault
572 readList = readListDefault
574 instance (Read a, Read b) => Read (a,b) where
575 readPrec = wrap_tup read_tup2
576 readListPrec = readListPrecDefault
577 readList = readListDefault
579 wrap_tup :: ReadPrec a -> ReadPrec a
580 wrap_tup p = parens (paren p)
582 read_comma :: ReadPrec ()
583 read_comma = do { L.Punc "," <- lexP; return () }
585 read_tup2 :: (Read a, Read b) => ReadPrec (a,b)
586 -- Reads "a , b" no parens!
587 read_tup2 = do x <- readPrec
592 read_tup4 :: (Read a, Read b, Read c, Read d) => ReadPrec (a,b,c,d)
593 read_tup4 = do (a,b) <- read_tup2
599 read_tup8 :: (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
600 => ReadPrec (a,b,c,d,e,f,g,h)
601 read_tup8 = do (a,b,c,d) <- read_tup4
603 (e,f,g,h) <- read_tup4
604 return (a,b,c,d,e,f,g,h)
607 instance (Read a, Read b, Read c) => Read (a, b, c) where
608 readPrec = wrap_tup (do { (a,b) <- read_tup2; read_comma
611 readListPrec = readListPrecDefault
612 readList = readListDefault
614 instance (Read a, Read b, Read c, Read d) => Read (a, b, c, d) where
615 readPrec = wrap_tup read_tup4
616 readListPrec = readListPrecDefault
617 readList = readListDefault
619 instance (Read a, Read b, Read c, Read d, Read e) => Read (a, b, c, d, e) where
620 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
622 ; return (a,b,c,d,e) })
623 readListPrec = readListPrecDefault
624 readList = readListDefault
626 instance (Read a, Read b, Read c, Read d, Read e, Read f)
627 => Read (a, b, c, d, e, f) where
628 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
630 ; return (a,b,c,d,e,f) })
631 readListPrec = readListPrecDefault
632 readList = readListDefault
634 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g)
635 => Read (a, b, c, d, e, f, g) where
636 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
637 ; (e,f) <- read_tup2; read_comma
639 ; return (a,b,c,d,e,f,g) })
640 readListPrec = readListPrecDefault
641 readList = readListDefault
643 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
644 => Read (a, b, c, d, e, f, g, h) where
645 readPrec = wrap_tup read_tup8
646 readListPrec = readListPrecDefault
647 readList = readListDefault
649 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
651 => Read (a, b, c, d, e, f, g, h, i) where
652 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
654 ; return (a,b,c,d,e,f,g,h,i) })
655 readListPrec = readListPrecDefault
656 readList = readListDefault
658 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
660 => Read (a, b, c, d, e, f, g, h, i, j) where
661 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
663 ; return (a,b,c,d,e,f,g,h,i,j) })
664 readListPrec = readListPrecDefault
665 readList = readListDefault
667 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
668 Read i, Read j, Read k)
669 => Read (a, b, c, d, e, f, g, h, i, j, k) where
670 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
671 ; (i,j) <- read_tup2; read_comma
673 ; return (a,b,c,d,e,f,g,h,i,j,k) })
674 readListPrec = readListPrecDefault
675 readList = readListDefault
677 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
678 Read i, Read j, Read k, Read l)
679 => Read (a, b, c, d, e, f, g, h, i, j, k, l) where
680 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
681 ; (i,j,k,l) <- read_tup4
682 ; return (a,b,c,d,e,f,g,h,i,j,k,l) })
683 readListPrec = readListPrecDefault
684 readList = readListDefault
686 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
687 Read i, Read j, Read k, Read l, Read m)
688 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m) where
689 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
690 ; (i,j,k,l) <- read_tup4; read_comma
692 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m) })
693 readListPrec = readListPrecDefault
694 readList = readListDefault
696 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
697 Read i, Read j, Read k, Read l, Read m, Read n)
698 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n) where
699 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
700 ; (i,j,k,l) <- read_tup4; read_comma
702 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n) })
703 readListPrec = readListPrecDefault
704 readList = readListDefault
706 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
707 Read i, Read j, Read k, Read l, Read m, Read n, Read o)
708 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) where
709 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
710 ; (i,j,k,l) <- read_tup4; read_comma
711 ; (m,n) <- read_tup2; read_comma
713 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) })
714 readListPrec = readListPrecDefault
715 readList = readListDefault