Well over a year ago, I mentioned that I was working on a Velocity bundle for Textmate. Or, to be more precise: I mentioned that I’d already written one that we were using at NPG.

A year later, I’m ready to release the bundle; you can get it from its Google Code site. But before you go there, an explanation for the delay is in order – and on the way, I’ll tell you about how the bundle was written.

TextMate is a wonderful, wonderful editor, and there’s always something new to learn about it. One of the best resources for it is James Edward Grey’s excellent book, published by the Pragmatic Programmers. JEG takes the attitude I do: TextMate is not about nifty bundles and shorcuts – it’s about the power under the hood that makes them possible. So his book won’t teach you nifty auto-completion shortcuts, because you can work them out for yourself. His book will teach you how to write your own. Despite using Textmate for over a year, I learned something on every page of the book.

Anyhow, when I originally wrote the language grammar for TextMate, I reversed-engineer how they work by looking at a few bundles. I then reverse-engineereed how Velocity works from looking at our source files, and bodged together a grammar that roughly worked.

Can you see the leaky abstraction yet?

It worked, but not perfectly. The snippets worked fine, of course.

Anyhow, come this month, I decided it was due a proper rewrite and a proper release. So I read the chapter in JEG’s book on writing language grammars. It’s a brilliant chapter. JEG takes the reader through writing a complete grammar for JSON, which is a good choice, because it’s a fairly succinctly defined language. I followed that through, and then applied the principles to my Velocity grammar.

As well as approaching the grammar the right way, I approached Velocity the right way, too. I started with the language documentation, which is reasonably short – it is, after all, a templating language. The language documentation is great – it provides definitions and examples. I used each example as a test case, writing grammar rules based on the definitions, and checking it all checked out.

(A note on TextMate language grammars – they’re not that hard to write. But they’re not easy. Their rule-structure is a little like CSS, I guess, with the way it cascades, but its concept of “repositories” – patterns that can be reused – is nice and powerful. On top of that, it will really push your regular expressions skills. But beyond that, it’s all doable, especially for little things like templating languages.)

A few tweaks after some real-world testing, and I ended up with a releasable version of the bundle. By going about things the right way, I produced something far more robust. And learned a whole lot more.

So, the moment you’ve all been waiting for: the TextMate Velocity bundle. You’ll need to check it out from Google Code (svn checkout http://txm-vtl-bundle.googlecode.com/svn/trunk/ txm-vtl-bundle), and then double-clicking it should open it in TextMate. Everything else should be self explanatory. Please do log bugs on the Google Code site, so I can try to keep it vaguely up-to-date, and suggestions for snippets are always welcome. It also works in e – what many people use at work – if you’re not on a Mac yet.

Apologies for the delay. Hope the few people who will find this useful really do find it useful!