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 -- We match both Ident and Symbol because the constructor
318 -- might be an operator eg (:=:)
319 choose sps = foldr ((+++) . try_one) pfail sps
321 try_one (s,p) = do { token <- lexP ;
323 L.Ident s' | s==s' -> p
324 L.Symbol s' | s==s' -> p
329 %*********************************************************
331 \subsection{Simple instances of Read}
333 %*********************************************************
336 instance Read Char where
339 ( do L.Char c <- lexP
345 ( do L.String s <- lexP -- Looks for "foo"
348 readListPrecDefault -- Looks for ['f','o','o']
349 ) -- (more generous than H98 spec)
351 readList = readListDefault
353 instance Read Bool where
356 ( do L.Ident s <- lexP
358 "True" -> return True
359 "False" -> return False
363 readListPrec = readListPrecDefault
364 readList = readListDefault
366 instance Read Ordering where
369 ( do L.Ident s <- lexP
377 readListPrec = readListPrecDefault
378 readList = readListDefault
382 %*********************************************************
384 \subsection{Structure instances of Read: Maybe, List etc}
386 %*********************************************************
388 For structured instances of Read we start using the precedences. The
389 idea is then that 'parens (prec k p)' will fail immediately when trying
390 to parse it in a context with a higher precedence level than k. But if
391 there is one parenthesis parsed, then the required precedence level
392 drops to 0 again, and parsing inside p may succeed.
394 'appPrec' is just the precedence level of function application. So,
395 if we are parsing function application, we'd better require the
396 precedence level to be at least 'appPrec'. Otherwise, we have to put
397 parentheses around it.
399 'step' is used to increase the precedence levels inside a
400 parser, and can be used to express left- or right- associativity. For
401 example, % is defined to be left associative, so we only increase
402 precedence on the right hand side.
404 Note how step is used in for example the Maybe parser to increase the
405 precedence beyond appPrec, so that basically only literals and
406 parenthesis-like objects such as (...) and [...] can be an argument to
410 instance Read a => Read (Maybe a) where
413 (do L.Ident "Nothing" <- lexP
417 do L.Ident "Just" <- lexP
422 readListPrec = readListPrecDefault
423 readList = readListDefault
425 instance Read a => Read [a] where
426 readPrec = readListPrec
427 readListPrec = readListPrecDefault
428 readList = readListDefault
430 instance (Ix a, Read a, Read b) => Read (Array a b) where
431 readPrec = parens $ prec appPrec $
432 do L.Ident "array" <- lexP
433 theBounds <- step readPrec
434 vals <- step readPrec
435 return (array theBounds vals)
437 readListPrec = readListPrecDefault
438 readList = readListDefault
440 instance Read L.Lexeme where
442 readListPrec = readListPrecDefault
443 readList = readListDefault
447 %*********************************************************
449 \subsection{Numeric instances of Read}
451 %*********************************************************
454 readNumber :: Num a => (L.Lexeme -> ReadPrec a) -> ReadPrec a
455 -- Read a signed number
460 L.Symbol "-" -> do y <- lexP
468 convertInt :: Num a => L.Lexeme -> ReadPrec a
469 convertInt (L.Int i) = return (fromInteger i)
472 convertFrac :: Fractional a => L.Lexeme -> ReadPrec a
473 convertFrac (L.Int i) = return (fromInteger i)
474 convertFrac (L.Rat r) = return (fromRational r)
475 convertFrac _ = pfail
477 instance Read Int where
478 readPrec = readNumber convertInt
479 readListPrec = readListPrecDefault
480 readList = readListDefault
482 instance Read Integer where
483 readPrec = readNumber convertInt
484 readListPrec = readListPrecDefault
485 readList = readListDefault
487 instance Read Float where
488 readPrec = readNumber convertFrac
489 readListPrec = readListPrecDefault
490 readList = readListDefault
492 instance Read Double where
493 readPrec = readNumber convertFrac
494 readListPrec = readListPrecDefault
495 readList = readListDefault
497 instance (Integral a, Read a) => Read (Ratio a) where
501 ( do x <- step readPrec
508 readListPrec = readListPrecDefault
509 readList = readListDefault
513 %*********************************************************
515 Tuple instances of Read, up to size 15
517 %*********************************************************
520 instance Read () where
528 readListPrec = readListPrecDefault
529 readList = readListDefault
531 instance (Read a, Read b) => Read (a,b) where
532 readPrec = wrap_tup read_tup2
533 readListPrec = readListPrecDefault
534 readList = readListDefault
536 wrap_tup :: ReadPrec a -> ReadPrec a
537 wrap_tup p = parens (paren p)
539 read_comma :: ReadPrec ()
540 read_comma = do { L.Punc "," <- lexP; return () }
542 read_tup2 :: (Read a, Read b) => ReadPrec (a,b)
543 -- Reads "a , b" no parens!
544 read_tup2 = do x <- readPrec
549 read_tup4 :: (Read a, Read b, Read c, Read d) => ReadPrec (a,b,c,d)
550 read_tup4 = do (a,b) <- read_tup2
556 read_tup8 :: (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
557 => ReadPrec (a,b,c,d,e,f,g,h)
558 read_tup8 = do (a,b,c,d) <- read_tup4
560 (e,f,g,h) <- read_tup4
561 return (a,b,c,d,e,f,g,h)
564 instance (Read a, Read b, Read c) => Read (a, b, c) where
565 readPrec = wrap_tup (do { (a,b) <- read_tup2; read_comma
568 readListPrec = readListPrecDefault
569 readList = readListDefault
571 instance (Read a, Read b, Read c, Read d) => Read (a, b, c, d) where
572 readPrec = wrap_tup read_tup4
573 readListPrec = readListPrecDefault
574 readList = readListDefault
576 instance (Read a, Read b, Read c, Read d, Read e) => Read (a, b, c, d, e) where
577 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
579 ; return (a,b,c,d,e) })
580 readListPrec = readListPrecDefault
581 readList = readListDefault
583 instance (Read a, Read b, Read c, Read d, Read e, Read f)
584 => Read (a, b, c, d, e, f) where
585 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
587 ; return (a,b,c,d,e,f) })
588 readListPrec = readListPrecDefault
589 readList = readListDefault
591 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g)
592 => Read (a, b, c, d, e, f, g) where
593 readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
594 ; (e,f) <- read_tup2; read_comma
596 ; return (a,b,c,d,e,f,g) })
597 readListPrec = readListPrecDefault
598 readList = readListDefault
600 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
601 => Read (a, b, c, d, e, f, g, h) where
602 readPrec = wrap_tup read_tup8
603 readListPrec = readListPrecDefault
604 readList = readListDefault
606 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
608 => Read (a, b, c, d, e, f, g, h, i) where
609 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
611 ; return (a,b,c,d,e,f,g,h,i) })
612 readListPrec = readListPrecDefault
613 readList = readListDefault
615 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
617 => Read (a, b, c, d, e, f, g, h, i, j) where
618 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
620 ; return (a,b,c,d,e,f,g,h,i,j) })
621 readListPrec = readListPrecDefault
622 readList = readListDefault
624 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
625 Read i, Read j, Read k)
626 => Read (a, b, c, d, e, f, g, h, i, j, k) where
627 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
628 ; (i,j) <- read_tup2; read_comma
630 ; return (a,b,c,d,e,f,g,h,i,j,k) })
631 readListPrec = readListPrecDefault
632 readList = readListDefault
634 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
635 Read i, Read j, Read k, Read l)
636 => Read (a, b, c, d, e, f, g, h, i, j, k, l) where
637 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
638 ; (i,j,k,l) <- read_tup4
639 ; return (a,b,c,d,e,f,g,h,i,j,k,l) })
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 i, Read j, Read k, Read l, Read m)
645 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m) 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
649 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m) })
650 readListPrec = readListPrecDefault
651 readList = readListDefault
653 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
654 Read i, Read j, Read k, Read l, Read m, Read n)
655 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n) where
656 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
657 ; (i,j,k,l) <- read_tup4; read_comma
659 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n) })
660 readListPrec = readListPrecDefault
661 readList = readListDefault
663 instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h,
664 Read i, Read j, Read k, Read l, Read m, Read n, Read o)
665 => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) where
666 readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
667 ; (i,j,k,l) <- read_tup4; read_comma
668 ; (m,n) <- read_tup2; read_comma
670 ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) })
671 readListPrec = readListPrecDefault
672 readList = readListDefault
676 -- XXX Can this be removed?
678 readp :: Read a => ReadP a
679 readp = readPrec_to_P readPrec minPrec