Introduction to Textrude - what and why

Code generators
1

Here’s a short introduction to a tool I wrote that may be of interest to others here.

Textrude sits firmly in the ‘templating’ part of the code-generation spectrum. That is to say that it transforms simple data models into textual output via a template containing a mixture of textual scaffolding and control logic. It’s really intended as a “front end” for a compiler; I typically use it to generate “boilerplate” source code from data-sets such as lists of error codes.

If that sounds a bit abstract, here’s an actual example:

Model:

name,cost
laptop,1000
monitor,400

Template:

{{for item in model}}
const int {{item.name}} = {{item.cost}};
{{end}}

Output:

const int laptop = 1000;
const int monitor = 400;

The first notable thing here is that the model schema is automatically derived and made available to the template engine. I used a CSV model here but Textrude also understands JSON and YAML and supports “dotting into” structured models.

The template language is Scriban which provides a reasonable trade-off between text/control switching and power. Textrude supports template function libraries so it’s feasible to build up a pseudo-DSL to reduce the amount of 'surface template code.

The tool aims to address a couple of my pet peeves with code-generation in “real world” environments.

Firstly, it’s designed with build-system integration in mind; it has its own (weak) dependency checking mechanism built in and templates can easily access environment variables (e.g. to stamp generated code with a commit or branch id).

Secondly, it aims to dramatically reduce the length of the feedback cycle when developing templates and models. The UI version of the tool allows output to be generated on every change to the model or template. It’s therefore possible to evaluate the correctness of the template in real-time as it is edited.

If this sounds interesting, you can check it out on github. It’s just a “spare time” project so has a few rough edges but feel free to raise an issue or even submit a PR if you want.

3 Likes
2

Nice to see new approaches in this area.
Any comparison with respect with StringTemplate?

2 Likes
3

Thanks - that’s an interesting link. From a brief exploration of the StringTemplate documentation (so I could be wrong and happy to be corrected!) I’d draw the following comparison points…

Firstly, the general philosophy appears to be very similar. i.e. ‘models’ are simple data representations. Any logical operations are encapsulated in the template that operates on the model. However I think there is a difference in scope.

To build something like Textrude you need:

  • an input layer that can parse model files in various formats (currently CSV, JSON, YAML, line-based) and build a common internal object representation (and ideally inject things like environmental variables and user-supplied definitions into the model).
  • a templating engine that can be applied to the constructed representation and emit a textual representation
  • various bits of logic to manage dependency tracking.
  • for the UI aspect there are other useful considerations such as the ability for the templating engine to be interrupted, and to behave well when presented with partial input.

StringTemplate appears to be a templating engine whereas Textrude is intended to be a fully-functional tool. In principle Textrude could have used the StringTemplate engine internally if I’d known about it earlier - indeed an early prototype used the Razor engine.

That said, I think the Scriban language (which is the work of Alexandre Mutel) has some pretty good features including the ability to use libraries and to generate multiple output streams, both of which were important to me as well as a nice syntax which includes a pipe operator and detection of first/last conditions in loop (helpful for addressing the “trailing comma” problem). It’s also relatively easy to inject extension functions which makes it simple to provide things like Humanizer functions to do camel-casing etc.

So to summarise…

  • If you’re familiar with StringTemplate you’ll ‘get’ the concept of Textrude.
  • If you want to see how the template generation compares then you should take a look at the Scriban language documentation.
  • Textrude is really the combination of a templating engine with lots of glue logic to provide (IMO!) a quick and easy way to generate output. Because all the model-parsing is done “for free” it’s also very easy to turn Textrude into a query engine. E.g.
#print out just the records that match the query
textrude.exe iFilter -e "(i.Population >100) && (contains i.Country 'United')" -i countries.json

Of course, the source is also structured to make it easy to wrap then internal logic in a different application if you have specific requirements - I have an ongoing project to release the engine as a separate Nuget package.

1 Like