X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fglasgow_exts.xml;h=797a509343704bae3ede80f7d9563fc0e511aaf2;hb=390b7c4110bc0fc9b76d6342f288d44d58fc27b9;hp=372ebab6fcfee28552cd754a08da78cd612c5928;hpb=25f84fa7e4b84c3db5ba745a7881c009b778e0b1;p=ghc-hetmet.git
diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 372ebab..797a509 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -1971,7 +1971,7 @@ exactly as you would in an ordinary instance declaration.
(In contrast the context is inferred in a deriving clause
attached to a data type declaration.) These deriving instance
rules obey the same rules concerning form and termination as ordinary instance declarations,
-controlled by the same flags; see .
+controlled by the same flags; see .
The stand-alone syntax is generalised for newtypes in exactly the same
way that ordinary deriving clauses are generalised ().
@@ -3604,7 +3604,10 @@ kind for the type variable cxt.
GHC now instead allows you to specify the kind of a type variable directly, wherever
-a type variable is explicitly bound. Namely:
+a type variable is explicitly bound, with the flag .
+
+
+This flag enables kind signatures in the following places:
data declarations:
@@ -4322,24 +4325,27 @@ Template Meta-programming for Haskell" (Proc Haskell Workshop 2002).
There is a Wiki page about
Template Haskell at
-http://www.haskell.org/th/, and that is the best place to look for
+http://www.haskell.org/haskellwiki/Template_Haskell, and that is the best place to look for
further details.
You may also
consult the online
Haskell library reference material
-(search for the type ExpQ).
-[Temporary: many changes to the original design are described in
- "http://research.microsoft.com/~simonpj/tmp/notes2.ps".
-Not all of these changes are in GHC 6.6.]
+(look for module Language.Haskell.TH).
+Many changes to the original design are described in
+
+Notes on Template Haskell version 2.
+Not all of these changes are in GHC, however.
- The first example from that paper is set out below as a worked example to help get you started.
+ The first example from that paper is set out below ()
+as a worked example to help get you started.
-The documentation here describes the realisation in GHC. (It's rather sketchy just now;
-Tim Sheard is going to expand it.)
+The documentation here describes the realisation of Template Haskell in GHC. It is not detailed enough to
+understand Template Haskell; see the
+Wiki page.
@@ -4365,41 +4371,47 @@ Tim Sheard is going to expand it.)
an expression; the spliced expression must
have type Q Exp
- a list of top-level declarations; ; the spliced expression must have type Q [Dec]
- [Planned, but not implemented yet.] a
- type; the spliced expression must have type Q Typ.
+ a list of top-level declarations; the spliced expression must have type Q [Dec]
- (Note that the syntax for a declaration splice uses "$" not "splice" as in
- the paper. Also the type of the enclosed expression must be Q [Dec], not [Q Dec]
- as in the paper.)
-
+
+ Inside a splice you can can only call functions defined in imported modules,
+ not functions defined elsewhere in the same module.
A expression quotation is written in Oxford brackets, thus:
[| ... |], where the "..." is an expression;
- the quotation has type Expr.
+ the quotation has type Q Exp.[d| ... |], where the "..." is a list of top-level declarations;
the quotation has type Q [Dec].[t| ... |], where the "..." is a type;
- the quotation has type Type.
+ the quotation has type Q Typ.
- Reification is written thus:
+ A name can be quoted with either one or two prefix single quotes:
- reifyDecl T, where T is a type constructor; this expression
- has type Dec.
- reifyDecl C, where C is a class; has type Dec.
- reifyType f, where f is an identifier; has type Typ.
- Still to come: fixities
-
-
+ 'f has type Name, and names the function f.
+ Similarly 'C has type Name and names the data constructor C.
+ In general 'thing interprets thing in an expression context.
+
+ ''T has type Name, and names the type constructor T.
+ That is, ''thing interprets thing in a type context.
+
+
+ These Names can be used to construct Template Haskell expressions, patterns, delarations etc. They
+ may also be given as an argument to the reify function.
+
+(Compared to the original paper, there are many differnces of detail.
+The syntax for a declaration splice uses "$" not "splice".
+The type of the enclosed expression must be Q [Dec], not [Q Dec].
+Type splices are not implemented, and neither are pattern splices or quotations.
+
Using Template Haskell
@@ -4442,7 +4454,7 @@ Tim Sheard is going to expand it.)
- A Template Haskell Worked Example
+ A Template Haskell Worked Example To help you get over the confidence barrier, try out this skeletal worked example.
First cut and paste the two modules below into "Main.hs" and "Printf.hs":
@@ -4482,15 +4494,15 @@ parse s = [ L s ]
-- Generate Haskell source code from a parsed representation
-- of the format string. This code will be spliced into
-- the module which calls "pr", at compile time.
-gen :: [Format] -> ExpQ
+gen :: [Format] -> Q Exp
gen [D] = [| \n -> show n |]
gen [S] = [| \s -> s |]
gen [L s] = stringE s
-- Here we generate the Haskell code for the splice
-- from an input format string.
-pr :: String -> ExpQ
-pr s = gen (parse s)
+pr :: String -> Q Exp
+pr s = gen (parse s)
Now run the compiler (here we are a Cygwin prompt on Windows):
@@ -5297,6 +5309,87 @@ Assertion failures can be caught, see the documentation for the
unrecognised word is (silently)
ignored.
+ Certain pragmas are file-header pragmas. A file-header
+ pragma must precede the module keyword in the file.
+ There can be as many file-header pragmas as you please, and they can be
+ preceded or followed by comments.
+
+
+ LANGUAGE pragma
+
+ LANGUAGEpragma
+ pragmaLANGUAGE
+
+ The LANGUAGE pragma allows language extensions to be enabled
+ in a portable way.
+ It is the intention that all Haskell compilers support the
+ LANGUAGE pragma with the same syntax, although not
+ all extensions are supported by all compilers, of
+ course. The LANGUAGE pragma should be used instead
+ of OPTIONS_GHC, if possible.
+
+ For example, to enable the FFI and preprocessing with CPP:
+
+{-# LANGUAGE ForeignFunctionInterface, CPP #-}
+
+ LANGUAGE is a file-header pragma (see ).
+
+ Every language extension can also be turned into a command-line flag
+ by prefixing it with "-X"; for example .
+ (Similarly, all "-X" flags can be written as LANGUAGE pragmas.
+
+
+ A list of all supported language extensions can be obtained by invoking
+ ghc --supported-languages (see ).
+
+ Any extension from the Extension type defined in
+ Language.Haskell.Extension
+ may be used. GHC will report an error if any of the requested extensions are not supported.
+
+
+
+
+ OPTIONS_GHC pragma
+ OPTIONS_GHC
+
+ pragmaOPTIONS_GHC
+
+
+ The OPTIONS_GHC pragma is used to specify
+ additional options that are given to the compiler when compiling
+ this source file. See for
+ details.
+
+ Previous versions of GHC accepted OPTIONS rather
+ than OPTIONS_GHC, but that is now deprecated.
+
+
+ OPTIONS_GHC is a file-header pragma (see ).
+
+
+ INCLUDE pragma
+
+ The INCLUDE pragma is for specifying the names
+ of C header files that should be #include'd into
+ the C source code generated by the compiler for the current module (if
+ compiling via C). For example:
+
+
+{-# INCLUDE "foo.h" #-}
+{-# INCLUDE <stdio.h> #-}
+
+ INCLUDE is a file-header pragma (see ).
+
+ An INCLUDE pragma is the preferred alternative
+ to the option (), because the
+ INCLUDE pragma is understood by other
+ compilers. Yet another alternative is to add the include file to each
+ foreign import declaration in your code, but we
+ don't recommend using this approach with GHC.
+
+
DEPRECATED pragmaDEPRECATED
@@ -5349,31 +5442,6 @@ Assertion failures can be caught, see the documentation for the
.
-
- INCLUDE pragma
-
- The INCLUDE pragma is for specifying the names
- of C header files that should be #include'd into
- the C source code generated by the compiler for the current module (if
- compiling via C). For example:
-
-
-{-# INCLUDE "foo.h" #-}
-{-# INCLUDE <stdio.h> #-}
-
- The INCLUDE pragma(s) must appear at the top of
- your source file with any OPTIONS_GHC
- pragma(s).
-
- An INCLUDE pragma is the preferred alternative
- to the option (), because the
- INCLUDE pragma is understood by other
- compilers. Yet another alternative is to add the include file to each
- foreign import declaration in your code, but we
- don't recommend using this approach with GHC.
-
-
INLINE and NOINLINE pragmas
@@ -5520,29 +5588,6 @@ happen.
-
- LANGUAGE pragma
-
- LANGUAGEpragma
- pragmaLANGUAGE
-
- This allows language extensions to be enabled in a portable way.
- It is the intention that all Haskell compilers support the
- LANGUAGE pragma with the same syntax, although not
- all extensions are supported by all compilers, of
- course. The LANGUAGE pragma should be used instead
- of OPTIONS_GHC, if possible.
-
- For example, to enable the FFI and preprocessing with CPP:
-
-{-# LANGUAGE ForeignFunctionInterface, CPP #-}
-
- Any extension from the Extension type defined in
- Language.Haskell.Extension may be used. GHC will report an error if any of the requested extensions are not supported.
-
-
-
LINE pragma
@@ -5562,22 +5607,6 @@ happen.
pragma.
-
- OPTIONS_GHC pragma
- OPTIONS_GHC
-
- pragmaOPTIONS_GHC
-
-
- The OPTIONS_GHC pragma is used to specify
- additional options that are given to the compiler when compiling
- this source file. See for
- details.
-
- Previous versions of GHC accepted OPTIONS rather
- than OPTIONS_GHC, but that is now deprecated.
-
-
RULES pragma