base-4.6.0.1: Basic libraries

Portability | non-portable (uses Text.ParserCombinators.ReadP)
Stability | provisional
Maintainer | libraries@haskell.org
Safe Haskell | Trustworthy

Text.Read

Contents

- The `Read` class
- Haskell 98 functions
- New parsing functions

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

- class Read a where
  - readsPrec :: Int -> ReadS a
  - readList :: ReadS [a]
  - readPrec :: ReadPrec a
  - readListPrec :: ReadPrec [a]
- type ReadS a = String -> [(a, String)]
- reads :: Read a => ReadS a
- read :: Read a => String -> a
- readParen :: Bool -> ReadS a -> ReadS a
- lex :: ReadS String
- module Text.ParserCombinators.ReadPrec
- data Lexeme
  - = Char Char
  - | String String
  - | Punc String
  - | Ident String
  - | Symbol String
  - | Number Number
  - | EOF
- lexP :: ReadPrec Lexeme
- parens :: ReadPrec a -> ReadPrec a
- readListDefault :: Read a => ReadS [a]
- readListPrecDefault :: Read a => ReadPrec [a]
- readEither :: Read a => String -> Either String a
- readMaybe :: Read a => String -> Maybe a

# The `Read` class

class Read a where

Parsing of `String`s, producing values.

Minimal complete definition: `readsPrec` (or, for GHC only, `readPrec`)

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 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

readsPrec

Arguments

:: Int | the operator precedence of the enclosing context (a number from `0` to `11`). Function application has precedence `10`.
-> ReadS a |

attempts to parse a value from the front of the string, returning a list of (parsed value, remaining string) pairs. If there is no successful parse, the returned list is empty.

Derived instances of `Read` and `Show` satisfy the following:

- `(x,"")` is an element of `(`readsPrec` d (`showsPrec` d x ""))`.

That is, `readsPrec` parses the string produced by `showsPrec`, and delivers the value that `showsPrec` started with.

readList :: ReadS [a]

The method `readList` is provided to allow the programmer to give a specialised way of parsing lists of values. For example, this is used by the predefined `Read` instance of the `Char` type, where values of type `String` should be are expected to use double quotes, rather than square brackets.

readPrec :: ReadPrec a

Proposed replacement for `readsPrec` using new-style parsers (GHC only).

readListPrec :: ReadPrec [a]

Proposed replacement for `readList` using new-style parsers (GHC only). The default definition uses `readList`. Instances that define `readPrec` should also define `readListPrec` as `readListPrecDefault`.

Instances

Read Bool |
Read Char |
Read Double |
Read Float |
Read Int |
Read Int8 |
Read Int16 |
Read Int32 |
Read Int64 |
Read Integer |
Read Ordering |
Read Word |
Read Word8 |
Read Word16 |
Read Word32 |
Read Word64 |
Read () |
Read Lexeme |
Read IOMode |
Read SeekMode |
Read CUIntMax |
Read CIntMax |
Read CUIntPtr |
Read CIntPtr |
Read CSUSeconds |
Read CUSeconds |
Read CTime |
Read CClock |
Read CSigAtomic |
Read CWchar |
Read CSize |
Read CPtrdiff |
Read CDouble |
Read CFloat |
Read CULLong |
Read CLLong |
Read CULong |
Read CLong |
Read CUInt |
Read CInt |
Read CUShort |
Read CShort |
Read CUChar |
Read CSChar |
Read CChar |
Read GeneralCategory |
Read Associativity |
Read Fixity |
Read Arity |
Read IntPtr |
Read WordPtr |
Read Any |
Read All |
Read NewlineMode |
Read Newline |
Read BufferMode |
Read ExitCode |
Read Fd |
Read CRLim |
Read CTcflag |
Read CSpeed |
Read CCc |
Read CUid |
Read CNlink |
Read CGid |
Read CSsize |
Read CPid |
Read COff |
Read CMode |
Read CIno |
Read CDev |
Read GCStats |
Read Version |
Read a => Read [a] |
(Integral a, Read a) => Read (Ratio a) |
Read a => Read (Maybe a) |
Read a => Read (Last a) |
Read a => Read (First a) |
Read a => Read (Product a) |
Read a => Read (Sum a) |
Read a => Read (Dual a) |
Read a => Read (Complex a) |
HasResolution a => Read (Fixed a) |
(Read a, Read b) => Read (Either a b) |
(Read a, Read b) => Read (a, b) |
(SingRep k a rep, Read rep, Eq rep) => Read (Sing k a) |
(Read a, Read b, Read c) => Read (a, b, c) |
(Read a, Read b, Read c, Read d) => Read (a, b, c, d) |
(Read a, Read b, Read c, Read d, Read e) => Read (a, b, c, d, e) |
(Read a, Read b, Read c, Read d, Read e, Read f) => Read (a, b, c, d, e, f) |
(Read a, Read b, Read c, Read d, Read e, Read f, Read g) => Read (a, b, c, d, e, f, g) |
(Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h) => Read (a, b, c, d, e, f, g, h) |
(Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h, Read i) => Read (a, b, c, d, e, f, g, h, i) |
(Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h, Read i, Read j) => Read (a, b, c, d, e, f, g, h, i, j) |
(Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h, Read i, Read j, Read k) => Read (a, b, c, d, e, f, g, h, i, j, k) |
(Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h, Read i, Read j, Read k, Read l) => Read (a, b, c, d, e, f, g, h, i, j, k, l) |
(Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h, Read i, Read j, Read k, Read l, Read m) => Read (a, b, c, d, e, f, g, h, i, j, k, l, m) |
(Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h, Read i, Read j, Read k, Read l, Read m, Read n) => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n) |
(Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h, Read i, Read j, Read k, Read l, Read m, Read n, Read o) => Read (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) |

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

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

reads :: Read a => ReadS a

equivalent to `readsPrec` with a precedence of 0.

read :: Read a => String -> a

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

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

``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

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

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. `>>`, `:%`
Number Number |
EOF |

Instances

Eq Lexeme |
Read Lexeme |
Show Lexeme |

lexP :: ReadPrec Lexeme

Parse a single lexeme

parens :: ReadPrec a -> ReadPrec a

`(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]

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]

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

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

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

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

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