[commit: ghc] master: Improve documentation of syntax for promoted lists (a972bdd)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/a972bddfc8115d80d774383a55202a293dc68595/ghc

>---------------------------------------------------------------

commit a972bddfc8115d80d774383a55202a293dc68595
Author: Simon Peyton Jones <simonpj at microsoft.com>
Date:   Mon Dec 15 17:08:29 2014 +0000

    Improve documentation of syntax for promoted lists
    
    THe documentation in 7.9.4 of promoted list and tuple types was
    misleading, which led to Trac #9882.  This patch makes explicit
    that only type-level with two or more elements can have the
    quote omitted.


>---------------------------------------------------------------

a972bddfc8115d80d774383a55202a293dc68595
 compiler/parser/Parser.y          |  8 ++++++--
 docs/users_guide/glasgow_exts.xml | 19 ++++++++++++++++---
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/compiler/parser/Parser.y b/compiler/parser/Parser.y
index bffe6e1..235d34a 100644
--- a/compiler/parser/Parser.y
+++ b/compiler/parser/Parser.y
@@ -1483,6 +1483,10 @@ atype :: { LHsType RdrName }
                                                        [mo $2,mc $4] }
         | SIMPLEQUOTE var                       { sLL $1 $> $ HsTyVar $ unLoc $2 }
 
+        -- Two or more [ty, ty, ty] must be a promoted list type, just as
+        -- if you had written '[ty, ty, ty]
+        -- (One means a list type, zero means the list type constructor, 
+        -- so you have to quote those.)
         | '[' ctype ',' comma_types1 ']'  {% ams (sLL $1 $> $ HsExplicitListTy
                                                      placeHolderKind ($2 : $4))
                                                  [mo $1, mj AnnComma $3,mc $5] }
@@ -1503,11 +1507,11 @@ inst_types1 :: { [LHsType RdrName] }
         | inst_type ',' inst_types1    {% addAnnotation (gl $1) AnnComma (gl $2)
                                           >> return ($1 : $3) }
 
-comma_types0  :: { [LHsType RdrName] }
+comma_types0  :: { [LHsType RdrName] }  -- Zero or more:  ty,ty,ty
         : comma_types1                  { $1 }
         | {- empty -}                   { [] }
 
-comma_types1    :: { [LHsType RdrName] }
+comma_types1    :: { [LHsType RdrName] }  -- One or more:  ty,ty,ty
         : ctype                        { [$1] }
         | ctype  ',' comma_types1      {% addAnnotation (gl $1) AnnComma (gl $2)
                                           >> return ($1 : $3) }
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index e12703f..7edca07 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -6882,9 +6882,9 @@ is a single quote.</para>
 </sect2>
 
 <sect2 id="promoted-lists-and-tuples">
-<title>Promoted lists and tuples types</title>
+<title>Promoted list and tuple types</title>
 <para>
-Haskell's list and tuple types are natively promoted to kinds, and enjoy the
+With <option>-XTypeOperators</option>, Haskell's list and tuple types are natively promoted to kinds, and enjoy the
 same convenient syntax at the type level, albeit prefixed with a quote:
 <programlisting>
 data HList :: [*] -> * where
@@ -6893,8 +6893,21 @@ data HList :: [*] -> * where
 
 data Tuple :: (*,*) -> * where
   Tuple :: a -> b -> Tuple '(a,b)
+
+foo0 :: HList '[]
+foo0 = HNil
+
+foo1 :: HList '[Int]
+foo1 = HCons (3::Int) HNil
+
+foo2 :: HList [Int, Bool]
+foo2 = ...
 </programlisting>
-Note that this requires <option>-XTypeOperators</option>.
+For type-level lists of <emphasis>two or more elements</emphasis>,
+such as the signature of <literal>foo2</literal> above, the quote may be omitted because the meaning is
+umambiguous. But for lists of one or zero elements (as in <literal>foo0</literal>
+and <literal>foo1</literal>), the quote is required, becuase the types <literal>[]</literal>
+and <literal>[Int]</literal> have existing meanings in Haskell.
 </para>
 </sect2>