Specification

Table of Contents

  • What is it: templater
  • Syntax: twig, jinja, django, liquid
  • Language: Lua 5.1+
  • Dependency: none
  • Compiler: simple tokenizer + AST
  • Unittest: busted

Limitations #

  • New (local) variables cannot be called by the following names (by internal limitation): and, break, do, else, elseif, end, false, for, function, if, in, local, nil, not, or, repeat, return, then, true, until, while. These keywords generate error during compile.

Working with keys #

Keys sequence a.b.c returns nil if variable a or any other keys (b or c) doesn’t exits. The sequence of keys {{ a.b.c }} may be represented as lua code

if a and is_table(a) and a.b and is_table(a.b) and a.b.c then
    return a.b.c
else
    return nil
end

Working with strings #

In case the value should be converted to a string.

{{ data }}
Value String evaluation Info
nil empty string  
cjson.null empty string see cjson
cbson.null() empty string see cbson
lyaml.null empty string see lyaml
yaml.null empty string see yaml
ngx.null empty string see ngx_lua
msgpack.null empty string see msgpack
box.NULL empty string see tarantool box
other value tostring(...)  

You may configure empty-string behavior.

Working with numbers # 

{{ data + 2 }}
Value Number evaluation Info
empty string 0  
string “0” or ‘0’ 0  
false 0  
true 1  
any table 0  
nil 0  
userdata tonumber(tostring(...)) if result is nil then 0 will be used
string tonumber(...) if result is nil then 0 will be used

You may configure number behavior.

Working with booleans #

The rules to determine if an expression is true or false are (edge cases):

{% if data %}
...
{% endif %}
Value Boolean evaluation Info
empty string false  
other string true  
numeric zero false  
whitespace-only string true  
string “0” or ‘0’ true  
nil false  
table with __toboolean __toboolean()  
table with __len __len() ~= 0  
empty table false  
non-empty table true  
cjson.null false see cjson
cjson.empty_array false see cjson
cbson.null() false see cbson
cbson.null() false see cbson
cbson.array() false see cbson
lyaml.null false see lyaml
yaml.null false see yaml
ngx.null false see ngx_lua
msgpack.null false see msgpack
box.NULL false see tarantool box
userdata with __toboolean __toboolean()  
userdata with __len __len() ~= 0  

Functions __toboolean() and __len() should be a part of the metatable.

You may configure false behavior.

Working with cycles #

Aspect supports iterators from Lua 5.2+ versions for Lua 5.1 and LuaJIT versions.

{% for key, value in data %}
...
{% endfor %}
Value Action
string not iterate
empty table not iterate
number not iterate
nil not iterate
true/false not iterate
userdata with __pairs iterate with __pairs()
userdata not iterate
table with __pairs iterate with __pairs() instead of pairs()
other table iterate with pairs()

The function __pairs() should be a part of the metatable and compatible with basic function pairs() (returns iterator, key, value)

Working with counting #

When it is necessary to count the number of elements (filter length or variable loop.length).

{{ data|length }}
Value Number evaluation
string string.len(...)
empty table 0
number 0
nil 0
true/false 0
userdata 0
table with __len __len(...)
table with __pairs invoke __pairs() and count elements
other tables count of keys
userdata with __len __len(...)
userdata with __pairs invoke __pairs() and count elements