22 The Ridgun Book

The `template` Lib — Safe Mustache Templates with HTML and LaTeX Auto-Escaping

22.1. Why Does the `template` Lib Exist? (The Real-World Problem & Ridgun Philosophy)

"Why do I need a template lib written from scratch in pure Ridgun instead of just linking a legacy C library?"

That is the first question every systems engineer asks when meeting template. And the answer captures the entire philosophy of ridgun-libs:

Let's be honest: assembling HTML pages or LaTeX reports by manual string concatenation is a textbook recipe for XSS vulnerabilities (<script>) or broken PDF builds the moment a user types % or _.

The template lib provides a logic-less Mustache engine with contextual auto-escaping (TmplPlain, TmplHtml, TmplLatex), explicit raw interpolation ({{{raw}}} / {{&raw}}), comments ({{! ... }}), truthy sections ({{#sec}}...{{/sec}}), and inverted sections ({{^sec}}...{{/sec}}).

In a traditional ecosystem, solving TMPL tasks means pulling in external C dependencies, wrestling with raw pointers, opaque type conversions, unchecked exceptions, or unpredictable garbage-collector pauses. In Ridgun, the template lib (src/main/ridgun/lib/template.rg) tackles the problem with four non-negotiable principles:

Declare import template (or import template as alias) at the top of your file: every lib defines its module :: template namespace, and under --strict multi-word functions are always called with natural spaces.
Chain your data pipelines left-to-right with ->: write input step one -> step two -> result, use (+ _ _ +) sequence masks to destructure tuples/lists, and omit _ = on sequential statements (or discard with -> ()).
Tail-Call Optimization (TCO): all internal loops in template are tail-recursive and compile into native hardware loops using $O(1)$ stack space.
Deterministic Memory (RMM1 / RMM2): every intermediate allocation is reclaimed at the exact instruction where its last read finishes, with no Garbage Collector.

22.2. Native Artifacts, Imports, and Complete `template` API Catalog

In ridgun-libs, template is a first-class lib located at src/main/ridgun/lib/template.rg (domain TMPL). When built with stable bundle, it compiles into three native artifacts:

Artifact	Path	Purpose
Ridgun Bundle	`target/bundles/template.rglib`	Portable distribution and direct `import template` resolution
Compiled Archive	`target/template.rgc`	Type-checked intermediate artifact verified by `ridgunc`
ELF64 Shared Object	`target/libtemplate.so`	Native dynamic shared library with zero C or `libc` dependencies

Every lib declares its own namespace via module :: template: simply write import template (or import template as alias) at the top and call its functions with natural spaces (my fn x) and left-to-right -> pipelines (x my fn -> result).

22.2.1. Summary of `template` Functional Families

Signature / Function / Type	Purpose & Usage
`tmpl render / tmpl render html / tmpl render latex`	Render Mustache templates with plain, HTML, or LaTeX auto-escaping
`tmpl escape html / tmpl escape latex`	Escape `& < > " '` for HTML or `\ { } & % $ # _ ~ ^` for LaTeX
`tmpl extract vars / tmpl has unclosed tags`	Inspect required variable names and validate tag balance before rendering

22.2.2. Exhaustive Catalog of Types and Signatures in `src/main/ridgun/lib/template.rg`

Below is the complete inventory of algebraic data types (type), mixfix operators (op ::), and function signatures (fn ::) defined in src/main/ridgun/lib/template.rg (1 types, 0 operators, and 35 functions):

Algebraic Data Types & Records (type) in template:

type TmplEscape = TmplEscapeNone | TmplEscapeHtml | TmplEscapeLatex

#	Function / Signature (`fn ::`)	Return Type
`1`	`fn :: tm lbrace`	`String`
`2`	`fn :: tm rbrace`	`String`
`3`	`fn :: tm braces`	`String`
`4`	`fn :: tm is space Int`	`Bool`
`5`	`fn :: tm trim start String Int Int`	`Int`
`6`	`fn :: tm trim end String Int Int`	`Int`
`7`	`fn :: tm trim String`	`String`
`8`	`fn :: tm lookup [(String, String)] String`	`String`
`9`	`fn :: tm val truthy String`	`Bool`
`10`	`fn :: tm is truthy [(String, String)] String`	`Bool`
`11`	`fn :: tm escape html char Int`	`String`
`12`	`fn :: tm escape html loop String Int Int String`	`String`
`13`	`fn :: tm escape latex char Int`	`String`
`14`	`fn :: tm escape latex loop String Int Int String`	`String`
`15`	`fn :: tm escape String TmplEscape`	`String`
`16`	`fn :: tm find close2 String Int Int`	`Int`
`17`	`fn :: tm find close3 String Int Int`	`Int`
`18`	`fn :: tm find section close String Int Int String Int`	`(Int, Int)`
`19`	`fn :: tm check section tag String Int Int String Int Int`	`(Int, Int)`
`20`	`fn :: tm check close tag String Int Int String Int Int`	`(Int, Int)`
`21`	`fn :: tm close tag match String Int Int String Int Int`	`(Int, Int)`
`22`	`fn :: tm check open tag String Int Int String Int Int`	`(Int, Int)`
`23`	`fn :: tm scan String Int Int [(String, String)] TmplEscape String`	`String`
`24`	`fn :: tm dispatch tag String Int Int [(String, String)] TmplEscape String`	`String`
`25`	`fn :: tm tag raw3 String Int Int [(String, String)] TmplEscape String Int`	`String`
`26`	`fn :: tm tag raw amp String Int Int [(String, String)] TmplEscape String Int`	`String`
`27`	`fn :: tm tag comment String Int Int [(String, String)] TmplEscape String Int`	`String`
`28`	`fn :: tm section active Bool Bool`	`Bool`
`29`	`fn :: tm render section body String Int (Int, Int) Int [(String, String)] TmplEscape String Bool`	`String`
`30`	`fn :: tm tag section String Int Int [(String, String)] TmplEscape String Int Bool`	`String`
`31`	`fn :: tm tag var String Int Int [(String, String)] TmplEscape String Int`	`String`
`32`	`fn :: tmpl render with escape String [(String, String)] TmplEscape`	`String`
`33`	`fn :: tmpl render String [(String, String)]`	`String`
`34`	`fn :: tmpl render html String [(String, String)]`	`String`
`35`	`fn :: tmpl render latex String [(String, String)]`	`String`

22.3. Deep Dive into `template`: Step-by-Step Examples for Every Feature

A signature table alone is never enough: let's explore every capability of the template lib through progressive, runnable Ridgun examples. We will start with two everyday tabular recipes and then walk through every functional scenario, transformation, and boundary condition verified in src/test/ridgun/test template.rg.

22.3.1. Example 1: Core Tabular Workflow with `template`

Notice how in Ridgun the = signs and transformation steps using template align into a clean, scannable table without unnecessary mutable variables or hidden side effects:

import template

fn :: renderizar perfil html String String => String
      renderizar perfil html usuario es_admin =
        "<h1>Hola {{user}}</h1>{{#admin}}<span class='badge'>Admin</span>{{/admin}}" -> plantilla
        [("user", usuario), ("admin", es_admin)] -> vars
        tmpl render html plantilla vars

22.3.2. Example 2: Safe Composition and Boundary Handling

Every function in the template lib is designed to compose cleanly with boolean guards | and with the rest of the 32 libs in ridgun-libs:

import template

fn :: generar linea latex String => String
      generar linea latex metrica =
        -- Escapa automaticamente % _ & # para que LaTeX no falle
        tmpl render latex "Resultado: {{val}}" [("val", metrica)]