X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;ds=sidebyside;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=393cbf50ac297252e7f2cc1cc0b71781a1d2f3ea;hb=9bcd95bad83ee937c178970e8b729732e680fe1e;hp=2c3bea02f9ccb02eba1339dfae6a9816d5be446e;hpb=5bd23e513eeff5beb852d60e2c9ff6314e24e87b;p=ghc-hetmet.git
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 2c3bea0..393cbf5 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -2005,7 +2005,7 @@ type. For example:
data T a where { T1 { f1::a, f2::(a,b) } :: T a } -- b is existential
upd1 t x = t { f1=x } -- OK: upd1 :: T a -> b -> T b
upd2 t x = t { f2=x } -- BAD (f2's type mentions b, which is
- existentially quantified)
+ -- 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
@@ -5322,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.
@@ -7135,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