Google's CTemplate) and got all hot and bothered, because it seemed like it
would be sufficiently powerful to replace Velocity for our Narya templating
needs.
I then sought out a Java implementation and found one, and quickly discovered
that it lacked the right level of awesome for my needs. So I foolishly decided
to write my own, because Mustache seemed simple enough that I could reimplement
it in a few hours.
A few hours later, I had a neat and tidy reimplementation of Mustache and then
set about to converting Narya to using it. Then the fun began.
I discovered that Mustache wants everything in a hash, but sometimes you just
want to iterate over the elements of a list, and print them into the template
whole-hog. So I extended Mustache with the special "this" variable for printing
the whole context instead of pulling values out of it by name.
Then I remembered that Velocity allows you to do a deep dive into objects,
calling methods and calling methods on the return values of those methods.
Velocity even allows you to pass constants as arguments to those methods (true,
strings, integers). Well, I reimplemented the compound keys, so that you can
call foo.bar.baz, but I didn't go so far as to support constant arguments. That
seemed a step too far into complexity land and to be the sort of thing that
Mustache tries to avoid. So with compound keys, I just had to add a few
alternative versions of methods we were already calling, since we only ever
passed true/false as an argument.
Then I realized that Mustache doesn't do any smart trimming of newlines, so if
you have:
{{#stuff}}
blah blah
{{/stuff}}
You get the annoying newline after the open-tag and after the close-tag. So I
modified my implementation to trim newlines in those circumstances, so that
template authors don't have to do a bunch of template-weirding whitespace
jockeying.
Then I discovered that Mustache doesn't support any notion of scope. So when
you're inside a so-called section, the only variables visible are those bound
by that section. The stuff outside the section is totally invisible. Well,
that's not how Velocity works, you can reference things outside your loop
iterations. It seemed no terribly affront to Mustache to make things work that
way as well, so I did that.
Then I discovered a problem with the fact that Mustache implicitly binds the
loop object to the root of the namespace, so if you have {{name}} outside the
loop and then your loop object also contains a {{name}} field, then you can't
see the outside {{name}} anymore because it's shadowed. Tough titties, in this
case, I just changed our code to not shadow the name.
Then I encountered a bunch of uses of $vidx to put a space before all but the
first element of a list. So I added two more special variables -first and -last
which allow you to do just that sort of thing (and more) in a more template
friendly way because you don't need a Turing complete language just to decide
whether or not you need to mind the gap.
Then I encoutered some uses of $vidx directly, where we were using it to assign
constants in invocation service related classes. So I added another special
variable -index which resolves to basically the same thing that $vidx resolves
to (a 1-based counter indicating which element you're on in your list
iteration). I rationalized to myself that if you wanted to automatically number
laundry lists in your templates, having -index would be nice.
Finally, I have Narya's templating stuff producing character-for-character
replicas of what it used to do with Velocity. Well, actually there's one
newline in a place where there didn't used to be one, but I think that newline
makes sense and it was maybe some sort of Velocity bug that caused it not to
exist.
I've tested the gendobj, genservice and genreceiver tasks. I have no tested
whatever uses streamable_as.tmpl, but I'm pretty confident that it will work
exactly as before because I modified hundreds of lines of other templates in
exactly the same ways and they all work just fine.
So the world gets yet another templating library:
http://code.google.com/p/jmustache/
git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@6218 542714f4-19e9-0310-aa3c-eee0fc999fb1
The @Generated annotation showed up in JSR-250 and then was bundled into
Java 1.6. For those of us stuck in a 1.5 world, there's fortunately a
nice tiny little jar with the necessary classes, so slurp that in.
git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@6057 542714f4-19e9-0310-aa3c-eee0fc999fb1
Michael Bayne