2 {-# OPTIONS -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 -----------------------------------------------------------------------------
21 , ReadS -- :: *; = String -> [(a,String)]
24 , reads -- :: Read a => ReadS a
25 , readp -- :: Read a => ReadP a
26 , readEither -- :: Read a => String -> Either String a
27 , read -- :: Read a => String -> a
30 , lex -- :: ReadS String
31 , lexLitChar -- :: ReadS String
32 , readLitChar -- :: ReadS Char
33 , lexDigits -- :: ReadS String
36 , lexP -- :: ReadPrec Lexeme
37 , paren -- :: ReadPrec a -> ReadPrec a
38 , parens -- :: ReadPrec a -> ReadPrec a
39 , list -- :: ReadPrec a -> ReadPrec [a]
40 , choose -- :: [(String, ReadPrec a)] -> ReadPrec a
41 , readListDefault, readListPrecDefault
48 import qualified Text.ParserCombinators.ReadP as P
50 import Text.ParserCombinators.ReadP
56 import qualified Text.Read.Lex as L
57 -- Lex exports 'lex', which is also defined here,
58 -- hence the qualified import.
59 -- We can't import *anything* unqualified, because that
62 import Text.ParserCombinators.ReadPrec
67 import {-# SOURCE #-} GHC.Err ( error )
69 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' is equivalent to
138 -- > instance (Read a) => Read (Tree a) where
140 -- > readsPrec d r = readParen (d > up_prec)
141 -- > (\r -> [(u:^:v,w) |
142 -- > (u,s) <- readsPrec (up_prec+1) r,
143 -- > (":^:",t) <- lex s,
144 -- > (v,w) <- readsPrec (up_prec+1) t]) r
146 -- > ++ readParen (d > app_prec)
147 -- > (\r -> [(Leaf m,t) |
148 -- > ("Leaf",s) <- lex r,
149 -- > (m,t) <- readsPrec (app_prec+1) s]) r
151 -- > where up_prec = 5
154 -- Note that right-associativity of @:^:@ is unused.
157 -- | attempts to parse a value from the front of the string, returning
158 -- a list of (parsed value, remaining string) pairs. If there is no
159 -- successful parse, the returned list is empty.
161 -- Derived instances of 'Read' and 'Text.Show.Show' satisfy the following:
163 -- * @(x,\"\")@ is an element of
164 -- @('readsPrec' d ('Text.Show.showsPrec' d x \"\"))@.
166 -- That is, 'readsPrec' parses the string produced by
167 -- 'Text.Show.showsPrec', and delivers the value that
168 -- 'Text.Show.showsPrec' started with.
170 readsPrec :: Int -- ^ the operator precedence of the enclosing
171 -- context (a number from @0@ to @11@).
172 -- Function application has precedence @10@.
175 -- | The method 'readList' is provided to allow the programmer to
176 -- give a specialised way of parsing lists of values.
177 -- For example, this is used by the predefined 'Read' instance of
178 -- the 'Char' type, where values of type 'String' should be are
179 -- expected to use double quotes, rather than square brackets.
180 readList :: ReadS [a]
182 -- | Proposed replacement for 'readsPrec' using new-style parsers (GHC only).
183 readPrec :: ReadPrec a
185 -- | Proposed replacement for 'readList' using new-style parsers (GHC only).
186 readListPrec :: ReadPrec [a]
188 -- default definitions
189 readsPrec = readPrec_to_S readPrec
190 readList = readPrec_to_S (list readPrec) 0
191 readPrec = readS_to_Prec readsPrec
192 readListPrec = readS_to_Prec (\_ -> readList)
194 readListDefault :: Read a => ReadS [a]
195 -- ^ Use this to define the 'readList' method, if you don't want a special
196 -- case (GHC only; for other systems the default suffices).
197 readListDefault = readPrec_to_S readListPrec 0
199 readListPrecDefault :: Read a => ReadPrec [a]
200 -- ^ Use this to define the 'readListPrec' method, if you
201 -- don't want a special case (GHC only).
202 readListPrecDefault = list readPrec
204 ------------------------------------------------------------------------
207 -- | equivalent to 'readsPrec' with a precedence of 0.
208 reads :: Read a => ReadS a
209 reads = readsPrec minPrec
211 readp :: Read a => ReadP a
212 readp = readPrec_to_P readPrec minPrec
214 readEither :: Read a => String -> Either String a
216 case [ x | (x,"") <- readPrec_to_S read' minPrec s ] of
218 [] -> Left "Prelude.read: no parse"
219 _ -> Left "Prelude.read: ambiguous parse"
226 -- | The 'read' function reads input from a string, which must be
227 -- completely consumed by the input process.
228 read :: Read a => String -> a
229 read s = either error id (readEither s)
231 ------------------------------------------------------------------------
234 -- | The 'lex' function reads a single lexeme from the input, discarding
235 -- initial white space, and returning the characters that constitute the
236 -- lexeme. If the input string contains only white space, 'lex' returns a
237 -- single successful \`lexeme\' consisting of the empty string. (Thus
238 -- @'lex' \"\" = [(\"\",\"\")]@.) If there is no legal lexeme at the
239 -- beginning of the input string, 'lex' fails (i.e. returns @[]@).
241 -- This lexer is not completely faithful to the Haskell lexical syntax
242 -- in the following respects:
244 -- * Qualified names are not handled properly
246 -- * Octal and hexadecimal numerics are not recognized as a single token
248 -- * Comments are not treated properly
249 lex :: ReadS String -- As defined by H98
250 lex s = readP_to_S L.hsLex s
252 -- | Read a string representation of a character, using Haskell
253 -- source-language escape conventions. For example:
255 -- > lexLitChar "\\nHello" = [("\\n", "Hello")]
257 lexLitChar :: ReadS String -- As defined by H98
258 lexLitChar = readP_to_S (do { (s, _) <- P.gather L.lexChar ;
260 -- There was a skipSpaces before the P.gather L.lexChar,
261 -- but that seems inconsistent with readLitChar
263 -- | Read a string representation of a character, using Haskell
264 -- source-language escape conventions, and convert it to the character
265 -- that it encodes. For example:
267 -- > readLitChar "\\nHello" = [('\n', "Hello")]
269 readLitChar :: ReadS Char -- As defined by H98
270 readLitChar = readP_to_S L.lexChar
272 -- | Reads a non-empty string of decimal digits.
273 lexDigits :: ReadS String
274 lexDigits = readP_to_S (P.munch1 isDigit)
276 ------------------------------------------------------------------------
279 lexP :: ReadPrec L.Lexeme
280 -- ^ Parse a single lexeme
283 paren :: ReadPrec a -> ReadPrec a
284 -- ^ @(paren p)@ parses \"(P0)\"
285 -- where @p@ parses \"P0\" in precedence context zero
286 paren p = do L.Punc "(" <- lexP
291 parens :: ReadPrec a -> ReadPrec a
292 -- ^ @(parens p)@ parses \"P\", \"(P0)\", \"((P0))\", etc,
293 -- where @p@ parses \"P\" in the current precedence context
294 -- parses \"P0\" in precedence context zero
297 optional = p +++ mandatory
298 mandatory = paren optional
300 list :: ReadPrec a -> ReadPrec [a]
301 -- ^ @(list p)@ parses a list of things parsed by @p@,
302 -- using the usual square-bracket syntax.
305 ( do L.Punc "[" <- lexP
306 (listRest False +++ listNext)
313 "," | started -> listNext
321 choose :: [(String, ReadPrec a)] -> ReadPrec a
322 -- ^ Parse the specified lexeme and continue as specified.
323 -- Esp useful for nullary constructors; e.g.
324 -- @choose [(\"A\", return A), (\"B\", return B)]@
325 choose sps = foldr ((+++) . try_one) pfail sps
327 try_one (s,p) = do { L.Ident s' <- lexP ;
328 if s == s' then p else pfail }
332 %*********************************************************
334 \subsection{Simple instances of Read}
336 %*********************************************************
339 instance Read Char where
342 ( do L.Char c <- lexP
348 ( do L.String s <- lexP -- Looks for "foo"
351 readListPrecDefault -- Looks for ['f','o','o']
352 ) -- (more generous than H98 spec)
354 readList = readListDefault
356 instance Read Bool where
359 ( do L.Ident s <- lexP
361 "True" -> return True
362 "False" -> return False
366 readListPrec = readListPrecDefault
367 readList = readListDefault
369 instance Read Ordering where
372 ( do L.Ident s <- lexP
380 readListPrec = readListPrecDefault
381 readList = readListDefault
385 %*********************************************************
387 \subsection{Structure instances of Read: Maybe, List etc}
389 %*********************************************************
391 For structured instances of Read we start using the precedences. The
392 idea is then that 'parens (prec k p)' will fail immediately when trying
393 to parse it in a context with a higher precedence level than k. But if
394 there is one parenthesis parsed, then the required precedence level
395 drops to 0 again, and parsing inside p may succeed.
397 'appPrec' is just the precedence level of function application. So,
398 if we are parsing function application, we'd better require the
399 precedence level to be at least 'appPrec'. Otherwise, we have to put
400 parentheses around it.
402 'step' is used to increase the precedence levels inside a
403 parser, and can be used to express left- or right- associativity. For
404 example, % is defined to be left associative, so we only increase
405 precedence on the right hand side.
407 Note how step is used in for example the Maybe parser to increase the
408 precedence beyond appPrec, so that basically only literals and
409 parenthesis-like objects such as (...) and [...] can be an argument to
413 instance Read a => Read (Maybe a) where
416 (do L.Ident "Nothing" <- lexP
420 do L.Ident "Just" <- lexP
425 readListPrec = readListPrecDefault
426 readList = readListDefault
428 instance (Read a, Read b) => Read (Either a b) where
432 ( do L.Ident "Left" <- lexP
436 do L.Ident "Right" <- lexP
442 readListPrec = readListPrecDefault
443 readList = readListDefault
445 instance Read a => Read [a] where
446 readPrec = readListPrec
447 readListPrec = readListPrecDefault
448 readList = readListDefault
450 instance (Ix a, Read a, Read b) => Read (Array a b) where
451 readPrec = parens $ prec appPrec $
452 do L.Ident "array" <- lexP
453 bounds <- step readPrec
454 vals <- step readPrec
455 return (array bounds vals)
457 readListPrec = readListPrecDefault
458 readList = readListDefault
460 instance Read L.Lexeme where
462 readListPrec = readListPrecDefault
463 readList = readListDefault
467 %*********************************************************
469 \subsection{Numeric instances of Read}
471 %*********************************************************
474 readNumber :: Num a => (L.Lexeme -> Maybe a) -> ReadPrec a
475 -- Read a signed number
480 L.Symbol "-" -> do n <- readNumber convert
483 _ -> case convert x of
488 convertInt :: Num a => L.Lexeme -> Maybe a
489 convertInt (L.Int i) = Just (fromInteger i)
490 convertInt _ = Nothing
492 convertFrac :: Fractional a => L.Lexeme -> Maybe a
493 convertFrac (L.Int i) = Just (fromInteger i)
494 convertFrac (L.Rat r) = Just (fromRational r)
495 convertFrac _ = Nothing
497 instance Read Int where
498 readPrec = readNumber convertInt
499 readListPrec = readListPrecDefault
500 readList = readListDefault
502 instance Read Integer where
503 readPrec = readNumber convertInt
504 readListPrec = readListPrecDefault
505 readList = readListDefault
507 instance Read Float where
508 readPrec = readNumber convertFrac
509 readListPrec = readListPrecDefault
510 readList = readListDefault
512 instance Read Double where
513 readPrec = readNumber convertFrac
514 readListPrec = readListPrecDefault
515 readList = readListDefault
517 instance (Integral a, Read a) => Read (Ratio a) where
521 ( do x <- step readPrec
528 readListPrec = readListPrecDefault
529 readList = readListDefault
533 %*********************************************************
535 \subsection{Tuple instances of Read}
537 %*********************************************************
540 instance Read () where
548 readListPrec = readListPrecDefault
549 readList = readListDefault
551 instance (Read a, Read b) => Read (a,b) where
562 readListPrec = readListPrecDefault
563 readList = readListDefault
566 instance (Read a, Read b, Read c) => Read (a, b, c) where
579 readListPrec = readListPrecDefault
580 readList = readListDefault
582 instance (Read a, Read b, Read c, Read d) => Read (a, b, c, d) where
597 readListPrec = readListPrecDefault
598 readList = readListDefault
600 instance (Read a, Read b, Read c, Read d, Read e) => Read (a, b, c, d, e) where
617 readListPrec = readListPrecDefault
618 readList = readListDefault