[Template-haskell] new TH tutorial (request for comments)

[Bulat Ziganshin]

Hello Johannes,

Friday, January 20, 2006, 7:10:18 AM, you wrote:

JA> i've recently written a tutorial on template haskell located at
JA> (http://www.haskell.org/hawiki/TemplateHaskellTutorial).

i'm now reading this tutorial. my thoughts:

1. when i read original TH report, i don't understand anything. there
was some examples, but how i can change them or construct anything
itslef, was a big secret for me. only after reading last chapters
where was described that TH programm must really generate AST and all
previous fancy examples is just shortcuts for manual AST generation, i
got an idea. rereading paper second time allow me to understand how
this all really work

The same relates, although in less degree, to your tutorial. you
describe ASTs without prior giving reader knowledge about how they
will be used. i think that prior information about splicing and that a
spliced expression must return AST representing list of declarations
or expression, would help here. that will build some logical scheme of
description:

- TH allows to generate code at compile-time
- this code is inserted by splices
- spliced expressions returns Haskell code respresented as AST
- types Exp, Dec and so on forms that ASTs
- all this done in Q monad, which gives us additional operations -
reification, name generation, error reporting

2. "Splicing is the dual operation of reification; it evaluates its
content at compile-time, converts the resulting AST into Haskell code
and inserts it in the program". actually, splicing is reverse
operation for the quasi-quotation, which don't get your speciall
attention. and that is another tutorial leak - quasi-quotation is not
so simple and obvious operation, as seems at the first look. believe
you or not, but i stucked on the chapter on quasi-quotation when i
tried to write my own TH doc

later you call quasi-quotation as "reification" and that's farther
complicates the terminology - in TH, reification, i.e. call to "reify"
function, retrieves information about given Name from Q monad
environment, while quasi-quotation is a syntax sugar what allows to
write AST expression in the form of literal Haskell code

3. what i like is what you early introduce reification and gives more
explanations on examples of ASTs representing expressions - more than
i does itself in my own tutorial

4. your tutorial does not mention many non-trivial details of TH,
icluding those that necessaryy to start real programming in TH. for
example, difference between mkName and newName. a "Restrictions"
chapter is non-readable in some parts - a least, i understand "In its
current implementation reificiation of non-quasi-quoted code seems
very restricted" after heavy thinking and only because i already know
that. and i don't understand the "Easily pattern matching the tree based
on its nodes' types seems limited."

5. what i really loves in your tutorial is your examples: they are
simple and elegant, but powerful!

-- 
Best regards,
 Bulat                            mailto:bulatz at HotPOP.com