2 {-# OPTIONS_GHC -XNoImplicitPrelude #-}
3 {-# OPTIONS_HADDOCK hide #-}
4 -----------------------------------------------------------------------------
7 -- Copyright : (c) The University of Glasgow, 1994-2002
8 -- License : see libraries/base/LICENSE
10 -- Maintainer : cvs-ghc@haskell.org
11 -- Stability : internal
12 -- Portability : non-portable (GHC Extensions)
14 -- The 'Read' class and instances for basic data types.
16 -----------------------------------------------------------------------------
23 , ReadS -- :: *; = String -> [(a,String)]
26 , lex -- :: ReadS String
27 , lexLitChar -- :: ReadS String
28 , readLitChar -- :: ReadS Char
29 , lexDigits -- :: ReadS String
32 , lexP -- :: ReadPrec Lexeme
33 , paren -- :: ReadPrec a -> ReadPrec a
34 , parens -- :: ReadPrec a -> ReadPrec a
35 , list -- :: ReadPrec a -> ReadPrec [a]
36 , choose -- :: [(String, ReadPrec a)] -> ReadPrec a
37 , readListDefault, readListPrecDefault
42 -- XXX Can this be removed?
47 import qualified Text.ParserCombinators.ReadP as P
49 import Text.ParserCombinators.ReadP
55 import qualified Text.Read.Lex as L
56 -- Lex exports 'lex', which is also defined here,
57 -- hence the qualified import.
58 -- We can't import *anything* unqualified, because that
61 import Text.ParserCombinators.ReadPrec
66 import {-# SOURCE #-} GHC.Unicode ( isDigit )
78 -- | @'readParen' 'True' p@ parses what @p@ parses, but surrounded with
81 -- @'readParen' 'False' p@ parses what @p@ parses, but optionally
82 -- surrounded with parentheses.
83 readParen :: Bool -> ReadS a -> ReadS a
84 -- A Haskell 98 function
85 readParen b g = if b then mandatory else optional
86 where optional r = g r ++ mandatory r
95 %*********************************************************
97 \subsection{The @Read@ class}
99 %*********************************************************
102 ------------------------------------------------------------------------
105 -- | Parsing of 'String's, producing values.
107 -- Minimal complete definition: 'readsPrec' (or, for GHC only, 'readPrec')
109 -- Derived instances of 'Read' make the following assumptions, which
110 -- derived instances of 'Text.Show.Show' obey:
112 -- * If the constructor is defined to be an infix operator, then the
113 -- derived 'Read' instance will parse only infix applications of
114 -- the constructor (not the prefix form).
116 -- * Associativity is not used to reduce the occurrence of parentheses,
117 -- although precedence may be.
119 -- * If the constructor is defined using record syntax, the derived 'Read'
120 -- will parse only the record-syntax form, and furthermore, the fields
121 -- must be given in the same order as the original declaration.
123 -- * The derived 'Read' instance allows arbitrary Haskell whitespace
124 -- between tokens of the input string. Extra parentheses are also
127 -- For example, given the declarations
130 -- > data Tree a = Leaf a | Tree a :^: Tree a
132 -- the derived instance of 'Read' in Haskell 98 is equivalent to
134 -- > instance (Read a) => Read (Tree a) where
136 -- > readsPrec d r = readParen (d > app_prec)
137 -- > (\r -> [(Leaf m,t) |
138 -- > ("Leaf",s) <- lex r,
139 -- > (m,t) <- readsPrec (app_prec+1) s]) r
141 -- > ++ 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
147 -- > where app_prec = 10
150 -- Note that right-associativity of @:^:@ is unused.
152 -- The derived instance in GHC is equivalent to
154 -- > instance (Read a) => Read (Tree a) where
156 -- > readPrec = parens $ (prec app_prec $ do
157 -- > Ident "Leaf" <- lexP
158 -- > m <- step readPrec
159 -- > return (Leaf m))
161 -- > +++ (prec up_prec $ do
162 -- > u <- step readPrec
163 -- > Symbol ":^:" <- lexP
164 -- > v <- step readPrec
165 -- > return (u :^: v))
167 -- > where app_prec = 10
170 -- > readListPrec = readListPrecDefault
173 -- | attempts to parse a value from the front of the string, returning
174 -- a list of (parsed value, remaining string) pairs. If there is no
175 -- successful parse, the returned list is empty.
177 -- Derived instances of 'Read' and 'Text.Show.Show' satisfy the following:
179 -- * @(x,\"\")@ is an element of
180 -- @('readsPrec' d ('Text.Show.showsPrec' d x \"\"))@.
182 -- That is, 'readsPrec' parses the string produced by
183 -- 'Text.Show.showsPrec', and delivers the value that
184 -- 'Text.Show.showsPrec' started with.
186 readsPrec :: Int -- ^ the operator precedence of the enclosing
187 -- context (a number from @0@ to @11@).
188 -- Function application has precedence @10@.
191 -- | The method 'readList' is provided to allow the programmer to
192 -- give a specialised way of parsing lists of values.
193 -- For example, this is used by the predefined 'Read' instance of
194 -- the 'Char' type, where values of type 'String' should be are
195 -- expected to use double quotes, rather than square brackets.
196 readList :: ReadS [a]
198 -- | Proposed replacement for 'readsPrec' using new-style parsers (GHC only).
199 readPrec :: ReadPrec a
201 -- | Proposed replacement for 'readList' using new-style parsers (GHC only).
202 -- The default definition uses 'readList'. Instances that define 'readPrec'
203 -- should also define 'readListPrec' as 'readListPrecDefault'.
204 readListPrec :: ReadPrec [a]
206 -- default definitions
207 readsPrec = readPrec_to_S readPrec
208 readList = readPrec_to_S (list readPrec) 0
209 readPrec = readS_to_Prec readsPrec
210 readListPrec = readS_to_Prec (\_ -> readList)
212 readListDefault :: Read a => ReadS [a]
213 -- ^ A possible replacement definition for the 'readList' method (GHC only).
214 -- This is only needed for GHC, and even then only for 'Read' instances
215 -- where 'readListPrec' isn't defined as 'readListPrecDefault'.
216 readListDefault = readPrec_to_S readListPrec 0
218 readListPrecDefault :: Read a => ReadPrec [a]
219 -- ^ A possible replacement definition for the 'readListPrec' method,
220 -- defined using 'readPrec' (GHC only).
221 readListPrecDefault = list readPrec
223 ------------------------------------------------------------------------
226 -- | The 'lex' function reads a single lexeme from the input, discarding
227 -- initial white space, and returning the characters that constitute the
228 -- lexeme. If the input string contains only white space, 'lex' returns a
229 -- single successful \`lexeme\' consisting of the empty string. (Thus
230 -- @'lex' \"\" = [(\"\",\"\")]@.) If there is no legal lexeme at the
231 -- beginning of the input string, 'lex' fails (i.e. returns @[]@).
233 -- This lexer is not completely faithful to the Haskell lexical syntax
234 -- in the following respects:
236 -- * Qualified names are not handled properly
238 -- * Octal and hexadecimal numerics are not recognized as a single token
240 -- * Comments are not treated properly
241 lex :: ReadS String -- As defined by H98
242 lex s = readP_to_S L.hsLex s
244 -- | Read a string representation of a character, using Haskell
245 -- source-language escape conventions. For example:
247 -- > lexLitChar "\\nHello" = [("\\n", "Hello")]
249 lexLitChar :: ReadS String -- As defined by H98
250 lexLitChar = readP_to_S (do { (s, _) <- P.gather L.lexChar ;
252 -- There was a skipSpaces before the P.gather L.lexChar,
253 -- but that seems inconsistent with readLitChar
255 -- | Read a string representation of a character, using Haskell
256 -- source-language escape conventions, and convert it to the character
257 -- that it encodes. For example:
259 -- > readLitChar "\\nHello" = [('\n', "Hello")]
261 readLitChar :: ReadS Char -- As defined by H98
262 readLitChar = readP_to_S L.lexChar
264 -- | Reads a non-empty string of decimal digits.
265 lexDigits :: ReadS String
266 lexDigits = readP_to_S (P.munch1 isDigit)
268 ------------------------------------------------------------------------
271 lexP :: ReadPrec L.Lexeme
272 -- ^ Parse a single lexeme
275 paren :: ReadPrec a -> ReadPrec a
276 -- ^ @(paren p)@ parses \"(P0)\"
277 -- where @p@ parses \"P0\" in precedence context zero
278 paren p = do L.Punc "(" <- lexP
283 parens :: ReadPrec a -> ReadPrec a
284 -- ^ @(parens p)@ parses \"P\", \"(P0)\", \"((P0))\", etc,
285 -- where @p@ parses \"P\" in the current precedence context
286 -- and parses \"P0\" in precedence context zero
289 optional = p +++ mandatory
290 mandatory = paren optional
292 list :: ReadPrec a -> ReadPrec [a]
293 -- ^ @(list p)@ parses a list of things parsed by @p@,
294 -- using the usual square-bracket syntax.
297 ( do L.Punc "[" <- lexP
298 (listRest False +++ listNext)
305 "," | started -> listNext
313 choose :: [(String, ReadPrec a)] -> ReadPrec a
314 -- ^ Parse the specified lexeme and continue as specified.
315 -- Esp useful for nullary constructors; e.g.
316 -- @choose [(\"A\", return A), (\"B\", return B)]@
317 choose sps = foldr ((+++) . try_one) pfail sps
319 try_one (s,p) = do { L.Ident s' <- lexP ;
320 if s == s' then p else pfail }
324 %*********************************************************
326 \subsection{Simple instances of Read}
328 %*********************************************************
331 instance Read Char where
334 ( do L.Char c <- lexP
340 ( do L.String s <- lexP -- Looks for "foo"
343 readListPrecDefault -- Looks for ['f','o','o']
344 ) -- (more generous than H98 spec)
346 readList = readListDefault
348 instance Read Bool where
351 ( do L.Ident s <- lexP
353 "True" -> return True
354 "False" -> return False
358 readListPrec = readListPrecDefault
359 readList = readListDefault
361 instance Read Ordering where
364 ( do L.Ident s <- lexP
372 readListPrec = readListPrecDefault
373 readList = readListDefault
377 %*********************************************************
379 \subsection{Structure instances of Read: Maybe, List etc}
381 %*********************************************************
383 For structured instances of Read we start using the precedences. The
384 idea is then that 'parens (prec k p)' will fail immediately when trying
385 to parse it in a context with a higher precedence level than k. But if
386 there is one parenthesis parsed, then the required precedence level
387 drops to 0 again, and parsing inside p may succeed.
389 'appPrec' is just the precedence level of function application. So,
390 if we are parsing function application, we'd better require the
391 precedence level to be at least 'appPrec'. Otherwise, we have to put
392 parentheses around it.
394 'step' is used to increase the precedence levels inside a
395 parser, and can be used to express left- or right- associativity. For
396 example, % is defined to be left associative, so we only increase
397 precedence on the right hand side.
399 Note how step is used in for example the Maybe parser to increase the
400 precedence beyond appPrec, so that basically only literals and
401 parenthesis-like objects such as (...) and [...] can be an argument to
405 instance Read a => Read (Maybe a) where
408 (do L.Ident "Nothing" <- lexP
412 do L.Ident "Just" <- lexP
417 readListPrec = readListPrecDefault
418 readList = readListDefault
420 instance Read a => Read [a] where
421 readPrec = readListPrec
422 readListPrec = readListPrecDefault
423 readList = readListDefault
425 instance (Ix a, Read a, Read b) => Read (Array a b) where
426 readPrec = parens $ prec appPrec $
427 do L.Ident "array" <- lexP
428 theBounds <- step readPrec
429 vals <- step readPrec
430 return (array theBounds vals)
432 readListPrec = readListPrecDefault
433 readList = readListDefault
435 instance Read L.Lexeme where
437 readListPrec = readListPrecDefault
438 readList = readListDefault
442 %*********************************************************
444 \subsection{Numeric instances of Read}
446 %*********************************************************
449 readNumber :: Num a => (L.Lexeme -> Maybe a) -> ReadPrec a
450 -- Read a signed number
455 L.Symbol "-" -> do n <- readNumber convert
458 _ -> case convert x of
463 convertInt :: Num a => L.Lexeme -> Maybe a
464 convertInt (L.Int i) = Just (fromInteger i)
465 convertInt _ = Nothing
467 convertFrac :: Fractional a => L.Lexeme -> Maybe a
468 convertFrac (L.Int i) = Just (fromInteger i)
469 convertFrac (L.Rat r) = Just (fromRational r)
470 convertFrac _ = Nothing
472 instance Read Int where
473 readPrec = readNumber convertInt
474 readListPrec = readListPrecDefault
475 readList = readListDefault
477 instance Read Integer where
478 readPrec = readNumber convertInt
479 readListPrec = readListPrecDefault
480 readList = readListDefault
482 instance Read Float where
483 readPrec = readNumber convertFrac
484 readListPrec = readListPrecDefault
485 readList = readListDefault
487 instance Read Double where
488 readPrec = readNumber convertFrac
489 readListPrec = readListPrecDefault
490 readList = readListDefault
492 instance (Integral a, Read a) => Read (Ratio a) where
496 ( do x <- step readPrec
503 readListPrec = readListPrecDefault
504 readList = readListDefault
508 %*********************************************************
510 Tuple instances of Read, up to size 15
512 %*********************************************************
515 instance Read () where
523 readListPrec = readListPrecDefault
524 readList = readListDefault
526 instance (Read a, Read b) => Read (a,b) where
527 readPrec = wrap_tup read_tup2
528 readListPrec = readListPrecDefault
529 readList = readListDefault
531 wrap_tup :: ReadPrec a -> ReadPrec a
532 wrap_tup p = parens (paren p)
534 read_comma :: ReadPrec ()
535 read_comma = do { L.Punc "," <- lexP; return () }
537 read_tup2 :: (Read a, Read b) => ReadPrec (a,b)
538 -- Reads "a , b" no parens!
539 read_tup2 = do x <- readPrec
544 read_tup4 :: (Read a, Read b, Read c, Read d) => ReadPrec (a,b,c,d)
545 read_tup4 = do (a,b) <- read_tup2
551 read_tup8 :: (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
552 => ReadPrec (a,b,c,d,e,f,g,h)
553 read_tup8 = do (a,b,c,d) <- read_tup4
555 (e,f,g,h) <- read_tup4
556 return (a,b,c,d,e,f,g,h)
559 instance (Read a, Read b, Read c) => Read (a, b, c) where
560 readPrec = wrap_tup (do { (a,b) <- read_tup2; read_comma
563 readListPrec = readListPrecDefault
564 readList = readListDefault
566 instance (Read a, Read b, Read c, Read d) => Read (a, b, c, d) where
567 readPrec = wrap_tup read_tup4
568 readListPrec = readListPrecDefault
569 readList = readListDefault
571 instance (Read a, Read b, Read c, Read d, Read e) => Read (a, b, c, d, e) where
572 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
574 ; return (a,b,c,d,e) })
575 readListPrec = readListPrecDefault
576 readList = readListDefault
578 instance (Read a, Read b, Read c, Read d, Read e, Read f)
579 => Read (a, b, c, d, e, f) where
580 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
582 ; return (a,b,c,d,e,f) })
583 readListPrec = readListPrecDefault
584 readList = readListDefault
586 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g)
587 => Read (a, b, c, d, e, f, g) where
588 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
589 ; (e,f) <- read_tup2; read_comma
591 ; return (a,b,c,d,e,f,g) })
592 readListPrec = readListPrecDefault
593 readList = readListDefault
595 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
596 => Read (a, b, c, d, e, f, g, h) where
597 readPrec = wrap_tup read_tup8
598 readListPrec = readListPrecDefault
599 readList = readListDefault
601 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
603 => Read (a, b, c, d, e, f, g, h, i) where
604 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
606 ; return (a,b,c,d,e,f,g,h,i) })
607 readListPrec = readListPrecDefault
608 readList = readListDefault
610 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
612 => Read (a, b, c, d, e, f, g, h, i, j) where
613 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
615 ; return (a,b,c,d,e,f,g,h,i,j) })
616 readListPrec = readListPrecDefault
617 readList = readListDefault
619 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
620 Read i, Read j, Read k)
621 => Read (a, b, c, d, e, f, g, h, i, j, k) where
622 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
623 ; (i,j) <- read_tup2; read_comma
625 ; return (a,b,c,d,e,f,g,h,i,j,k) })
626 readListPrec = readListPrecDefault
627 readList = readListDefault
629 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
630 Read i, Read j, Read k, Read l)
631 => Read (a, b, c, d, e, f, g, h, i, j, k, l) where
632 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
633 ; (i,j,k,l) <- read_tup4
634 ; return (a,b,c,d,e,f,g,h,i,j,k,l) })
635 readListPrec = readListPrecDefault
636 readList = readListDefault
638 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
639 Read i, Read j, Read k, Read l, Read m)
640 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m) where
641 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
642 ; (i,j,k,l) <- read_tup4; read_comma
644 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m) })
645 readListPrec = readListPrecDefault
646 readList = readListDefault
648 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
649 Read i, Read j, Read k, Read l, Read m, Read n)
650 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n) where
651 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
652 ; (i,j,k,l) <- read_tup4; read_comma
654 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n) })
655 readListPrec = readListPrecDefault
656 readList = readListDefault
658 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
659 Read i, Read j, Read k, Read l, Read m, Read n, Read o)
660 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) where
661 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
662 ; (i,j,k,l) <- read_tup4; read_comma
663 ; (m,n) <- read_tup2; read_comma
665 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) })
666 readListPrec = readListPrecDefault
667 readList = readListDefault
671 -- XXX Can this be removed?
673 readp :: Read a => ReadP a
674 readp = readPrec_to_P readPrec minPrec