22 El Libro de Ridgun

La lib `template` — Plantillas Mustache Seguras con Auto-Escape HTML y LaTeX

22.1. ¿Por qué existe la lib `template`? (El problema real y la filosofía Ridgun)

«¿Por qué necesito una lib template escrita desde cero en Ridgun puro en lugar de enlazar una librería de C de toda la vida?»

Esa es la primera pregunta que se hace cualquier ingeniero de sistemas al llegar a template. Y la respuesta resume toda la filosofía de ridgun-libs:

Seamos sinceros: montar páginas HTML o informes LaTeX concatenando cadenas a mano es la receta perfecta para una vulnerabilidad XSS (<script>) o para que un simple símbolo % o _ rompa la compilación de tu PDF.

La lib template ofrece un motor Mustache sin lógica arbitraria con auto-escape contextual (TmplPlain, TmplHtml, TmplLatex), sustitución cruda explícita ({{{raw}}} / {{&raw}}), comentarios ({{! ... }}), secciones condicionales ({{#sec}}...{{/sec}}) e invertidas ({{^sec}}...{{/sec}}).

En un ecosistema tradicional, resolver las tareas del dominio TMPL implica arrastrar dependencias externas en C, lidiar con punteros crudos, conversiones opacas de tipos, excepciones no verificadas o pausas impredecibles del recolector de basura. En Ridgun, la lib template (src/main/ridgun/lib/template.rg) aborda el problema con cuatro principios innegociables:

Declara import template (o import template as alias) al inicio del archivo: cada lib define su espacio de nombres module :: template y en modo --strict las funciones multi-palabra se invocan siempre con espacios naturales.
Encadena tus tuberías de izquierda a derecha con ->: escribe entrada paso uno -> paso dos -> resultado, usa máscaras (+ _ _ +) para desestructurar secuencias y omite _ = en sentencias secuenciales (o descarta con -> ()).
Recursión de cola con TCO (Tail-Call Optimization): todos los recorridos internos de template se compilan a bucles nativos en $O(1)$ espacio de pila.
Memoria determinista (RMM1 / RMM2): cada estructura intermedia se libera en el instante exacto en que termina su última lectura, sin Garbage Collector.

22.2. Artefactos nativos, importación y catálogo completo de la API de `template`

En ridgun-libs, template es una lib de primera clase ubicada en src/main/ridgun/lib/template.rg (dominio TMPL). Al compilar con stable bundle, se empaqueta en tres artefactos nativos:

Artefacto	Ruta	Propósito
Bundle Ridgun	`target/bundles/template.rglib`	Distribución e importación directa con `import template`
Archivo compilado	`target/template.rgc`	Artefacto intermedio verificado por `ridgunc`
Objeto compartido ELF64	`target/libtemplate.so`	Biblioteca dinámica nativa sin dependencias de C ni `libc`

Cada lib declara su propio espacio de nombres con module :: template: basta con escribir import template (o import template as alias) en el encabezado y llamar a sus funciones con espacios naturales (mi funcion x) y tuberías -> (x mi funcion -> resultado).

22.2.1. Resumen de familias funcionales de `template`

Firma / Función / Tipo	Qué hace y cuándo usarla
`tmpl render / tmpl render html / tmpl render latex`	Renderiza plantillas Mustache con auto-escape plano, HTML o LaTeX
`tmpl escape html / tmpl escape latex`	Escapa `& < > " '` para HTML o `\ { } & % $ # _ ~ ^` para LaTeX
`tmpl extract vars / tmpl has unclosed tags`	Extrae los nombres de variables requeridos y valida que las etiquetas estén cerradas

22.2.2. Catálogo exhaustivo de tipos y firmas en `src/main/ridgun/lib/template.rg`

A continuación tienes el inventario completo de tipos algebraicos (type), operadores (op ::) y firmas de funciones (fn ::) definidos en src/main/ridgun/lib/template.rg (1 tipos, 0 operadores y 35 funciones):

Tipos algebraicos y registros (type) de template:

type TmplEscape = TmplEscapeNone | TmplEscapeHtml | TmplEscapeLatex

#	Función / Firma (`fn ::`)	Tipo de Retorno
`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. Explorando `template` a fondo: Ejemplos paso a paso de cada funcionalidad

No basta con ver la tabla de firmas: vamos a explorar cada una de las funcionalidades de la lib template mediante ejemplos progresivos y ejecutables en Ridgun. Empezaremos por las dos recetas tabulares de uso cotidiano y después recorreremos en detalle todos los escenarios funcionales, transformaciones y casos límite verificados en src/test/ridgun/test template.rg.

22.3.1. Ejemplo 1: Flujo principal en estilo tabular con `template`

Observa cómo en Ridgun los signos = y los pasos de transformación con template quedan alineados como una tabla limpia, sin variables mutables innecesarias ni efectos laterales ocultos:

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. Ejemplo 2: Composición segura y manejo de casos de borde

Toda función de la lib template está diseñada para componerse con guardas booleanas | y con el resto de las 32 libs de 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)]