22 O Libro de Ridgun

A lib `template` — Modelos Mustache Seguros con Auto-Escape HTML e LaTeX

22.1. Por que existe a lib `template`? (O problema real e a filosofía Ridgun)

«Por que necesito unha lib template escrita dende cero en Ridgun puro en vez de enlazar unha librería de C de toda a vida?»

Esa é a primeira pregunta que se fai calquera enxeñeiro de sistemas ao chegar a template. E a resposta resume toda a filosofía de ridgun-libs:

Sexamos sinceros: montar páxinas HTML ou informes LaTeX concatenando cadeas á man é a receita perfecta para unha vulnerabilidade XSS (<script>) ou para que un simple símbolo % ou _ rompa a compilación do teu PDF.

A lib template ofrece un motor Mustache sen lóxica arbitraria con auto-escape contextual (TmplPlain, TmplHtml, TmplLatex), substitución crúa explícita ({{{raw}}} / {{&raw}}), comentarios ({{! ... }}), seccións condicionais ({{#sec}}...{{/sec}}) e invertidas ({{^sec}}...{{/sec}}).

Nun ecosistema tradicional, resolver as tarefas do dominio TMPL implica arrastrar dependencias externas en C, loitar con punteiros crus, conversións opacas de tipos, excepcións non verificadas ou pausas impredicibles do colector de lixo. En Ridgun, a lib template (src/main/ridgun/lib/template.rg) aborda o problema con catro principios innegociables:

Declara import template (ou import template as alias) ao inicio do ficheiro: cada lib define o seu espazo de nomes module :: template e en modo --strict as funcións multi-palabra invócanse sempre con espazos naturais.
Encadea as túas tubaxes de esquerda a dereita con ->: escribe entrada paso un -> paso dous -> resultado, usa máscaras (+ _ _ +) para desestruturar secuencias e omite _ = en sentenzas secuenciais (ou descarta con -> ()).
Recursión de cola con TCO (Tail-Call Optimization): todos os percorridos internos de template compílanse a bucles nativos en espazo de pila $O(1)$.
Memoria determinista (RMM1 / RMM2): cada estrutura intermedia libérase no instante exacto en que remata a súa última lectura, sen Garbage Collector.

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

En ridgun-libs, template é unha lib de primeira clase situada en src/main/ridgun/lib/template.rg (dominio TMPL). Ao compilar con stable bundle, empaquétase en tres formatos nativos:

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

Cada lib declara o seu propio espazo de nomes con module :: template: abonda con escribir import template (ou import template as alias) na cabeceira e chamar ás súas funcións con espazos naturais (mina funcion x) e tubaxes -> (x mina funcion -> resultado).

22.2.1. Resumo de familias funcionais de `template`

Sinatura / Función / Tipo	Que fai e cando usala
`tmpl render / tmpl render html / tmpl render latex`	Renderiza modelos Mustache con auto-escape plano, HTML ou LaTeX
`tmpl escape html / tmpl escape latex`	Escapa `& < > " '` para HTML ou `\ { } & % $ # _ ~ ^` para LaTeX
`tmpl extract vars / tmpl has unclosed tags`	Extrae os nomes de variables requiridos e valida que as etiquetas estean pechadas

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

A continuación tes o inventario completo de tipos alxébricos (type), operadores (op ::) e sinaturas de funcións (fn ::) definidos en src/main/ridgun/lib/template.rg (1 tipos, 0 operadores e 35 funcións):

Tipos alxébricos e rexistros (type) de template:

type TmplEscape = TmplEscapeNone | TmplEscapeHtml | TmplEscapeLatex

#	Función / Sinatura (`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: Exemplos paso a paso de cada funcionalidade

Non abonda con ver a táboa de sinaturas: imos explorar cada unha das funcionalidades da lib template mediante exemplos progresivos e executables en Ridgun. Comezaremos polas dúas receitas tabulares de uso cotián e despois percorreremos en detalle todos os escenarios funcionais, transformacións e casos límite verificados en src/test/ridgun/test template.rg.

22.3.1. Exemplo 1: Fluxo principal en estilo tabular con `template`

Observa como en Ridgun os signos = e os pasos de transformación con template quedan aliñados coma unha táboa limpa, sen variables mutables innecesarias nin efectos laterais 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. Exemplo 2: Composición segura e manexo de casos de bordo

Toda función da lib template está deseñada para compoñerse con gardas booleanas | e co resto das 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)]