22 Il Libro di Ridgun

La lib `template` — Modelli Mustache Sicuri con Auto-Escape HTML e LaTeX

22.1. Perché esiste la lib `template`? (Il problema reale e la filosofia Ridgun)

«Perché ho bisogno di una lib template scritta da zero in Ridgun puro invece di collegare una libreria C tradizionale?»

Questa è la prima domanda che si pone qualsiasi ingegnere di sistema arrivando a template. E la risposta riassume l'intera filosofia di ridgun-libs:

Siamo sinceri: assemblare pagine HTML o report LaTeX concatenando stringhe a mano è la ricetta perfetta per una vulnerabilità XSS (<script>) o perché un semplice simbolo % o _ interrompa la compilazione del tuo PDF.

La lib template offre un motore Mustache privo di logica arbitraria con auto-escape contestuale (TmplPlain, TmplHtml, TmplLatex), sostituzione raw esplicita ({{{raw}}} / {{&raw}}), commenti ({{! ... }}), sezioni condizionali ({{#sec}}...{{/sec}}) e invertite ({{^sec}}...{{/sec}}).

In un ecosistema tradizionale, risolvere i compiti del dominio TMPL comporta trascinare dipendenze esterne in C, gestire puntatori grezzi, conversioni opache di tipo, eccezioni non verificate o pause imprevedibili del garbage collector. In Ridgun, la lib template (src/main/ridgun/lib/template.rg) affronta il problema con quattro principi non negoziabili:

Dichiara import template (o import template as alias) all'inizio del file: ogni lib definisce il proprio spazio dei nomi module :: template e in modalità --strict le funzioni multi-parola si invocano sempre con spazi naturali.
Concatena le tue pipeline da sinistra a destra con ->: scrivi input passo uno -> passo due -> risultato, usa le maschere (+ _ _ +) per destrutturare le sequenze e ometti _ = nelle istruzioni sequenziali (o scarta il valore con -> ()).
Ricorsione di coda con TCO (Tail-Call Optimization): tutte le scansioni interne di template vengono compilate in cicli nativi in spazio di stack $O(1)$.
Memoria deterministica (RMM1 / RMM2): ogni struttura intermedia viene liberata nell'istante esatto in cui termina la sua ultima lettura, senza Garbage Collector.

22.2. Artefatti nativi, importazione e catalogo completo dell'API di `template`

In ridgun-libs, template è una lib di prima classe situata in src/main/ridgun/lib/template.rg (dominio TMPL). Compilando con stable bundle, viene impacchettata in tre artefatti nativi:

Artefatto	Percorso	Scopo
Bundle Ridgun	`target/bundles/template.rglib`	Distribuzione e importazione diretta con `import template`
File compilato	`target/template.rgc`	Artefatto intermedio verificato da `ridgunc`
Oggetto condiviso ELF64	`target/libtemplate.so`	Libreria dinamica nativa senza dipendenze C né `libc`

Ogni lib dichiara il proprio spazio dei nomi con module :: template: basta scrivere import template (o import template as alias) nell'intestazione e invocare le sue funzioni con spazi naturali (mia funzione x) e pipeline -> (x mia funzione -> risultato).

22.2.1. Riepilogo delle famiglie funzionali di `template`

Firma / Funzione / Tipo	Cosa fa e quando usarla
`tmpl render / tmpl render html / tmpl render latex`	Renderizza modelli Mustache con auto-escape testo semplice, HTML o LaTeX
`tmpl escape html / tmpl escape latex`	Esegue l'escape di `& < > " '` per HTML o `\ { } & % $ # _ ~ ^` per LaTeX
`tmpl extract vars / tmpl has unclosed tags`	Estrae i nomi delle variabili richieste e convalida la chiusura dei tag

22.2.2. Catalogo esaustivo dei tipi e delle firme in `src/main/ridgun/lib/template.rg`

Di seguito trovi l'inventario completo dei tipi algebrici (type), degli operatori (op ::) e delle firme di funzione (fn ::) definiti in src/main/ridgun/lib/template.rg (1 tipi, 0 operatori e 35 funzioni):

Tipi algebrici e record (type) di template:

type TmplEscape = TmplEscapeNone | TmplEscapeHtml | TmplEscapeLatex

#	Funzione / Firma (`fn ::`)	Tipo di Ritorno
`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. Esplorare `template` a fondo: Esempi passo dopo passo di ogni funzionalità

Non basta consultare la tabella delle firme: esploreremo ciascuna delle funzionalità della lib template tramite esempi progressivi ed eseguibili in Ridgun. Inizieremo con due ricette tabulari di uso quotidiano e poi percorreremo nel dettaglio tutti gli scenari funzionali, le trasformazioni e i casi limite verificati in src/test/ridgun/test template.rg.

22.3.1. Esempio 1: Flusso principale in stile tabulare con `template`

Osserva come in Ridgun i segni = e i passaggi di trasformazione con template risultino allineati come una tabella pulita, senza variabili mutabili superflue né effetti collaterali nascosti:

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. Esempio 2: Composizione sicura e gestione dei casi limite

Ogni funzione della lib template è progettata per comporsi con le guardie booleane | e con il resto delle 34 lib di 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)]