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