|
Text.Read | Portability | non-portable (uses Text.ParserCombinators.ReadP) | Stability | provisional | Maintainer | libraries@haskell.org |
|
|
|
|
|
Description |
Converting strings to values.
The Text.Read library is the canonical library to import for
Read-class facilities. For GHC only, it offers an extended and much
improved Read class, which constitutes a proposed alternative to the
Haskell 98 Read. In particular, writing parsers is easier, and
the parsers are much more efficient.
|
|
Synopsis |
|
|
|
|
The Read class
|
|
|
Parsing of Strings, producing values.
Minimal complete definition: readsPrec (or, for GHC only, readPrec)
Derived instances of Read make the following assumptions, which
derived instances of Text.Show.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 98 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
| | Methods | | :: Int | the operator precedence of the enclosing
context (a number from 0 to 11).
Function application has precedence 10.
| -> ReadS a | |
| | | | | | |
| | Instances | |
|
|
|
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 98 functions
|
|
|
equivalent to readsPrec with a precedence of 0.
|
|
|
The read function reads input from a string, which must be
completely consumed by the input process.
|
|
|
readParen True p parses what p parses, but surrounded with
parentheses.
readParen False p parses what p parses, but optionally
surrounded with parentheses.
|
|
|
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 |
|
|
Haskell lexemes.
| Constructors | Char Char | Character literal
| String String | String literal, with escapes interpreted
| Punc String | Punctuation or reserved symbol, e.g. (, ::
| Ident String | Haskell identifier, e.g. foo, Baz
| Symbol String | Haskell symbol, e.g. >>, :%
| Int Integer | Integer literal
| Rat Rational | Floating point literal
| EOF | |
| Instances | |
|
|
|
Parse a single lexeme
|
|
|
(parens p) parses "P", "(P0)", "((P0))", etc,
where p parses "P" in the current precedence context
and parses "P0" in precedence context zero
|
|
|
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.
|
|
|
A possible replacement definition for the readListPrec method,
defined using readPrec (GHC only).
|
|
Produced by Haddock version 2.0.0.0 |