From 4d60ffc3e9a167c64e395046e1d2ef51eeb165ec Mon Sep 17 00:00:00 2001 From: "simonpj@microsoft.com" Date: Tue, 11 Sep 2007 08:22:12 +0000 Subject: [PATCH 1/1] Improve documentation for Template Haskell --- docs/users_guide/glasgow_exts.xml | 69 +++++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 30 deletions(-) diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index 372ebab..da6a125 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 (). @@ -4322,24 +4322,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 +4368,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 +4451,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 +4491,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): -- 1.7.10.4