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
69 import {-# SOURCE #-} GHC.Unicode ( isDigit )
81 -- | @'readParen' 'True' p@ parses what @p@ parses, but surrounded with
84 -- @'readParen' 'False' p@ parses what @p@ parses, but optionally
85 -- surrounded with parentheses.
86 readParen :: Bool -> ReadS a -> ReadS a
87 -- A Haskell 98 function
88 readParen b g = if b then mandatory else optional
89 where optional r = g r ++ mandatory r
98 %*********************************************************
100 \subsection{The @Read@ class}
102 %*********************************************************
105 ------------------------------------------------------------------------
108 -- | Parsing of 'String's, producing values.
110 -- Minimal complete definition: 'readsPrec' (or, for GHC only, 'readPrec')
112 -- Derived instances of 'Read' make the following assumptions, which
113 -- derived instances of 'Text.Show.Show' obey:
115 -- * If the constructor is defined to be an infix operator, then the
116 -- derived 'Read' instance will parse only infix applications of
117 -- the constructor (not the prefix form).
119 -- * Associativity is not used to reduce the occurrence of parentheses,
120 -- although precedence may be.
122 -- * If the constructor is defined using record syntax, the derived 'Read'
123 -- will parse only the record-syntax form, and furthermore, the fields
124 -- must be given in the same order as the original declaration.
126 -- * The derived 'Read' instance allows arbitrary Haskell whitespace
127 -- between tokens of the input string. Extra parentheses are also
130 -- For example, given the declarations
133 -- > data Tree a = Leaf a | Tree a :^: Tree a
135 -- the derived instance of 'Read' in Haskell 98 is equivalent to
137 -- > instance (Read a) => Read (Tree a) where
139 -- > readsPrec d r = readParen (d > app_prec)
140 -- > (\r -> [(Leaf m,t) |
141 -- > ("Leaf",s) <- lex r,
142 -- > (m,t) <- readsPrec (app_prec+1) s]) r
144 -- > ++ readParen (d > up_prec)
145 -- > (\r -> [(u:^:v,w) |
146 -- > (u,s) <- readsPrec (up_prec+1) r,
147 -- > (":^:",t) <- lex s,
148 -- > (v,w) <- readsPrec (up_prec+1) t]) r
150 -- > where app_prec = 10
153 -- Note that right-associativity of @:^:@ is unused.
155 -- The derived instance in GHC is equivalent to
157 -- > instance (Read a) => Read (Tree a) where
159 -- > readPrec = parens $ (prec app_prec $ do
160 -- > Ident "Leaf" <- lexP
161 -- > m <- step readPrec
162 -- > return (Leaf m))
164 -- > +++ (prec up_prec $ do
165 -- > u <- step readPrec
166 -- > Symbol ":^:" <- lexP
167 -- > v <- step readPrec
168 -- > return (u :^: v))
170 -- > where app_prec = 10
173 -- > readListPrec = readListPrecDefault
176 -- | attempts to parse a value from the front of the string, returning
177 -- a list of (parsed value, remaining string) pairs. If there is no
178 -- successful parse, the returned list is empty.
180 -- Derived instances of 'Read' and 'Text.Show.Show' satisfy the following:
182 -- * @(x,\"\")@ is an element of
183 -- @('readsPrec' d ('Text.Show.showsPrec' d x \"\"))@.
185 -- That is, 'readsPrec' parses the string produced by
186 -- 'Text.Show.showsPrec', and delivers the value that
187 -- 'Text.Show.showsPrec' started with.
189 readsPrec :: Int -- ^ the operator precedence of the enclosing
190 -- context (a number from @0@ to @11@).
191 -- Function application has precedence @10@.
194 -- | The method 'readList' is provided to allow the programmer to
195 -- give a specialised way of parsing lists of values.
196 -- For example, this is used by the predefined 'Read' instance of
197 -- the 'Char' type, where values of type 'String' should be are
198 -- expected to use double quotes, rather than square brackets.
199 readList :: ReadS [a]
201 -- | Proposed replacement for 'readsPrec' using new-style parsers (GHC only).
202 readPrec :: ReadPrec a
204 -- | Proposed replacement for 'readList' using new-style parsers (GHC only).
205 -- The default definition uses 'readList'. Instances that define 'readPrec'
206 -- should also define 'readListPrec' as 'readListPrecDefault'.
207 readListPrec :: ReadPrec [a]
209 -- default definitions
210 readsPrec = readPrec_to_S readPrec
211 readList = readPrec_to_S (list readPrec) 0
212 readPrec = readS_to_Prec readsPrec
213 readListPrec = readS_to_Prec (\_ -> readList)
215 readListDefault :: Read a => ReadS [a]
216 -- ^ A possible replacement definition for the 'readList' method (GHC only).
217 -- This is only needed for GHC, and even then only for 'Read' instances
218 -- where 'readListPrec' isn't defined as 'readListPrecDefault'.
219 readListDefault = readPrec_to_S readListPrec 0
221 readListPrecDefault :: Read a => ReadPrec [a]
222 -- ^ A possible replacement definition for the 'readListPrec' method,
223 -- defined using 'readPrec' (GHC only).
224 readListPrecDefault = list readPrec
226 ------------------------------------------------------------------------
229 -- | equivalent to 'readsPrec' with a precedence of 0.
230 reads :: Read a => ReadS a
231 reads = readsPrec minPrec
233 readp :: Read a => ReadP a
234 readp = readPrec_to_P readPrec minPrec
236 readEither :: Read a => String -> Either String a
238 case [ x | (x,"") <- readPrec_to_S read' minPrec s ] of
240 [] -> Left "Prelude.read: no parse"
241 _ -> Left "Prelude.read: ambiguous parse"
248 -- | The 'read' function reads input from a string, which must be
249 -- completely consumed by the input process.
250 read :: Read a => String -> a
251 read s = either error id (readEither s)
253 ------------------------------------------------------------------------
256 -- | The 'lex' function reads a single lexeme from the input, discarding
257 -- initial white space, and returning the characters that constitute the
258 -- lexeme. If the input string contains only white space, 'lex' returns a
259 -- single successful \`lexeme\' consisting of the empty string. (Thus
260 -- @'lex' \"\" = [(\"\",\"\")]@.) If there is no legal lexeme at the
261 -- beginning of the input string, 'lex' fails (i.e. returns @[]@).
263 -- This lexer is not completely faithful to the Haskell lexical syntax
264 -- in the following respects:
266 -- * Qualified names are not handled properly
268 -- * Octal and hexadecimal numerics are not recognized as a single token
270 -- * Comments are not treated properly
271 lex :: ReadS String -- As defined by H98
272 lex s = readP_to_S L.hsLex s
274 -- | Read a string representation of a character, using Haskell
275 -- source-language escape conventions. For example:
277 -- > lexLitChar "\\nHello" = [("\\n", "Hello")]
279 lexLitChar :: ReadS String -- As defined by H98
280 lexLitChar = readP_to_S (do { (s, _) <- P.gather L.lexChar ;
282 -- There was a skipSpaces before the P.gather L.lexChar,
283 -- but that seems inconsistent with readLitChar
285 -- | Read a string representation of a character, using Haskell
286 -- source-language escape conventions, and convert it to the character
287 -- that it encodes. For example:
289 -- > readLitChar "\\nHello" = [('\n', "Hello")]
291 readLitChar :: ReadS Char -- As defined by H98
292 readLitChar = readP_to_S L.lexChar
294 -- | Reads a non-empty string of decimal digits.
295 lexDigits :: ReadS String
296 lexDigits = readP_to_S (P.munch1 isDigit)
298 ------------------------------------------------------------------------
301 lexP :: ReadPrec L.Lexeme
302 -- ^ Parse a single lexeme
305 paren :: ReadPrec a -> ReadPrec a
306 -- ^ @(paren p)@ parses \"(P0)\"
307 -- where @p@ parses \"P0\" in precedence context zero
308 paren p = do L.Punc "(" <- lexP
313 parens :: ReadPrec a -> ReadPrec a
314 -- ^ @(parens p)@ parses \"P\", \"(P0)\", \"((P0))\", etc,
315 -- where @p@ parses \"P\" in the current precedence context
316 -- and parses \"P0\" in precedence context zero
319 optional = p +++ mandatory
320 mandatory = paren optional
322 list :: ReadPrec a -> ReadPrec [a]
323 -- ^ @(list p)@ parses a list of things parsed by @p@,
324 -- using the usual square-bracket syntax.
327 ( do L.Punc "[" <- lexP
328 (listRest False +++ listNext)
335 "," | started -> listNext
343 choose :: [(String, ReadPrec a)] -> ReadPrec a
344 -- ^ Parse the specified lexeme and continue as specified.
345 -- Esp useful for nullary constructors; e.g.
346 -- @choose [(\"A\", return A), (\"B\", return B)]@
347 choose sps = foldr ((+++) . try_one) pfail sps
349 try_one (s,p) = do { L.Ident s' <- lexP ;
350 if s == s' then p else pfail }
354 %*********************************************************
356 \subsection{Simple instances of Read}
358 %*********************************************************
361 instance Read Char where
364 ( do L.Char c <- lexP
370 ( do L.String s <- lexP -- Looks for "foo"
373 readListPrecDefault -- Looks for ['f','o','o']
374 ) -- (more generous than H98 spec)
376 readList = readListDefault
378 instance Read Bool where
381 ( do L.Ident s <- lexP
383 "True" -> return True
384 "False" -> return False
388 readListPrec = readListPrecDefault
389 readList = readListDefault
391 instance Read Ordering where
394 ( do L.Ident s <- lexP
402 readListPrec = readListPrecDefault
403 readList = readListDefault
407 %*********************************************************
409 \subsection{Structure instances of Read: Maybe, List etc}
411 %*********************************************************
413 For structured instances of Read we start using the precedences. The
414 idea is then that 'parens (prec k p)' will fail immediately when trying
415 to parse it in a context with a higher precedence level than k. But if
416 there is one parenthesis parsed, then the required precedence level
417 drops to 0 again, and parsing inside p may succeed.
419 'appPrec' is just the precedence level of function application. So,
420 if we are parsing function application, we'd better require the
421 precedence level to be at least 'appPrec'. Otherwise, we have to put
422 parentheses around it.
424 'step' is used to increase the precedence levels inside a
425 parser, and can be used to express left- or right- associativity. For
426 example, % is defined to be left associative, so we only increase
427 precedence on the right hand side.
429 Note how step is used in for example the Maybe parser to increase the
430 precedence beyond appPrec, so that basically only literals and
431 parenthesis-like objects such as (...) and [...] can be an argument to
435 instance Read a => Read (Maybe a) where
438 (do L.Ident "Nothing" <- lexP
442 do L.Ident "Just" <- lexP
447 readListPrec = readListPrecDefault
448 readList = readListDefault
450 instance (Read a, Read b) => Read (Either a b) where
454 ( do L.Ident "Left" <- lexP
458 do L.Ident "Right" <- lexP
464 readListPrec = readListPrecDefault
465 readList = readListDefault
467 instance Read a => Read [a] where
468 readPrec = readListPrec
469 readListPrec = readListPrecDefault
470 readList = readListDefault
472 instance (Ix a, Read a, Read b) => Read (Array a b) where
473 readPrec = parens $ prec appPrec $
474 do L.Ident "array" <- lexP
475 bounds <- step readPrec
476 vals <- step readPrec
477 return (array bounds vals)
479 readListPrec = readListPrecDefault
480 readList = readListDefault
482 instance Read L.Lexeme where
484 readListPrec = readListPrecDefault
485 readList = readListDefault
489 %*********************************************************
491 \subsection{Numeric instances of Read}
493 %*********************************************************
496 readNumber :: Num a => (L.Lexeme -> Maybe a) -> ReadPrec a
497 -- Read a signed number
502 L.Symbol "-" -> do n <- readNumber convert
505 _ -> case convert x of
510 convertInt :: Num a => L.Lexeme -> Maybe a
511 convertInt (L.Int i) = Just (fromInteger i)
512 convertInt _ = Nothing
514 convertFrac :: Fractional a => L.Lexeme -> Maybe a
515 convertFrac (L.Int i) = Just (fromInteger i)
516 convertFrac (L.Rat r) = Just (fromRational r)
517 convertFrac _ = Nothing
519 instance Read Int where
520 readPrec = readNumber convertInt
521 readListPrec = readListPrecDefault
522 readList = readListDefault
524 instance Read Integer where
525 readPrec = readNumber convertInt
526 readListPrec = readListPrecDefault
527 readList = readListDefault
529 instance Read Float where
530 readPrec = readNumber convertFrac
531 readListPrec = readListPrecDefault
532 readList = readListDefault
534 instance Read Double where
535 readPrec = readNumber convertFrac
536 readListPrec = readListPrecDefault
537 readList = readListDefault
539 instance (Integral a, Read a) => Read (Ratio a) where
543 ( do x <- step readPrec
550 readListPrec = readListPrecDefault
551 readList = readListDefault
555 %*********************************************************
557 Tuple instances of Read, up to size 15
559 %*********************************************************
562 instance Read () where
570 readListPrec = readListPrecDefault
571 readList = readListDefault
573 instance (Read a, Read b) => Read (a,b) where
574 readPrec = wrap_tup read_tup2
575 readListPrec = readListPrecDefault
576 readList = readListDefault
578 wrap_tup :: ReadPrec a -> ReadPrec a
579 wrap_tup p = parens (paren p)
581 read_comma :: ReadPrec ()
582 read_comma = do { L.Punc "," <- lexP; return () }
584 read_tup2 :: (Read a, Read b) => ReadPrec (a,b)
585 -- Reads "a , b" no parens!
586 read_tup2 = do x <- readPrec
591 read_tup4 :: (Read a, Read b, Read c, Read d) => ReadPrec (a,b,c,d)
592 read_tup4 = do (a,b) <- read_tup2
598 read_tup8 :: (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
599 => ReadPrec (a,b,c,d,e,f,g,h)
600 read_tup8 = do (a,b,c,d) <- read_tup4
602 (e,f,g,h) <- read_tup4
603 return (a,b,c,d,e,f,g,h)
606 instance (Read a, Read b, Read c) => Read (a, b, c) where
607 readPrec = wrap_tup (do { (a,b) <- read_tup2; read_comma
610 readListPrec = readListPrecDefault
611 readList = readListDefault
613 instance (Read a, Read b, Read c, Read d) => Read (a, b, c, d) where
614 readPrec = wrap_tup read_tup4
615 readListPrec = readListPrecDefault
616 readList = readListDefault
618 instance (Read a, Read b, Read c, Read d, Read e) => Read (a, b, c, d, e) where
619 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
621 ; return (a,b,c,d,e) })
622 readListPrec = readListPrecDefault
623 readList = readListDefault
625 instance (Read a, Read b, Read c, Read d, Read e, Read f)
626 => Read (a, b, c, d, e, f) where
627 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
629 ; return (a,b,c,d,e,f) })
630 readListPrec = readListPrecDefault
631 readList = readListDefault
633 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g)
634 => Read (a, b, c, d, e, f, g) where
635 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
636 ; (e,f) <- read_tup2; read_comma
638 ; return (a,b,c,d,e,f,g) })
639 readListPrec = readListPrecDefault
640 readList = readListDefault
642 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
643 => Read (a, b, c, d, e, f, g, h) where
644 readPrec = wrap_tup read_tup8
645 readListPrec = readListPrecDefault
646 readList = readListDefault
648 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
650 => Read (a, b, c, d, e, f, g, h, i) where
651 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
653 ; return (a,b,c,d,e,f,g,h,i) })
654 readListPrec = readListPrecDefault
655 readList = readListDefault
657 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
659 => Read (a, b, c, d, e, f, g, h, i, j) where
660 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
662 ; return (a,b,c,d,e,f,g,h,i,j) })
663 readListPrec = readListPrecDefault
664 readList = readListDefault
666 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
667 Read i, Read j, Read k)
668 => Read (a, b, c, d, e, f, g, h, i, j, k) where
669 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
670 ; (i,j) <- read_tup2; read_comma
672 ; return (a,b,c,d,e,f,g,h,i,j,k) })
673 readListPrec = readListPrecDefault
674 readList = readListDefault
676 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
677 Read i, Read j, Read k, Read l)
678 => Read (a, b, c, d, e, f, g, h, i, j, k, l) where
679 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
680 ; (i,j,k,l) <- read_tup4
681 ; return (a,b,c,d,e,f,g,h,i,j,k,l) })
682 readListPrec = readListPrecDefault
683 readList = readListDefault
685 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
686 Read i, Read j, Read k, Read l, Read m)
687 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m) where
688 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
689 ; (i,j,k,l) <- read_tup4; read_comma
691 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m) })
692 readListPrec = readListPrecDefault
693 readList = readListDefault
695 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
696 Read i, Read j, Read k, Read l, Read m, Read n)
697 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n) where
698 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
699 ; (i,j,k,l) <- read_tup4; read_comma
701 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n) })
702 readListPrec = readListPrecDefault
703 readList = readListDefault
705 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
706 Read i, Read j, Read k, Read l, Read m, Read n, Read o)
707 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) where
708 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
709 ; (i,j,k,l) <- read_tup4; read_comma
710 ; (m,n) <- read_tup2; read_comma
712 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) })
713 readListPrec = readListPrecDefault
714 readList = readListDefault