[Template-haskell] RE: Documentation Template Haskell

[Simon Peyton-Jones]

Good start.  I'm not sure whether it would have enough detail to meet
Christoph's need, but let's ask him.  Maybe he can fill in some of the
blanks.

Simon


| -----Original Message-----
| From: template-haskell-bounces at haskell.org
[mailto:template-haskell-bounces at haskell.org] On
| Behalf Of Bulat Ziganshin
| Sent: 25 October 2005 15:25
| To: Simon Peyton-Jones
| Cc: Christoph Herrmann; template-haskell at haskell.org
| Subject: Re: [Template-haskell] RE: Documentation Template Haskell
| 
| Hello Simon,
| 
| Tuesday, October 25, 2005, 1:47:38 PM, you wrote:
| 
| SPJ> So here's an offer.  If you'd be willing to draft the
documentation you
| 
| "TH can be used to automatically generate any Haskell code at the
compile
| time. This code will be compiled just the same as if it was
| hand-written. This allows to create metaprograms - programs, which
| itself generate Haskell programs, allowing to use programming
| techniques not available in Haskell itself, such as macro
| preprocessing, self-optimized algorithms, generic programming,
| functions with variable parameters count and so on
| 
| TH code is written as ordinal Haskell functions, which generate AST
| (abstract syntax tree) representing Haskell code. This AST represented
| by type Exp. Moreover, these functions must function in special monad
| Q, which provides abilities to generate unique identifiers for
| code builded and to make queries about environment in which this
function
| is running.
| 
| Type Exp allows to represent any Haskell code:
| 
| data Exp = LitE Lit  -- representing literals
|          | VarE Name -- representing variables
|          .....
| 
| Type Lit, used in Exp, represents Haskell literals:
| .....
| -- description for other types
| 
| 
| To make TH programming easier, the above-mentioned constructors are
| duplicated by functions which accepts arguments lifted to Q monad and
| return results in the same monad. For example, AppE constructor dubbed
| by appE function. These functions are defined using types which is
| also lifted to Q monad, such as ExpQ = Q Exp and so on.
| 
| To create unique identifiers for generated code you must use the
| following functions: ....
| 
| You can also query about environment which runs TH function with the
| following functions: ....
| 
| 
| Also, to simplify building of ASTs, Template Haskell can automatically
| translate ordinary Haskell code to this representation by using
| [|...|]. This code has type ExpQ, so it is a computation which will
| return Exp, representing code inside brackets, on execution in monad
Q.
| Code inside brackets can be any Haskell code, local identifiers will
| be translated to code generating unique identifiers.
| 
| If you need to create expression of type Pat, use form [p| ... |],
| type Dec - use [d| ... |].
| 
| Code, generated by TH functions, can be spilled to hand-written code
| by using splice notation: $function or $(function parameters...). You
| can use splices in any place where Haskell expression or declaration
| can be written. Of course, the spliced expression must return value of
| appropriate type - ExpQ or DecQ, respectively. You also can use spills
| in definitions of TH functions, inside abovementioned brackets, making
| some form of macrogeneration. In other cases, you must import TH
| functions in order to spill it, because TH-generating code must be
| already compiled in time where current module code isn't even
| syntax-processed"
| 
| >END-OF-DOC
| 
| 
| 
| this doc doesn't include 'name and ''type, whose explanations i can't
| recall. i also wrote TH tutorial, but don't finish it. You can see the
| last edition as http://freearc.narod.ru/th.htm
| 
| one more suggestion - i think that we must include in GHC
| distribution useful TH application libraries: printf, class derivation
| (a la DrIFT)
| 
| 
| 
| --
| Best regards,
|  Bulat                            mailto:bulatz at HotPOP.com
| 
| 
| 
| _______________________________________________
| template-haskell mailing list
| template-haskell at haskell.org
| http://www.haskell.org/mailman/listinfo/template-haskell