[Template-haskell] RE: Documentation Template Haskell

[Bulat Ziganshin]

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