HewDocumentation 0.9.3

Module std.text.template

Go-style text/template rendering.

Parse a template string with parse, then render the compiled Template against a Ctx value. Directives inside {{...}} are substituted; all other text passes through verbatim.

Supported directives

DirectiveMeaning
{{.key}}Substitute the scalar bound to key in the context
{{.}}Substitute the current element (inside {{range}})
{{if .key}}...{{end}}Render body only when key is non-empty/non-zero
{{if .key}}...{{else}}...{{end}}Conditional with else branch
{{range .key}}...{{end}}Iterate a list; inside the body . is the item

Errors

parse and render_template return TemplateError: UnclosedDirective, UnclosedBlock, UnexpectedTag, DotOutsideRange, or UnknownDirective.

Method-style rendering

Render with template.render_template(t, ctx).expect("template renders").

Data model

The context is a flat Ctx value with two independent parallel-vector maps:

Values are strings, integers, booleans, or flat lists of strings. Nested lists and maps are outside this API.

Examples

import std.text.template;

fn main() {
    var ctx = template.new_ctx();
    ctx.set_str("name", "Alice");
    ctx.set_int("age", 30);
    var items: Vec<string> = Vec.new();
    items.push("red");
    items.push("green");
    ctx.set_list("colours", items);

    let t = match template.parse("Hello {{.name}}, age {{.age}}!") {
        .Ok(template) => template,
        .Err(_) => panic("template parse failed"),
    };
    let result = template.render_template(t, ctx);
    match result {
        .Ok(s) => println(s),
        .Err(_e) => println("template render failed"),
    }
}

Contents

Functions

Function parse

pub fn parse(src: string) -> Result<Template, TemplateError>

Parse and validate a template string.

Function render_template

pub fn render_template(t: Template, ctx: Ctx) -> Result<string, TemplateError>

Render a compiled template, returning a structured error on failure.

Function new_ctx

pub fn new_ctx() -> Ctx

Create an empty rendering context.

Examples

import std.text.template;

fn main() {
    var ctx = template.new_ctx();
    ctx.set_str("greeting", "hello");
}

Function render

pub fn render(tmpl: string, ctx: Ctx) -> string fails TemplateError

Render tmpl against ctx, returning the substituted string on success.

Fails with a TemplateError if the template is malformed (unclosed {{, unmatched {{end}}, or {{.}} outside a {{range}} block).

Examples

import std.text.template;

fn main() {
    var ctx = template.new_ctx();
    ctx.set_str("who", "world");
    let t = match template.parse("hello {{.who}}!") {
        .Ok(template) => template,
        .Err(_) => panic("template parse failed"),
    };
    let r = template.render_template(t, ctx);
    match r {
        .Ok(s) => println(s),    // "hello world!"
        .Err(_) => println("template error"),
    }
}

Types

Struct Ctx

Template rendering context.

Construct with new_ctx(), then populate through the var self methods set_str, set_int, set_bool, and set_list; the binding must be var.

Fields

skeys: Vec<string>

Keys for scalar (string-valued) entries.

svals: Vec<string>

String-rendered values for scalar entries (parallel to skeys).

lkeys: Vec<string>

Keys for list entries.

litems: Vec<string>

Flat concatenation of all list items across all list entries.

lstart: Vec<i64>

Start index into litems for each list entry (parallel to lkeys).

llen: Vec<i64>

Item count for each list entry (parallel to lkeys).

Struct Template

Opaque compiled template.

Fields

src: string

Enum TemplateError

Structured template parse/render errors.

Variants

UnclosedDirective(string)
UnclosedBlock(string)
UnexpectedTag(string)
DotOutsideRange(string)
UnknownDirective(string)
DuplicateElse(string)

Inherent methods

impl Ctx

pub fn set_str(var self, key: string, val: string)

Bind key to the string val in the context.

Examples
import std.text.template;

fn main() {
    var ctx = template.new_ctx();
    ctx.set_str("name", "Alice");
}

pub fn set_int(var self, key: string, val: i64)

Bind key to the integer val (stored as its decimal representation).

Examples
import std.text.template;

fn main() {
    var ctx = template.new_ctx();
    ctx.set_int("count", 42);
}

pub fn set_bool(var self, key: string, val: bool)

Bind key to the boolean val ("true" or "false").

Examples
import std.text.template;

fn main() {
    var ctx = template.new_ctx();
    ctx.set_bool("active", true);
}

pub fn set_list(var self, key: string, items: Vec<string>)

Bind key to the list of strings items.

Inside a {{range .key}}...{{end}} block, each element is bound to {{.}}.

Examples
import std.text.template;

fn main() {
    var ctx = template.new_ctx();
    var colours: Vec<string> = Vec.new();
    colours.push("red");
    colours.push("blue");
    ctx.set_list("colours", colours);
}