On Learning StringTemplate

I have been thinking lately about the learnability (the ease with which something can be learned) of StringTemplate. I like StringTemplate and would like to see more people make use of it. To that end I think there are some things that can help make it easier for people to get started with it.

StringTemplate is both a language for describing text generation and a tool (template engine) that implements that language and provides an API to connect the tool to another program.

StringTemplate is not a general purpose language and cannot stand on its own. By design it has no way to perform general computation. It also has no general way to create data and limited ability to specify literal data. It is up to some driving program to produce and or make data available to the StringTemplate template engine. This is not a negative – this is it’s strength. See this excellent paper for why.

However, the lack of readily available data makes learning the template language difficult without also learning the StringTemplate API. In order to try StringTemplate out one must learn the template syntax and semantics, and the API and then write a program to produce some data and call the template engine.

In theory one benefit of the separation of presentation from business logic is that a project can be divided between people who work on the business logic (the program) and people who work on the presentation (the templates). The people working on presentation don’t need to be programmers.

The current documentation for StringTemplate describes both the template syntax and the Java API at the same time. In some cases it is confusing to learn two things at once and more importantly it excludes non-programmers from learning StringTemplate.

In contrast, trying out XSLT is is easy (even if mastering XSLT is hard) because all you need is a text editor to create both your input documents and your style sheet and an XSLT program to process the style sheet with the input documents. Likewise trying out HTML is easy, all you need is a text editor and a browser. Interpreted languages like Python that have an interactive mode also make it easy to jump right in and get the feel of things. (I’m not saying that StringTemplate is like XSLT, HTML or Python, I’m just comparing the ease with which one can dive in and try the technology out.)

So what StringTemplate needs is a literal representation for data that can be used as input and a stand alone program to read the data and templates to produce the output text.

I choose JSON as the literal data format. The reasons are:

  • Its a standard
  • It is becoming increasingly well known
  • It is easy to type in and not overly verbose
  • I had already made changes to get a Java JSON library to play nice with StringTemplate.
  • It supports all the data shapes that StringTemplate works with.

I created a command line tool called StringTemplate Standalone Tool (STST). It takes as input the name of a file containing data in JSON format, the name of a template and optionally the name of a group as well as various options.

Look ma, no programming.

Here is a simple example of how it is used.

Create a JSON file called data.js with this content:
{ "audience": "World" }

Create a StringTemplate file called first.st with this content:
Hello $audience$!

From a command prompt in the same folder as the above two files type
> stst first data.js
The output is
Hello World!

It also works with group files and can use the angle bracket lexer. For command usage type: stst -h

The next thing StringTemplate needs is a tutorial that focuses on the template syntax independent of the API. STST enables this kind of tutorial. Separate documentation can focus primarily on the API.

Download STST here

This tool can have other uses as well. Here are some ideas:

  • It is a quick way to try out template syntax without having to write or modify a program. This can benefit seasoned template authors as well as beginners.
  • It could be part of a test framework for StringTemplate itself or for a set of templates in an application. The templates can easily be processed with known data and the expected results asserted.
  • It enables development of the templates before or in parallel with code by creating a JSON data file that represents what the code will produce.
  • It could be used as part of shell scripts where some existing program outputs JSON data and STST is used to generate text from it. The data could come from a web service for example.

What could you use it for?

Future possible directions for STST

  • Integrate the functionality into an IDE for StringTemplate
  • Expose the functionality in an interactive servlet (web app).
  • Support other data formats like CSV, YAML, or XML
  • More support for renderers

I Like Python

I recently started learning Python and to my surprise find it to be a very nice language.

I had heard good things about it years ago but never gave it a look. I noticed that Joel Spolsky gave Python half credit as a safe choice of language to develop enterprise applications in. Still, I was (and still am) happy working in Java.

What prompted me to look at Python is my new Job. I now work at BEA. The BEA WebLogic Server has a tool for configuring and managing domains called WebLogic Scripting Tool (WLST). WLST is based on Jython (Jython is Python implemented in Java).

I started reading a Python tutorial. The first thing I noticed is that code blocks are identified by indenting. This seemed very strange and uncomfortable after years of using curly brackets. Now it makes sense to me. I was going to indent my code anyway so why shouldn’t the language make use of that fact. A side benefit is no more arguing over if the curly brackets belong on the same line or a new line. If arguing about code style floats your boat be comforted that you can still argue over how many spaces to indent.

So far I have created two small utility programs in Python. One gathers some information about files and outputs an XML file. The other processes an XML file using SAX and outputs a new XML file. (I didn’t use XSLT because I needed to write files, run a program and include it’s output as new element content.) Even with the learning curve I was able to write these programs faster then I could have in Java. Also the code is much smaller than their Java counter parts would be.

Some things I like about Python:

  • Simple but powerful syntax is quick and easy to learn. It seems to me to be minimally complete. In other words it doesn’t have lots of unnecessary junk.
  • Very good documentation including tutorials.
  • The interactive interpreter makes it easy to try things out. This facilitates learning.
  • Like JavaScript, Python has a syntax for creating rich literal data structures. It is so much easier to do this:
    fruit = { "apples": [ "Cortland", "Braeburn"], 'pears': [ "Bartlett", "Bosc" ] }

    Than it is to do this:

    HashMap fruit = new HashMap();
    ArrayList apples = new ArrayList();
    apples.add("Cortland");
    apples.add("Braeburn");
    ArrayList pears = new ArrayList();
    pears.add("Bartlett");
    pears.add("Bosc");
    fruit.put("apples", apples);
    fruit.put("pears", pears);

  • List comprehension – a concise syntax to make new lists from existing lists without the usual for loop. Example: [ x**2 for x in range(5) ] produces this list: [0, 1, 4, 9, 16]
  • An extensive standard library of functions and classes.
  • The map() and reduce() functions.

Python will replace Perl as my scripting language of choice.