Module

tuck

src/tuck.pooka

A 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.

Pooka
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

enum

Escape

src/tuck.pooka:44
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.
variant

Html

src/tuck.pooka:45
Escape.Html
variant

Plain

src/tuck.pooka:46
Escape.Plain
class

Template

src/tuck.pooka:50
class Template(name: String, escape: Escape, document: Document)

A template that has been read and checked, ready to render.

field

name

src/tuck.pooka:50
name: String
INFERREDString
field

escape

src/tuck.pooka:50
escape: Escape
INFERREDtuck.Escape
field

document

src/tuck.pooka:50
document: Document
constructor

new

src/tuck.pooka:50
class

Library

src/tuck.pooka:54
class 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.

field

templates

src/tuck.pooka:55
templates: List(#(String, Template))
INFERREDList(#(String, tuck.Template))
field

filters

src/tuck.pooka:56
filters: List(#(String, Filter))
INFERREDList(#(String, tuck/filter.Filter))
field

functions

src/tuck.pooka:57
functions: List(#(String, Function))
INFERREDList(#(String, tuck/function.Function))
constructor

new

src/tuck.pooka:55
INFERREDfn(List(#(String, tuck.Template)), List(#(String, tuck/filter.Filter)), List(#(String, tuck/function.Function))) -> tuck.Library
function

parse

src/tuck.pooka:69
parse(source: String) -> Result(Template, TuckError)
INFERREDfn(String) -> Result(tuck.Template, tuck/error.TuckError)

Read a template from text. It is called template in error messages, and escapes for HTML.

Pooka
import tuck

let assert Error(problem) = tuck.parse("{% if %}")
assert tuck.describe(problem) == "template:1:7: expected a value, found `%}`"
function

parse_named

src/tuck.pooka:75
parse_named(name: String, source: String, escape: Escape) -> Result(
  Template,
  TuckError
)
INFERREDfn(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.

function

render

src/tuck.pooka:96
render(template: Template, data: Json) -> Result(String, TuckError)
INFERREDfn(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.

Pooka
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;")
function

library

src/tuck.pooka:119
library() -> Library
INFERREDfn() -> tuck.Library

A library with no templates yet.

function

add

src/tuck.pooka:133
add(library: Library, name: String, source: String) -> Result(
  Library,
  TuckError
)
INFERREDfn(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.

Pooka
import tuck

let assert Ok(pages) = tuck.library()
  |> tuck.add("base.html.tuck", "<main>{% block body %}{% endblock %}</main>")
function

load

src/tuck.pooka:153
load(folder: String) -> Result(Library, TuckError)
INFERREDfn(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.

function

with_filter

src/tuck.pooka:222
with_filter(
  library: Library,
  name: String,
  run: fn(Json, List(Json)) -> Result(Json, String)
) -> Library
INFERREDfn(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.Library

Add a filter of your own. It receives the value and any arguments, and returns the new value or a sentence about what went wrong.

Pooka
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)
function

template

src/tuck.pooka:240
template(library: Library, name: String) -> Option(Template)
INFERREDfn(tuck.Library, String) -> Option(tuck.Template)

The template called name, if the library has it.

function

render_named

src/tuck.pooka:257
render_named(library: Library, name: String, data: Json) -> Result(
  String,
  TuckError
)
INFERREDfn(tuck.Library, String, $package/pooka_json/pooka/json.Json) -> Result(String, tuck/error.TuckError)

Render the library's template called name.

Pooka
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, &lt;Ada&gt;</main>")
function

escape_for

src/tuck.pooka:307
escape_for(name: String) -> Escape
INFERREDfn(String) -> tuck.Escape

How a template named name escapes: Html for HTML, XML and SVG templates, Plain for anything else.

Pooka
import tuck

assert tuck.escape_for("pages/home.html.tuck") == tuck.Escape.Html
assert tuck.escape_for("emails/welcome.txt.tuck") == tuck.Escape.Plain
function

describe

src/tuck.pooka:323
describe(problem: TuckError) -> String
INFERREDfn(tuck/error.TuckError) -> String

A problem as one line: name:line:column: what went wrong.

function

parse_checked

src/tuck.pooka:360
parse_checked(
  name: String,
  source: String,
  escape: Escape,
  budget: limits.Budget
) -> Result(Template, TuckError)
INFERREDfn(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.

Pooka
let page = tuck.parse_checked("home.html.tuck", "Hi, {{ name }}", tuck.Escape.Html, limits.defaults())
function

render_checked

src/tuck.pooka:375
render_checked(template: Template, data: Json, budget: limits.Budget) -> Result(
  String,
  TuckError
)
INFERREDfn(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.

Pooka
let assert Ok(page) = tuck.parse("Hello")
assert tuck.render_checked(page, json.JObject([]), limits.defaults()) == Ok("Hello")
function

render_named_checked

src/tuck.pooka:387
render_named_checked(
  library: Library,
  name: String,
  data: Json,
  budget: limits.Budget
) -> Result(String, TuckError)
INFERREDfn(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.

function

load_checked

src/tuck.pooka:423
load_checked(folder: String, budget: limits.Budget) -> Result(
  Library,
  TuckError
)
INFERREDfn(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.

function

with_function

src/tuck.pooka:437
with_function(
  library: Library,
  name: String,
  run: fn(List(Json)) -> Result(Json, String)
) -> Result(Library, TuckError)
INFERREDfn(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.

Pooka
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)