util.interpolation implements a string template language, primarily meant for interpolation of variables into HTML.

An example:

local st = require"util.stanza"
local render = require"util.interpolation".new("%b{}", st.xml_escape);
local template = [[
<p>Hello, {name}! Welcome to {here}.</p>
print(render(template, { title = "Welome", name = "Alice", here = "wonderland" })


The module exposes a single new() function, which takes 2 or 3 arguments and returns a renderer function.

The first argument is the pattern that signifies variables. The first capture must have exactly one character before and after the variable name. It is recommended to use the %bxy pattern construct. To allow a longer pre- or suffix, a capture can be used around the inner two characters, so a longer pattern may be "\\var(%b{})" for \var(variable).

The second argument must be an escaping function for the target text format. For HTML or XML the xml_escape function from util.stanza is suitable. To disable escaping, simply pass function(x) return x end.

The third argument is an optional table of filter functions. See the Filters section below.

The returned function takes two arguments, a template string and a table of variables.


No escaping

To pass a variable through raw, without escaping, put an exclamation mark as last character: {foo!}.

Optional variables

Normally, if a variable used in the template is left out, the original template text is passed through unchanged. This can be changed by including a question mark: {foo?}, then the entire expression will be removed in the output.

This fallback text can contain nested template expressions, like {foo?empty, but {bar}}.

template input output
{foo?bar} {foo="hi"} "hi"
{foo?bar} {foo=""} ""
{foo?bar} {} "bar"
{foo?bar} {foo=false} "bar"

Conditional subtemplate

Similar to fallback text, but the other way around: {foo&the variable foo is {foo}}.

template input output
{foo&bar} {foo="hi"} "bar"
{foo&bar} {foo=""} "bar"
{foo&bar} {} ""
{foo&bar} {foo=true} "bar"
{foo&bar} {foo=false} ""

To insert text when a variable is falsy, without using the variable itself, use {foo~the variable is falsy}, which renders to the empty string when foo is truthy, unlike {foo?fallback}. (the ~ syntax added in 0.12)

template input output
{foo~bar} {foo="hi"} ""
{foo~bar} {foo=""} ""
{foo~bar} {} "bar"
{foo~bar} {foo=true} ""
{foo~bar} {foo=false} "bar"

Iterating over arrays and maps

To render a list of things using the same template the expression {list#subtemplate with {idx} and {item}} can be used. Each item will be available in the sub-template as an item variable, and its index will be idx.

local template = [[
<li id="item-{idx}">{item}</li>}
print(render(template, { items = { "lorem", "ipsum", "dolor", "sit", "amet" } }))

Iterating over arbitrary key-value tables is done like {table%{idx} = {item}}.


The third argument to new is a table of filter functions. To invoke these, the pipe symbol is used, like {foo|uppercase}. Multiple filters may be chained. The filter functions get the input as one argument. Returning nil cancels further chained filters. May be combined with one final modifier.