[project @ 2004-07-23 15:26:06 by ross]

[ghc-base.git] / GHC / Read.lhs

diff --git a/GHC/Read.lhs b/GHC/Read.lhs
index 2bc3320..1e213b5 100644 (file)
--- a/GHC/Read.lhs
+++ b/GHC/Read.lhs
@@ -3,7 +3,7 @@
 -----------------------------------------------------------------------------
 -- |
 -- 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,8 +49,8 @@ import qualified Text.ParserCombinators.ReadP as P
 
 import Text.ParserCombinators.ReadP
   ( ReadP
+  , ReadS
   , readP_to_S
-  , readS_to_P
   )
 
 import qualified Text.Read.Lex as L
@@ -65,11 +65,14 @@ 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}
@@ -90,25 +93,20 @@ 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
 
 class Read a where
   readsPrec    :: Int -> ReadS a
   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
@@ -118,13 +116,13 @@ 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
 
 ------------------------------------------------------------------------
@@ -157,15 +155,27 @@ read s = either error id (readEither s)
 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 { P.skipSpaces ;
-                             (s, L.Char _) <- P.gather L.lex ;
+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 (do { L.Char c <- L.lex ;
-                              return c })
+readLitChar = readP_to_S L.lexChar
 
+-- | Reads a non-empty string of decimal digits.
 lexDigits :: ReadS String
 lexDigits = readP_to_S (P.munch1 isDigit)
 
@@ -177,17 +187,17 @@ lexP :: ReadPrec L.Lexeme
 lexP = lift L.lex
 
 paren :: ReadPrec a -> ReadPrec a
--- ^ @(paren p)@ parses "(P0)"
---     where @p@ parses "P0" in precedence context zero
+-- ^ @(paren p)@ parses \"(P0)\"
+--     where @p@ parses \"P0\" in precedence context zero
 paren p = do L.Punc "(" <- lexP
             x          <- reset p
             L.Punc ")" <- lexP
             return x
 
 parens :: ReadPrec a -> ReadPrec a
--- ^ @(parens p)@ parses "P", "(P0)", "((P0))", etc, 
---     where @p@ parses "P"  in the current precedence context
---             parses "P0" in precedence context zero
+-- ^ @(parens p)@ parses \"P\", \"(P0)\", \"((P0))\", etc, 
+--     where @p@ parses \"P\"  in the current precedence context
+--             parses \"P0\" in precedence context zero
 parens p = optional
  where
   optional  = p +++ mandatory
@@ -217,7 +227,7 @@ list readx =
 choose :: [(String, ReadPrec a)] -> ReadPrec a
 -- ^ Parse the specified lexeme and continue as specified.
 -- Esp useful for nullary constructors; e.g.
---    @choose [("A", return A), ("B", return B)]@
+--    @choose [(\"A\", return A), (\"B\", return B)]@
 choose sps = foldr ((+++) . try_one) pfail sps
           where
             try_one (s,p) = do { L.Ident s' <- lexP ;