X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=393cbf50ac297252e7f2cc1cc0b71781a1d2f3ea;hp=78983eb06b54d1087f45768100799760b99c4b69;hb=9bcd95bad83ee937c178970e8b729732e680fe1e;hpb=b1f3ff48870a3a4670cb41b890b78bbfffa8a32e
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 78983eb..393cbf5 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -7139,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