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

[Gabor Greif]

Hmm, shouldn't that be -XDataKinds (instead of -XTypeOperators)?


also:
  umambiguous ---> unambiguous
  becuase ---> because

Cheers,

    Gabor

On 12/15/14, git at git.haskell.org <git at git.haskell.org> wrote:
> 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>
>
>
> _______________________________________________
> ghc-commits mailing list
> ghc-commits at haskell.org
> http://www.haskell.org/mailman/listinfo/ghc-commits
>