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@haskell.org [mailto:template-haskell-bounces@haskell.org] On | Behalf Of Bulat Ziganshin | Sent: 25 October 2005 15:25 | To: Simon Peyton-Jones | Cc: Christoph Herrmann; template-haskell@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@HotPOP.com | | | | _______________________________________________ | template-haskell mailing list | template-haskell@haskell.org | http://www.haskell.org/mailman/listinfo/template-haskell