22 El Llibre de Ridgun

La lib `template` — Plantilles Mustache Segures amb Auto-Escapament HTML i LaTeX

22.1. Per què existeix la lib `template`? (El problema real i la filosofia Ridgun)

«Per què necessito una lib template escrita des de zero en Ridgun pur en lloc d'enllaçar una llibreria de C de tota la vida?»

Aquesta és la primera pregunta que es fa qualsevol enginyer de sistemes en arribar a template. I la resposta resumeix tota la filosofia de ridgun-libs:

Siguem sincers: muntar pàgines HTML o informes LaTeX concatenant cadenes a mà és la recepta perfecta per a una vulnerabilitat XSS (<script>) o perquè un simple símbol % o _ trenqui la compilació del teu PDF.

La lib template ofereix un motor Mustache sense lògica arbitrària amb auto-escapament contextual (TmplPlain, TmplHtml, TmplLatex), substitució crua explícita ({{{raw}}} / {{&raw}}), comentaris ({{! ... }}), seccions condicionals ({{#sec}}...{{/sec}}) i invertides ({{^sec}}...{{/sec}}).

En un ecosistema tradicional, resoldre les tasques del domini TMPL implica arrossegar dependències externes en C, lluitar amb punters crus, conversions opaques de tipus, excepcions no verificades o pauses impredictibles del recol·lector de brossa. En Ridgun, la lib template (src/main/ridgun/lib/template.rg) aborda el problema amb quatre principis innegociables:

Declara import template (o import template as alias) a l'inici del fitxer: cada lib defineix el seu espai de noms module :: template i en mode --strict les funcions multi-paraula s'invoquen sempre amb espais naturals.
Encadena les teves canonades d'esquerra a dreta amb ->: escriu entrada pas u -> pas dos -> resultat, fes servir màscares (+ _ _ +) per desestructurar seqüències i omet _ = en sentències seqüencials (o descarta amb -> ()).
Recursió de cua amb TCO (Tail-Call Optimization): tots els recorreguts interns de template es compilen a bucles natius en espai de pila $O(1)$.
Memòria determinista (RMM1 / RMM2): cada estructura intermèdia s'allibera en l'instant exacte en què acaba la seva última lectura, sense Garbage Collector.

22.2. Artefactes natius, importació i catàleg complet de l'API de `template`

A ridgun-libs, template és una lib de primera classe situada a src/main/ridgun/lib/template.rg (domini TMPL). En compilar amb stable bundle, s'empaqueta en tres formats natius:

Artefacte	Ruta	Propòsit
Bundle Ridgun	`target/bundles/template.rglib`	Distribució i importació directa amb `import template`
Fitxer compilat	`target/template.rgc`	Artefacte intermedi verificat per `ridgunc`
Objecte compartit ELF64	`target/libtemplate.so`	Biblioteca dinàmica nativa sense dependències de C ni `libc`

Cada lib declara el seu propi espai de noms amb module :: template: n'hi ha prou d'escriure import template (o import template as alias) a la capçalera i cridar les seves funcions amb espais naturals (la meva funcio x) i canonades -> (x la meva funcio -> resultat).

22.2.1. Resum de famílies funcionals de `template`

Signatura / Funció / Tipus	Què fa i quan fer-la servir
`tmpl render / tmpl render html / tmpl render latex`	Renderitza plantilles Mustache amb auto-escapament pla, HTML o LaTeX
`tmpl escape html / tmpl escape latex`	Escapa `& < > " '` per a HTML o `\ { } & % $ # _ ~ ^` per a LaTeX
`tmpl extract vars / tmpl has unclosed tags`	Extreu els noms de variables requerits i valida que les etiquetes estiguin tancades

22.2.2. Catàleg exhaustiu de tipus i signatures a `src/main/ridgun/lib/template.rg`

A continuació tens l'inventari complet de tipus algebraics (type), operadors (op ::) i signatures de funcions (fn ::) definits a src/main/ridgun/lib/template.rg (1 tipus, 0 operadors i 35 funcions):

Tipus algebraics i registres (type) de template:

type TmplEscape = TmplEscapeNone | TmplEscapeHtml | TmplEscapeLatex

#	Funció / Signatura (`fn ::`)	Tipus de Retorn
`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. Explorant `template` a fons: Exemples pas a pas de cada funcionalitat

No n'hi ha prou de veure la taula de signatures: explorarem cadascuna de les funcionalitats de la lib template mitjançant exemples progressius i executables en Ridgun. Començarem per les dues receptes tabulars d'ús quotidià i després recorrerem en detall tots els escenaris funcionals, transformacions i casos límit verificats a src/test/ridgun/test template.rg.

22.3.1. Exemple 1: Flux principal en estil tabular amb `template`

Observa com en Ridgun els signes = i els passos de transformació amb template queden alineats com una taula neta, sense variables mutables innecessàries ni efectes laterals ocults:

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. Exemple 2: Composició segura i gestió de casos de vora

Tota funció de la lib template està dissenyada per compondre's amb guardes booleanes | i amb la resta de les 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)]