Michael Bayne
4b443fe148
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 Narya library
-----------------
The Narya library provides various facilities for making networked
multiplayer games. Its various packages include:
* geom, util, io - basic tools for doing networked I/O, data structure
manipulation and some geometry math
* resource - tools for bundling, deploying and managing media (images,
sounds, etc.) with a game
* media - a framework for doing "active" rendering in Java
* media.image - tools for loading, caching, manipulating and displaying images
* media.sound - tools for loading, caching, and playing audio
* media.animation, media.sprite - works in concert with the active
rendering system and provides tools for defining and manipulating
sprites (graphical entities that follow paths) and animations
(graphical entities that affect the display in other ways)
* miso - a framework for defining and displaying isometrically rendered scenes
* presents - a framework for distributing information among a server and
networked clients
* crowd - builds on the presents framework to create the notion of
bodies and rooms and provides chat infrastructure
* whirled - builds on the crowd framework and defines a scene graph with
portals to move between scenes and provides hooks for distributing and
updating scene data (for example isometric rendering information) over
the network
* cast - a framework for defining and using recolorable, composited
characters with different poses and actions
* parlor - builds upon the crowd framework to create the notion of a
game with players and provides tools for making turn based games
* puzzle - builds on the parlor and media frameworks to provide tools
for implementing puzzle games in a networked environment
* micasa - builds on the parlor framework to provide lobbies and
matchmaking for multiplayer games
Documentation is somewhat sparse at the moment, but inspection of the code
in the tests/ directory shows examples of use of many features of the
library.
Building
--------
Building the library is very simple. First ensure that the necessary third
party jar files are available either in the lib/ directory or in the
system wide jar file location specified in build.xml. See lib/README for a
list of the necessary third party jar files and how to get them.
The library is built using ant, a modern build tool available from The
Jakarta Project. If you aren't already using ant for other projects, it
can be found here:
http://jakarta.apache.org/ant/
Invoke ant with any of the following targets:
all: builds the distribution files and javadoc documentation
compile: builds only the class files (dist/classes)
javadoc: builds only the javadoc documentation (dist/docs)
dist: builds the distribution jar files (dist/*.jar)
Distribution
------------
The Narya library is released under the LGPL. The most recent version of
the library is available here:
http://code.google.com/p/narya/
Contributions and Contact Information
-------------------------------------
Narya is actively developed by the scurvy dogs at Three Rings Design, Inc.
Contributions are welcome.
Questions, comments, contributions, and other worldly endeavors can be
handled in the Google Group for Three Rings libraries:
http://groups.google.com/group/ooo-libs
$Id$