Remove Control.Parallel*, now in package parallel
[haskell-directory.git] / GHC / Read.lhs
index 17a9d81..2610ec5 100644 (file)
@@ -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
@@ -14,6 +14,7 @@
 --
 -----------------------------------------------------------------------------
 
+-- #hide
 module GHC.Read 
   ( Read(..)   -- class
   
@@ -49,8 +50,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,17 +66,24 @@ 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
@@ -90,25 +98,113 @@ 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' 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
+
 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).
+  -- The default definition uses 'readList'.  Instances that define 'readPrec'
+  -- should also define 'readListPrec' as 'readListPrecDefault'.
   readListPrec :: ReadPrec [a]
   
   -- default definitions
@@ -118,18 +214,20 @@ 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
+-- ^ 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'.
 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
+-- ^ A possible replacement definition for the 'readListPrec' method,
+--   defined using 'readPrec' (GHC only).
 readListPrecDefault = list readPrec
 
 ------------------------------------------------------------------------
 -- utility functions
 
+-- | equivalent to 'readsPrec' with a precedence of 0.
 reads :: Read a => ReadS a
 reads = readsPrec minPrec
 
@@ -148,24 +246,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 { 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)
 
@@ -187,7 +314,7 @@ paren p = do L.Punc "(" <- lexP
 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
+--         and parses \"P0\" in precedence context zero
 parens p = optional
  where
   optional  = p +++ mandatory
@@ -428,7 +555,7 @@ instance (Integral a, Read a) => Read (Ratio a) where
 
 %*********************************************************
 %*                                                     *
-\subsection{Tuple instances of Read}
+       Tuple instances of Read, up to size 15
 %*                                                     *
 %*********************************************************
 
@@ -445,71 +572,145 @@ instance Read () where
   readList     = readListDefault
 
 instance (Read a, Read b) => Read (a,b) where
-  readPrec =
-    parens
-    ( paren
-      ( do x <- readPrec
-           L.Punc "," <- lexP
-           y <- readPrec
-           return (x,y)
-      )
-    )
-
+  readPrec = wrap_tup read_tup2
   readListPrec = readListPrecDefault
   readList     = readListDefault
 
+wrap_tup :: ReadPrec a -> ReadPrec a
+wrap_tup p = parens (paren p)
+
+read_comma :: ReadPrec ()
+read_comma = do { L.Punc "," <- lexP; return () }
+
+read_tup2 :: (Read a, Read b) => ReadPrec (a,b)
+-- Reads "a , b"  no parens!
+read_tup2 = do x <- readPrec
+              read_comma
+              y <- readPrec
+              return (x,y)
+
+read_tup4 :: (Read a, Read b, Read c, Read d) => ReadPrec (a,b,c,d)
+read_tup4 = do (a,b) <- read_tup2
+               read_comma
+               (c,d) <- read_tup2
+               return (a,b,c,d)
 
-instance (Read a, Read b, Read c) => Read (a, b, c) where
-  readPrec =
-    parens
-    ( paren
-      ( do x <- readPrec
-           L.Punc "," <- lexP
-           y <- readPrec
-           L.Punc "," <- lexP
-           z <- readPrec
-           return (x,y,z)
-      )
-    )
 
+read_tup8 :: (Read a, Read b, Read c, Read d, Read e, Read f, Read g, Read h)
+         => ReadPrec (a,b,c,d,e,f,g,h)
+read_tup8 = do (a,b,c,d) <- read_tup4
+               read_comma
+               (e,f,g,h) <- read_tup4
+               return (a,b,c,d,e,f,g,h)
+
+
+instance (Read a, Read b, Read c) => Read (a, b, c) where
+  readPrec = wrap_tup (do { (a,b) <- read_tup2; read_comma 
+                         ; c <- readPrec 
+                         ; return (a,b,c) })
   readListPrec = readListPrecDefault
   readList     = readListDefault
 
 instance (Read a, Read b, Read c, Read d) => Read (a, b, c, d) where
-  readPrec =
-    parens
-    ( paren
-      ( do w <- readPrec
-           L.Punc "," <- lexP
-           x <- readPrec
-           L.Punc "," <- lexP
-           y <- readPrec
-           L.Punc "," <- lexP
-           z <- readPrec
-           return (w,x,y,z)
-      )
-    )
-
+  readPrec = wrap_tup read_tup4
   readListPrec = readListPrecDefault
   readList     = readListDefault
 
 instance (Read a, Read b, Read c, Read d, Read e) => Read (a, b, c, d, e) where
-  readPrec =
-    parens
-    ( paren
-      ( do v <- readPrec
-           L.Punc "," <- lexP
-           w <- readPrec
-           L.Punc "," <- lexP
-           x <- readPrec
-           L.Punc "," <- lexP
-           y <- readPrec
-           L.Punc "," <- lexP
-           z <- readPrec
-           return (v,w,x,y,z)
-      )
-    )
+  readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
+                         ; e <- readPrec
+                         ; return (a,b,c,d,e) })
+  readListPrec = readListPrecDefault
+  readList     = readListDefault
+
+instance (Read a, Read b, Read c, Read d, Read e, Read f)
+       => Read (a, b, c, d, e, f) where
+  readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
+                         ; (e,f) <- read_tup2
+                         ; return (a,b,c,d,e,f) })
+  readListPrec = readListPrecDefault
+  readList     = readListDefault
+
+instance (Read a, Read b, Read c, Read d, Read e, Read f, Read g)
+       => Read (a, b, c, d, e, f, g) where
+  readPrec = wrap_tup (do { (a,b,c,d) <- read_tup4; read_comma
+                         ; (e,f) <- read_tup2; read_comma
+                         ; g <- readPrec
+                         ; return (a,b,c,d,e,f,g) })
+  readListPrec = readListPrecDefault
+  readList     = readListDefault
+
+instance (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) where
+  readPrec     = wrap_tup read_tup8
+  readListPrec = readListPrecDefault
+  readList     = readListDefault
+
+instance (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) where
+  readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
+                         ; i <- readPrec
+                         ; return (a,b,c,d,e,f,g,h,i) })
+  readListPrec = readListPrecDefault
+  readList     = readListDefault
+
+instance (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) where
+  readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
+                         ; (i,j) <- read_tup2
+                         ; return (a,b,c,d,e,f,g,h,i,j) })
+  readListPrec = readListPrecDefault
+  readList     = readListDefault
+
+instance (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) where
+  readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
+                         ; (i,j) <- read_tup2; read_comma
+                         ; k <- readPrec
+                         ; return (a,b,c,d,e,f,g,h,i,j,k) })
+  readListPrec = readListPrecDefault
+  readList     = readListDefault
+
+instance (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) where
+  readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
+                         ; (i,j,k,l) <- read_tup4
+                         ; return (a,b,c,d,e,f,g,h,i,j,k,l) })
+  readListPrec = readListPrecDefault
+  readList     = readListDefault
+
+instance (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) where
+  readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
+                         ; (i,j,k,l) <- read_tup4; read_comma
+                         ; m <- readPrec
+                         ; return (a,b,c,d,e,f,g,h,i,j,k,l,m) })
+  readListPrec = readListPrecDefault
+  readList     = readListDefault
+
+instance (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) where
+  readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
+                         ; (i,j,k,l) <- read_tup4; read_comma
+                         ; (m,n) <- read_tup2
+                         ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n) })
+  readListPrec = readListPrecDefault
+  readList     = readListDefault
 
+instance (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) where
+  readPrec = wrap_tup (do { (a,b,c,d,e,f,g,h) <- read_tup8; read_comma
+                         ; (i,j,k,l) <- read_tup4; read_comma
+                         ; (m,n) <- read_tup2; read_comma
+                         ; o <- readPrec
+                         ; return (a,b,c,d,e,f,g,h,i,j,k,l,m,n,o) })
   readListPrec = readListPrecDefault
   readList     = readListDefault
 \end{code}