RE: Documentation Template Haskell
Christoph, and other TH users, | > I have been waiting for a long while for more documentation | > about the use of Template Haskell as it is currently implemented, | > now ghc-6.4.1. The documentation on the web refers to several old You're absolutely right. Template Haskell is appallingly badly documented. The reason I have not done anything about it is that there's very little traffic on the Template Haskell list (or any other, about TH), and that has de-motivated me so far as improving TH is concerned. I tend to pay more attention to things that I think people are actively using and care about. TH seems to have had quite a bit less impact than I originally thought it might, given that it provides something qualitatively new. But maybe I'm wrong. For example, I didn't know that it was important to you. Maybe there are others. In any case, as you may guess I find it difficult to find enough time to do all the GHC related things that GHC's users would like. That's good, because it means GHC is being useful, but bad because some things don't get done. My current hope is to broaden the base of people who are willing to contribute to GHC themselves, with support from me and Simon, so that Simon and I aren't always on the critical path. So here's an offer. If you'd be willing to draft the documentation you would like to see, I would be willing to - review it, - answer questions, and - write parts where you don't know what to say. But you already know a lot, so you are well placed to write an outline. Perhaps TH folk would be willing to help too? RSVP to the TH list (which I'm ccing). I know this won't be quite the reply you were hoping for, but I hope you'll consider it. Simon | -----Original Message----- | From: Christoph Herrmann [mailto:herrmann@uni-passau.de] | Sent: 22 October 2005 18:42 | To: Simon Peyton-Jones | Subject: Re: Documentation Template Haskell | | Dear Simon, | | > Anything more than a list of library function types would do it. | | It would be good if it contains some explanations. Recently | I have found the following example on the mailing list but I can | only guess what, e.g., "tupP" means. | | sel' :: Int -> Int -> ExpQ | sel' i n = lamE [pat] rhs | where pat = tupP (map varP as) | rhs = varE (as !! (i - 1)) | as = map mkName [ ("a__" ++ show j) | j <- [1..n] ] | | Looking up Google for "tupP TH" leads me to some pages about TH | where I can either find some old example TH programs without "tupP" | or a list of library functions where I can only get the type of "tupP". | What I need would be a few English words telling what tupP actually does. | | Also, I'm wondering about the TH function "tuple" below whether it is | an old version, a plan for the future or even supposed to work with | ghc-6.4.1 but I forgot some import declarations. | | tuple :: Int -> Q Exp | tuple n = [|\list -> $(tupE (exprs [|list|])) |] | where | exprs list = [infixE (Just (list::[Char])) | (varE "!!") | (Just (litE $ integerL (toInteger num))) | | num <- [0..(n - 1)]] | | | Christoph Herrmann wrote: | > Dear Simon, | > | > I have been waiting for a long while for more documentation | > about the use of Template Haskell as it is currently implemented, | > now ghc-6.4.1. The documentation on the web refers to several old | > versions of TH and most of the examples don't work any more, | > e.g., the generation of a function which selects a component | > from a tuple. I don't know which of the new features you proposed | > are currently implemented. | > | > I need Template Haskell both for my work on metaprogramming | > and for teaching. Could you please point me to information | > about the current state? It doesn't matter for me how well it is | > written, as far as the definitions are up-to-date. Also, some examples | > which deal with code construction and reification and which work with | > ghc-6.4.1 would be useful for me. Again, I do not care about how they | > look like. Anything more than a list of library function types would do it. | > | > Many thanks in advance | > -- | > Christoph Herrmann | > University of Passau, Germany | > | >
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
Bulat Ziganshin wrote:
one more suggestion - i think that we must include in GHC distribution useful TH application libraries: printf, class derivation (a la DrIFT)
I'd love that. Are there any such libraries at the moment? Somewhere? If there is some kind of blueprint, I could perhaps use it http://www.haskell.org/pipermail/template-haskell/2005-October/000474.html -- -- Johannes Waldmann -- Tel/Fax (0341) 3076 6479/80 -- ---- http://www.imn.htwk-leipzig.de/~waldmann/ -------
Hello Johannes, Tuesday, October 25, 2005, 6:51:21 PM, you wrote: JW> Bulat Ziganshin wrote:
one more suggestion - i think that we must include in GHC distribution useful TH application libraries: printf, class derivation (a la DrIFT)
JW> I'd love that. Are there any such libraries at the moment? Somewhere? http://www.haskell.org/th/papers/Template_Haskell-A_Report_From_The_Field.ps which is mentioned at http://www.haskell.org/th/ -- Best regards, Bulat mailto:bulatz@HotPOP.com
On 10/25/05, Simon Peyton-Jones
TH seems to have had quite a bit less impact than I originally thought it might, given that it provides something qualitatively new. But maybe I'm wrong. For example, I didn't know that it was important to you. Maybe there are others.
I also use TH, mostly to generate instances of some classes and for things like interpolation (this is the word they use in Perl-world for this - I've used Perl several years ago) of variables in String literals. Probably not the most sophisticated uses, but they sure make writing (some kinds of) code much easier. There are probably many things that could be done to make TH more useful, and hopefully also more popular. Here are some I thought about: - allow to use TH to create rules for deriving instances of user defined type classes - so the end user doesn't have to know about TH - this is quite controversial, because on one hand it would make TH less visible, but on the other, library writers would be more willing to use it - allow to use TH as a kind of preprocessor, so TH-preprocessed source can be loaded by other compilers - bridge that gap between ADTs used in TH and haskell-src(-exts), so, for example, I could parse parts of String literals as Haskell. - alternatively, allow to splice inside String literals ;-) - allow to use syntaxes other than Haskell in quotations, for example, I would love to use Haskell to generate C++ (to improve Haskell/C++ ratio in my code). In other words, make TH an aid in using DSLs.
My current hope is to broaden the base of people who are willing to contribute to GHC themselves, with support from me and Simon, so that Simon and I aren't always on the critical path.
I would like to clarify that I don't expect Simon and you to do any of these. I am already amazed that you did so much :-) Best regards Tomasz
Hello Tomasz, Wednesday, October 26, 2005, 10:58:53 AM, you wrote: TZ> I also use TH, mostly to generate instances of some classes and TZ> for things like interpolation (this is the word they use in Perl-world TZ> for this - I've used Perl several years ago) of variables in String literals. can you publish these modules with examples of usage? one of TH problems is severe lacking of light examples of its usage TZ> There are probably many things that could be done to make TH TZ> more useful, and hopefully also more popular. Here are some I TZ> thought about: TZ> - allow to use TH to create rules for deriving instances of TZ> user defined type classes - so the end user doesn't have TZ> to know about TH - this is quite controversial, because on TZ> one hand it would make TH less visible, but on the other, TZ> library writers would be more willing to use it i' m also think about this. smth like expansion of: data T = ... deriving (GhcBinary) to data T = ... $(deriveGhcBinary ''T) -- Best regards, Bulat mailto:bulatz@HotPOP.com
On 10/26/05, Bulat Ziganshin
can you publish these modules with examples of usage? one of TH problems is severe lacking of light examples of its usage
I'll try. I will put it on my website... if I ever get to putting some content on it. BTW, usually I don't like the way my TH code looks - that's probably because it's very different from "ordinary" Haskell code, and I don't write much of it (there are always more uses then definitions), so I didn't have a chance to improve my style. I wonder how other people feel about it. Best regards Tomasz
Simon Peyton-Jones wrote:
The reason I have not done anything about it is that there's very little traffic on the Template Haskell list (or any other, about TH), and that has de-motivated me so far as improving TH is concerned.
I WANT to use TH, but I don't. Here are several reasons: 1. The documentation is poor, and writing my own documentation to a changing API is frustrating. 2. Haskell is making very quick progress - many people have shown how GADTs and existential types overlap, and perhaps we could have hacked up some sort of GADTs in TH, but we didn't have to. Someone has hacked up TH versions of Generic Haskell and PolyP (or Starfunski), but those tools already exist in the wild. In addition, some analysis I might use TH for can be done in other ways, like the projects that end up parsing Haskell in Haskell, or Programmatica, or GHC as a package. 3. TH is ugly by comparison. Those splices break my concentration. When I write a utility or library, I want it to be transparent to the user: I want it to look built-in. SYB is a great example of a beautiful utility. 4. For the things that #2 doesn't take care of, I don't know if TH can do. Chameleon and System CT are quite interesting, but can TH simulate that kind of behavior? I want impredicativity NOW (especially for type classes), and SPJ is working on it already -- why should I hack it up in TH only to create some weak or ugly syntax months after GHC has boxy types built-in? I know that #3 is my own issue to get over - a decision was made that Haskell metaprogramming would be more explicit than regular Haskell, and if I want it to be different, I can use Lisp or roll my own. But I thought I would (a) Offer some praise - TH is unused partially because GHC is so great (b) Explain that part of the reason I don't use TH is that there is no good documentation, and that's only because more people don't use TH, which may be only because there is no good documentation . . . Jim
participants (5)
-
Bulat Ziganshin -
Jim Apple -
Johannes Waldmann -
Simon Peyton-Jones -
Tomasz Zielonka