X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=9da32531654db5d8ee961a820e17a2bdc0b91786;hb=117dc73b8a8f6a4184a825a96c372480377f4680;hp=2169bbaae566be497d1317bc236ac7c76d7f0e42;hpb=d0f7e402963b6f6cbe78c2a0421da2dacdca6921;p=ghc-hetmet.git
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 2169bba..9da3253 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -1232,7 +1232,7 @@ it is not clear which of the two types is intended.
Haskell 98 regards all four as ambiguous, but with the
- flag, GHC will accept
+ flag, GHC will accept
the former two. The rules are precisely the same as those for instance
declarations in Haskell 98, where the method names on the left-hand side
of the method bindings in an instance declaration refer unambiguously
@@ -1990,15 +1990,28 @@ main = do
display (inc (inc counterB)) -- prints "##"
-At the moment, record update syntax is only supported for Haskell 98 data types,
-so the following function does not work:
-
+Record update syntax is supported for existentials (and GADTs):
--- This is invalid; use explicit NewCounter instead for now
setTag :: Counter a -> a -> Counter a
setTag obj t = obj{ tag = t }
+The rule for record update is this:
+the types of the updated fields may
+mention only the universally-quantified type variables
+of the data constructor. For GADTs, the field may mention only types
+that appear as a simple type-variable argument in the constructor's result
+type. For example:
+
+data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b } -- c is existential
+upd1 t x = t { f1=x } -- OK: upd1 :: T a b -> a' -> T a' b
+upd2 t x = t { f3=x } -- BAD (f3's type mentions c, which is
+ -- existentially quantified)
+data G a b where { G1 { g1::a, g2::c } :: G a [c] }
+upd3 g x = g { g1=x } -- OK: upd3 :: G a b -> c -> G c b
+upd4 g x = g { g2=x } -- BAD (f2's type mentions c, which is not a simple
+ -- type-variable argument in G1's result type)
+
@@ -3247,9 +3260,6 @@ sets of instance declarations.
Instance declarations
-
-Relaxed rules for instance declarations
-
An instance declaration has the form
instance ( assertion1, ..., assertionn) => classtype1 ... typem where ...
@@ -3259,19 +3269,73 @@ The part before the "=>" is the
"=>" is the head of the instance declaration.
+
+Relaxed rules for the instance head
+
In Haskell 98 the head of an instance declaration
must be of the form C (T a1 ... an), where
-C is the class, T is a type constructor,
+C is the class, T is a data type constructor,
and the a1 ... an are distinct type variables.
-Furthermore, the assertions in the context of the instance declaration
+GHC relaxes these rules in two ways.
+
+
+
+The flag allows the head of the instance
+declaration to mention arbitrary nested types.
+For example, this becomes a legal instance declaration
+
+ instance C (Maybe Int) where ...
+
+See also the rules on overlap.
+
+
+With the flag, instance heads may use type
+synonyms. As always, using a type synonym is just shorthand for
+writing the RHS of the type synonym definition. For example:
+
+
+
+ type Point = (Int,Int)
+ instance C Point where ...
+ instance C [Point] where ...
+
+
+
+is legal. However, if you added
+
+
+
+ instance C (Int,Int) where ...
+
+
+
+as well, then the compiler will complain about the overlapping
+(actually, identical) instance declarations. As always, type synonyms
+must be fully applied. You cannot, for example, write:
+
+
+ type P a = [[a]]
+ instance Monad P where ...
+
+
+
+
+
+
+
+
+Relaxed rules for instance contexts
+
+In Haskell 98, the assertions in the context of the instance declaration
must be of the form C a where a
is a type variable that occurs in the head.
+
-The flag loosens these restrictions
-considerably. Firstly, multi-parameter type classes are permitted. Secondly,
-the context and head of the instance declaration can each consist of arbitrary
+The flag relaxes this rule, as well
+as the corresponding rule for type signatures (see ).
+With this flag the context of the instance declaration can each consist of arbitrary
(well-kinded) assertions (C t1 ... tn) subject only to the
following rules:
@@ -3569,47 +3633,6 @@ hard to pin down.) We are interested to receive feedback on these points.
-
-Type synonyms in the instance head
-
-
-Unlike Haskell 98, instance heads may use type
-synonyms. (The instance "head" is the bit after the "=>" in an instance decl.)
-As always, using a type synonym is just shorthand for
-writing the RHS of the type synonym definition. For example:
-
-
-
- type Point = (Int,Int)
- instance C Point where ...
- instance C [Point] where ...
-
-
-
-is legal. However, if you added
-
-
-
- instance C (Int,Int) where ...
-
-
-
-as well, then the compiler will complain about the overlapping
-(actually, identical) instance declarations. As always, type synonyms
-must be fully applied. You cannot, for example, write:
-
-
-
- type P a = [[a]]
- instance Monad P where ...
-
-
-
-This design decision is independent of all the others, and easily
-reversed, but it makes sense to me.
-
-
-
@@ -4328,6 +4351,31 @@ class (F a ~ b) => C a b where
+
+ Type families and instance declarations
+ Type families require us to extend the rules for
+ the form of instance heads, which are given
+ in .
+ Specifically:
+
+ Data type families may appear in an instance head
+ Type synonym families may not appear (at all) in an instance head
+
+The reason for the latter restriction is that there is no way to check for. Consider
+
+ type family F a
+ type instance F Bool = Int
+
+ class C a
+
+ instance C Int
+ instance C (F a)
+
+Now a constraint (C (F Bool)) would match both instances.
+The situation is especially bad because the type instance for F Bool
+might be in another module, or even in a module that is not yet written.
+
+
@@ -5274,9 +5322,13 @@ f xs = ys ++ ys
ys :: [a]
ys = reverse xs
-The type signature for f brings the type variable a into scope; it scopes over
-the entire definition of f.
-In particular, it is in scope at the type signature for ys.
+The type signature for f brings the type variable a into scope,
+because of the explicit forall ().
+The type variables bound by a forall scope over
+the entire definition of the accompanying value declaration.
+In this example, the type variable a scopes over the whole
+definition of f, including over
+the type signature for ys.
In Haskell 98 it is not possible to declare
a type for ys; a major benefit of scoped type variables is that
it becomes possible to do so.
@@ -7087,6 +7139,83 @@ happen.
+
+ ANN pragmas
+
+ GHC offers the ability to annotate various code constructs with additional
+ data by using three pragmas. This data can then be inspected at a later date by
+ using GHC-as-a-library.
+
+
+ Annotating values
+
+ ANN
+
+ Any expression that has both Typeable and Data instances may be attached to a top-level value
+ binding using an ANN pragma. In particular, this means you can use ANN
+ to annotate data constructors (e.g. Just) as well as normal values (e.g. take).
+ By way of example, to annotate the function foo with the annotation Just "Hello"
+ you would do this:
+
+
+{-# ANN foo (Just "Hello") #-}
+foo = ...
+
+
+
+ A number of restrictions apply to use of annotations:
+
+ The binder being annotated must be at the top level (i.e. no nested binders)
+ The binder being annotated must be declared in the current module
+ The expression you are annotating with must have a type with Typeable and Data instances
+ The Template Haskell staging restrictions apply to the
+ expression being annotated with, so for example you cannot run a function from the module being compiled.
+
+ To be precise, the annotation {-# ANN x e #-} is well staged if and only if $(e) would be
+ (disregarding the usual type restrictions of the splice syntax, and the usual restriction on splicing inside a splice - $([|1|]) is fine as an annotation, albeit redundant).
+
+
+ If you feel strongly that any of these restrictions are too onerous,
+ please give the GHC team a shout.
+
+
+ However, apart from these restrictions, many things are allowed, including expressions which not fully evaluated!
+ Annotation expressions will be evaluated by the compiler just like Template Haskell splices are. So, this annotation is fine:
+
+
+{-# ANN f SillyAnnotation { foo = (id 10) + $([| 20 |]), bar = 'f } #-}
+f = ...
+
+
+
+
+ Annotating types
+
+ ANN type
+ ANN
+
+ You can annotate types with the ANN pragma by using the type keyword. For example:
+
+
+{-# ANN type Foo (Just "A `Maybe String' annotation") #-}
+data Foo = ...
+
+
+
+
+ Annotating modules
+
+ ANN module
+ ANN
+
+ You can annotate modules with the ANN pragma by using the module keyword. For example:
+
+
+{-# ANN module (Just "A `Maybe String' annotation") #-}
+
+
+
+
LINE pragma