Module
tuck
src/tuck.pookaA cozy little template engine: tuck your values into text.
Tuck reads templates with {{ values }}, {% if %}, {% for %},
includes and inheritance, and renders them with data from pooka/json.
Templates meant for HTML escape what they print, so a name like
<script> arrives as text, not as a surprise.
import pooka/json.{JObject, JString}
import tuck
let assert Ok(page) = tuck.parse("Hello, {{ name }}!")
let data = JObject([#("name", JString("Ada"))])
assert tuck.render(page, data) == Ok("Hello, Ada!")
For more than one template, put them in a Library: it reads each one
once, lets them include and extend each other, and renders them by name.
API reference
- enumEscape
- classTemplate
- classLibrary
- functionparse
- functionparse_named
- functionrender
- functionlibrary
- functionadd
- functionload
- functionwith_filter
- functiontemplate
- functionrender_named
- functionescape_for
- functiondescribe
- functionparse_checked
- functionrender_checked
- functionrender_named_checked
- functionload_checked
- functionwith_function
enum Escape
How printed values are made safe.
Html:&,<,>,"and'become entities. The default.Plain: values are printed exactly as they are, for text, Markdown or email bodies.
Escape.Html
Escape.Plain
class Template(name: String, escape: Escape, document: Document)
A template that has been read and checked, ready to render.
name: String
Stringescape: Escape
tuck.Escapedocument: Document
tuck/ast.Document
fn(String, tuck.Escape, tuck/ast.Document) -> tuck.Templateclass Library(
templates: List(#(String, Template)),
filters: List(#(String, Filter)),
functions: List(#(String, Function))
)
Templates that can include and extend each other, each read once, with custom filters and explicitly registered host functions.
templates: List(#(String, Template))
List(#(String, tuck.Template))filters: List(#(String, Filter))
List(#(String, tuck/filter.Filter))functions: List(#(String, Function))
List(#(String, tuck/function.Function))
fn(List(#(String, tuck.Template)), List(#(String, tuck/filter.Filter)), List(#(String, tuck/function.Function))) -> tuck.Libraryparse(source: String) -> Result(Template, TuckError)
fn(String) -> Result(tuck.Template, tuck/error.TuckError)Read a template from text. It is called template in error messages,
and escapes for HTML.
import tuck
let assert Error(problem) = tuck.parse("{% if %}")
assert tuck.describe(problem) == "template:1:7: expected a value, found `%}`"
parse_named(name: String, source: String, escape: Escape) -> Result(
Template,
TuckError
)
fn(String, String, tuck.Escape) -> Result(tuck.Template, tuck/error.TuckError)Read a template from text, with the name its errors will use and how it escapes.
render(template: Template, data: Json) -> Result(String, TuckError)
fn(tuck.Template, $package/pooka_json/pooka/json.Json) -> Result(String, tuck/error.TuckError)Render a template on its own. data must be an object; its fields are
the template's names. A template that includes or extends others needs a
Library.
import pooka/json.{JArray, JObject, JString}
import tuck
let assert Ok(list) = tuck.parse("{% for n in names %}{{ n }};{% endfor %}")
let data = JObject([#("names", JArray([JString("Ada"), JString("Bo")]))])
assert tuck.render(list, data) == Ok("Ada;Bo;")
library() -> Library
fn() -> tuck.LibraryA library with no templates yet.
add(library: Library, name: String, source: String) -> Result(
Library,
TuckError
)
fn(tuck.Library, String, String) -> Result(tuck.Library, tuck/error.TuckError)Add a template to a library, read from text. Names ending in
.html.tuck, .htm.tuck, .xml.tuck or .svg.tuck escape for HTML;
others print values as they are.
import tuck
let assert Ok(pages) = tuck.library()
|> tuck.add("base.html.tuck", "<main>{% block body %}{% endblock %}</main>")
load(folder: String) -> Result(Library, TuckError)
fn(String) -> Result(tuck.Library, tuck/error.TuckError)Read every .tuck file in a folder and its subfolders. Each template is
named by its path inside the folder, with / between the parts:
layouts/base.html.tuck.
with_filter(
library: Library,
name: String,
run: fn(Json, List(Json)) -> Result(Json, String)
) -> Library
fn(tuck.Library, String, fn($package/pooka_json/pooka/json.Json, List($package/pooka_json/pooka/json.Json)) -> Result($package/pooka_json/pooka/json.Json, String)) -> tuck.LibraryAdd a filter of your own. It receives the value and any arguments, and returns the new value or a sentence about what went wrong.
import pooka/json.{JString, Json}
import tuck
let shout = fn(value: Json, _args: List(Json)) {
match value {
JString(s) -> Ok(JString(s + "!"))
_ -> Error("`shout` needs text")
}
}
let pages = tuck.library() |> tuck.with_filter("shout", shout)
template(library: Library, name: String) -> Option(Template)
fn(tuck.Library, String) -> Option(tuck.Template)The template called name, if the library has it.
render_named(library: Library, name: String, data: Json) -> Result(
String,
TuckError
)
fn(tuck.Library, String, $package/pooka_json/pooka/json.Json) -> Result(String, tuck/error.TuckError)Render the library's template called name.
import pooka/json.{JObject, JString}
import tuck
let assert Ok(pages) = tuck.library()
|> tuck.add("base.html.tuck", "<main>{% block body %}{% endblock %}</main>")
let assert Ok(pages) = pages
|> tuck.add("home.html.tuck", "{% extends \"base.html.tuck\" %}{% block body %}Hi, {{ name }}{% endblock %}")
let data = JObject([#("name", JString("<Ada>"))])
assert tuck.render_named(pages, "home.html.tuck", data) == Ok("<main>Hi, <Ada></main>")
escape_for(name: String) -> Escape
fn(String) -> tuck.EscapeHow a template named name escapes: Html for HTML, XML and SVG
templates, Plain for anything else.
import tuck
assert tuck.escape_for("pages/home.html.tuck") == tuck.Escape.Html
assert tuck.escape_for("emails/welcome.txt.tuck") == tuck.Escape.Plain
describe(problem: TuckError) -> String
fn(tuck/error.TuckError) -> StringA problem as one line: name:line:column: what went wrong.
parse_checked(
name: String,
source: String,
escape: Escape,
budget: limits.Budget
) -> Result(Template, TuckError)
fn(String, String, tuck.Escape, tuck/limits.Budget) -> Result(tuck.Template, tuck/error.TuckError)Read a named template in a resource-bounded worker. Parser errors retain their exact location; resource failures name the entry point at line one.
let page = tuck.parse_checked("home.html.tuck", "Hi, {{ name }}", tuck.Escape.Html, limits.defaults())
render_checked(template: Template, data: Json, budget: limits.Budget) -> Result(
String,
TuckError
)
fn(tuck.Template, $package/pooka_json/pooka/json.Json, tuck/limits.Budget) -> Result(String, tuck/error.TuckError)Render a parsed template with bounded work, heap, time and final output.
let assert Ok(page) = tuck.parse("Hello")
assert tuck.render_checked(page, json.JObject([]), limits.defaults()) == Ok("Hello")
render_named_checked(
library: Library,
name: String,
data: Json,
budget: limits.Budget
) -> Result(String, TuckError)
fn(tuck.Library, String, $package/pooka_json/pooka/json.Json, tuck/limits.Budget) -> Result(String, tuck/error.TuckError)Render a library entry with the same resource boundary, including includes, inheritance, custom filters, and output generation.
load_checked(folder: String, budget: limits.Budget) -> Result(
Library,
TuckError
)
fn(String, tuck/limits.Budget) -> Result(tuck.Library, tuck/error.TuckError)Load a folder within a resource budget. The source-byte budget applies to each template; the work, heap and time budgets cover the whole operation.
with_function(
library: Library,
name: String,
run: fn(List(Json)) -> Result(Json, String)
) -> Result(Library, TuckError)
fn(tuck.Library, String, fn(List($package/pooka_json/pooka/json.Json)) -> Result($package/pooka_json/pooka/json.Json, String)) -> Result(tuck.Library, tuck/error.TuckError)Register an explicitly callable host function. Dotted names form namespaces; callbacks return ordinary typed JSON data and therefore retain autoescaping.
let clock = fn(args) { match args { [] -> Ok(json.JString("2026-11-16")) _ -> Error("expected no arguments") } }
let pages = tuck.with_function(tuck.library(), "time.now", clock)