X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=GHC%2FRead.lhs;h=e24cbe5c00c52c4904015fcb941271b2e37ae52d;hb=de2b563a240bafc20b656729d1ecde0c890d22da;hp=38a2ccf189e0f3192c2890a37cf384ca011f33e9;hpb=a7fdfabc5f9d97b2cbcd6fe80b70f0b2d1d0db95;p=ghc-base.git diff --git a/GHC/Read.lhs b/GHC/Read.lhs index 38a2ccf..e24cbe5 100644 --- a/GHC/Read.lhs +++ b/GHC/Read.lhs @@ -1,9 +1,9 @@ \begin{code} -{-# OPTIONS -fno-implicit-prelude #-} +{-# OPTIONS_GHC -fno-implicit-prelude #-} ----------------------------------------------------------------------------- -- | -- Module : GHC.Read --- Copyright : (c) The FFI Task Force, 1994-2002 +-- Copyright : (c) The University of Glasgow, 1994-2002 -- License : see libraries/base/LICENSE -- -- Maintainer : cvs-ghc@haskell.org @@ -49,6 +49,7 @@ import qualified Text.ParserCombinators.ReadP as P import Text.ParserCombinators.ReadP ( ReadP + , ReadS , readP_to_S ) @@ -64,17 +65,25 @@ import Data.Maybe import Data.Either import {-# SOURCE #-} GHC.Err ( error ) +#ifndef __HADDOCK__ +import {-# SOURCE #-} GHC.Unicode ( isDigit ) +#endif import GHC.Num import GHC.Real import GHC.Float import GHC.List -import GHC.Show -- isAlpha etc +import GHC.Show import GHC.Base import GHC.Arr \end{code} \begin{code} +-- | @'readParen' 'True' p@ parses what @p@ parses, but surrounded with +-- parentheses. +-- +-- @'readParen' 'False' p@ parses what @p@ parses, but optionally +-- surrounded with parentheses. readParen :: Bool -> ReadS a -> ReadS a -- A Haskell 98 function readParen b g = if b then mandatory else optional @@ -89,25 +98,91 @@ readParen b g = if b then mandatory else optional %********************************************************* %* * -\subsection{The @Read@ class and @ReadS@ type} +\subsection{The @Read@ class} %* * %********************************************************* \begin{code} ------------------------------------------------------------------------ --- ReadS - --- | A parser for a type @a@, represented as a function that takes a --- 'String' and returns a list of possible parses @(a,'String')@ pairs. -type ReadS a = String -> [(a,String)] - ------------------------------------------------------------------------- -- class Read +-- | 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 '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' is equivalent to +-- +-- > instance (Read a) => Read (Tree a) where +-- > +-- > readsPrec d 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 +-- > +-- > ++ readParen (d > app_prec) +-- > (\r -> [(Leaf m,t) | +-- > ("Leaf",s) <- lex r, +-- > (m,t) <- readsPrec (app_prec+1) s]) r +-- > +-- > where up_prec = 5 +-- > app_prec = 10 +-- +-- Note that right-associativity of @:^:@ is unused. + class Read a where - readsPrec :: Int -> 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 'Text.Show.Show' satisfy the following: + -- + -- * @(x,\"\")@ is an element of + -- @('readsPrec' d ('Text.Show.showsPrec' d x \"\"))@. + -- + -- That is, 'readsPrec' parses the string produced by + -- 'Text.Show.showsPrec', and delivers the value that + -- 'Text.Show.showsPrec' started with. + + readsPrec :: Int -- ^ the operator precedence of the enclosing + -- context (a number from @0@ to @11@). + -- Function application has precedence @10@. + -> 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. readList :: ReadS [a] + + -- | Proposed replacement for 'readsPrec' using new-style parsers (GHC only). readPrec :: ReadPrec a + + -- | Proposed replacement for 'readList' using new-style parsers (GHC only). readListPrec :: ReadPrec [a] -- default definitions @@ -117,18 +192,19 @@ class Read a where readListPrec = readS_to_Prec (\_ -> readList) readListDefault :: Read a => ReadS [a] --- ^ Use this to define the 'readList' method, if you --- don't want a special case +-- ^ Use this to define the 'readList' method, if you don't want a special +-- case (GHC only; for other systems the default suffices). readListDefault = readPrec_to_S readListPrec 0 readListPrecDefault :: Read a => ReadPrec [a] -- ^ Use this to define the 'readListPrec' method, if you --- don't want a special case +-- don't want a special case (GHC only). readListPrecDefault = list readPrec ------------------------------------------------------------------------ -- utility functions +-- | equivalent to 'readsPrec' with a precedence of 0. reads :: Read a => ReadS a reads = readsPrec minPrec @@ -147,24 +223,53 @@ readEither s = lift P.skipSpaces return x +-- | The 'read' function reads input from a string, which must be +-- completely consumed by the input process. read :: Read a => String -> a read s = either error id (readEither s) ------------------------------------------------------------------------ -- H98 compatibility +-- | 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 lex :: ReadS String -- As defined by H98 lex s = readP_to_S L.hsLex s +-- | Read a string representation of a character, using Haskell +-- source-language escape conventions. For example: +-- +-- > lexLitChar "\\nHello" = [("\\n", "Hello")] +-- lexLitChar :: ReadS String -- As defined by H98 lexLitChar = readP_to_S (do { (s, _) <- P.gather L.lexChar ; return s }) -- There was a skipSpaces before the P.gather L.lexChar, -- but that seems inconsistent with readLitChar +-- | Read a string representation of a character, using Haskell +-- source-language escape conventions, and convert it to the character +-- that it encodes. For example: +-- +-- > readLitChar "\\nHello" = [('\n', "Hello")] +-- readLitChar :: ReadS Char -- As defined by H98 readLitChar = readP_to_S L.lexChar +-- | Reads a non-empty string of decimal digits. lexDigits :: ReadS String lexDigits = readP_to_S (P.munch1 isDigit)