Text.Read

Copyright	(c) The University of Glasgow 2001
License	BSD-style (see the file libraries/base/LICENSE)
Maintainer	[email protected]
Stability	provisional
Portability	non-portable (uses Text.ParserCombinators.ReadP)
Safe Haskell	Trustworthy
Language	Haskell2010

The Read class

class Read a where Source

Parsing of Strings, producing values.

Derived instances of Read make the following assumptions, which derived instances of Show obey:

• If the constructor is defined to be an infix operator, then the derived Read instance will parse only infix applications of the constructor (not the prefix form).
• Associativity is not used to reduce the occurrence of parentheses, although precedence may be.
• If the constructor is defined using record syntax, the derived Read will parse only the record-syntax form, and furthermore, the fields must be given in the same order as the original declaration.
• The derived Read instance allows arbitrary Haskell whitespace between tokens of the input string. Extra parentheses are also allowed.

For example, given the declarations

infixr 5 :^:
data Tree a =  Leaf a  |  Tree a :^: Tree a

the derived instance of Read in Haskell 2010 is equivalent to

instance (Read a) => Read (Tree a) where

        readsPrec d r =  readParen (d > app_prec)
                         (\r -> [(Leaf m,t) |
                                 ("Leaf",s) <- lex r,
                                 (m,t) <- readsPrec (app_prec+1) s]) r

                      ++ readParen (d > up_prec)
                         (\r -> [(u:^:v,w) |
                                 (u,s) <- readsPrec (up_prec+1) r,
                                 (":^:",t) <- lex s,
                                 (v,w) <- readsPrec (up_prec+1) t]) r

          where app_prec = 10
                up_prec = 5

Note that right-associativity of :^: is unused.

The derived instance in GHC is equivalent to

instance (Read a) => Read (Tree a) where

        readPrec = parens $ (prec app_prec $ do
                                 Ident "Leaf" <- lexP
                                 m <- step readPrec
                                 return (Leaf m))

                     +++ (prec up_prec $ do
                                 u <- step readPrec
                                 Symbol ":^:" <- lexP
                                 v <- step readPrec
                                 return (u :^: v))

          where app_prec = 10
                up_prec = 5

        readListPrec = readListPrecDefault

type ReadS a = String -> [(a, String)] Source

A parser for a type a, represented as a function that takes a String and returns a list of possible parses as (a,String) pairs.

Note that this kind of backtracking parser is very inefficient; reading a large structure may be quite slow (cf ReadP).

Haskell 2010 functions

reads :: Read a => ReadS a Source

equivalent to readsPrec with a precedence of 0.

read :: Read a => String -> a Source

The read function reads input from a string, which must be completely consumed by the input process.

readParen :: Bool -> ReadS a -> ReadS a Source

readParen True p parses what p parses, but surrounded with parentheses.

readParen False p parses what p parses, but optionally surrounded with parentheses.

lex :: ReadS String Source

The lex function reads a single lexeme from the input, discarding initial white space, and returning the characters that constitute the lexeme. If the input string contains only white space, lex returns a single successful `lexeme' consisting of the empty string. (Thus lex "" = [("","")].) If there is no legal lexeme at the beginning of the input string, lex fails (i.e. returns []).

This lexer is not completely faithful to the Haskell lexical syntax in the following respects:

• Qualified names are not handled properly
• Octal and hexadecimal numerics are not recognized as a single token
• Comments are not treated properly

New parsing functions

module Text.ParserCombinators.ReadPrec

data Lexeme Source

lexP :: ReadPrec Lexeme Source

Parse a single lexeme

parens :: ReadPrec a -> ReadPrec a Source

(parens p) parses "P", "(P0)", "((P0))", etc, where p parses "P" in the current precedence context and parses "P0" in precedence context zero

readListDefault :: Read a => ReadS [a] Source

A possible replacement definition for the readList method (GHC only). This is only needed for GHC, and even then only for Read instances where readListPrec isn't defined as readListPrecDefault.

readListPrecDefault :: Read a => ReadPrec [a] Source

A possible replacement definition for the readListPrec method, defined using readPrec (GHC only).

readEither :: Read a => String -> Either String a Source

Parse a string using the Read instance. Succeeds if there is exactly one valid result. A Left value indicates a parse error.

Since: 4.6.0.0

readMaybe :: Read a => String -> Maybe a Source

Parse a string using the Read instance. Succeeds if there is exactly one valid result.

Since: 4.6.0.0