Powerful text interpolation with rise

2 minute read
Projects

Throughout my career I have had many times where I have needed to perform text interpolation, or templating, on files. Over the years, I have generally stuck to either envsubst or m4 which have performed admirably. However, there were a few issues that I felt they either didn’t solve easily. Some of these are:

  • Cross-platform support
    • Although they can be used across Linux/Windows/Mac, the installation differs greatly between each
  • Limited capabilities
    • In the case of envsubst, it can only replace environment variables
    • Although m4 is far more powerful, the syntax can be very confusing to someone that has not used it often

After using Terraform’s configuration syntax for a little while, I admired the simplicity in which the syntax was formed and the powerful capabilities it provided. However, it was part of the Terraform toolchain and could not be used on specific files. This was when I decided to build my own text interpolation tool, rise.

This post will provide a very quick overview of the concepts and some links to project for further reading.

Simple Usage

There are two main concepts in rise. Config files and template files. A config file contains all of the different configuration that can then be utilised in a template file. The template file is the text to perform the interpolation on.

A simple example of a config file is as follows:

1variable "i" {
2  value = 6
3}

This simply declares a variable i, with a default value of 6. More details on the syntax of a configuration file can be found at the HCL project page.

A simple example of a template file is as follows (note that this file is JSON, but could be any syntax):

1{
2  "i": ${var.i}
3}

It’s a simple JSON structure, that will set the value of the key i, to the value from the configuration above.

If the config file was located at vars.hcl and the template at input.json, we could perform interpolation as follows:

1rise -i ./input.json -o ./output.json --config ./vars.hcl

The contents of output.json should now read:

1{
2  "i": 6
3}

Advanced Usage

There are a number of interpolation functions that can be used to perform complex actions. Here is a quick example to showcase a few of them.

Our config file, vars.hcl:

1variable "animals" {
2  value = ["dog", "cat", "cow"]
3}
4
5template "title" {
6  content = "We are going to list some animals now!"
7}

Our template file, input.txt:

1${tmpl.title}
2
3${join(", ", var.animals)}

Let’s run rise!

1rise -i ./input.txt -o ./output.txt --config ./vars.hcl

The result:

1We are going to list some animals now!
2
3dog, cat, cow

There are many other interpolation functions that what was shown here. They can all be found in the rise docs.

If you wanted to know more about rise checkout the GitHub page, and the docs.