22 Boken om Ridgun

Lib:en `template` — Säkra Mustache-mallar med Automatisk HTML- och LaTeX-kodning

22.1. Varför finns lib:en `template`? (Det verkliga problemet och Ridguns filosofi)

”Varför behöver jag en template-lib skriven från grunden i ren Ridgun i stället för att bara länka in ett gammalt C-bibliotek?”

Det är den första fråga varje systemingenjör ställer sig när man möter template. Och svaret sammanfattar hela filosofin bakom ridgun-libs:

Låt oss vara ärliga: att bygga HTML-sidor eller LaTeX-rapporter genom manuell strängkonkatenering är ett säkert recept på XSS-sårbarheter (<script>) eller trasiga PDF-byggen så fort någon skriver % eller _.

Lib:en template erbjuder en logikfri Mustache-motor med kontextuell automatisk kodning (TmplPlain, TmplHtml, TmplLatex), explicit råinterpolering ({{{raw}}} / {{&raw}}), kommentarer ({{! ... }}) samt villkorliga ({{#sec}}) och inverterade sektioner ({{^sec}}).

I ett traditionellt ekosystem innebär uppgifter inom domänen TMPL ofta att man drar in externa C-beroenden, brottas med råa pekare, ogenomskinliga typkonverteringar, okontrollerade undantag eller oförutsägbara skräpsamlarpauser. I Ridgun löser lib:en template (src/main/ridgun/lib/template.rg) problemet genom fyra kompromisslösa principer:

Deklarera import template (eller import template as alias) överst i filen: varje lib definierar sin module :: template-namnrymd och i --strict-läge anropas flerordsfunktioner alltid med naturliga mellanslag.
Kedja dina datapipelines från vänster till höger med ->: skriv indata steg ett -> steg två -> resultat, använd (+ _ _ +)-sekvensmasker för att packa upp tupler och utelämna _ = vid sekventiella satser (eller kasta med -> ()).
Svansrekursion med TCO (Tail-Call Optimization): alla interna genomlöpningar i template kompileras till inbyggda hårdvaruloopar med $O(1)$ stackutrymme.
Deterministiskt minne (RMM1 / RMM2): varje mellanliggande struktur frigörs i exakt det ögonblick dess sista läsning avslutas, helt utan Garbage Collector.

22.2. Inbyggda artefakter, import och komplett API-katalog för `template`

I ridgun-libs är template en förstklassig lib placerad i src/main/ridgun/lib/template.rg (domän TMPL). När du bygger med stable bundle paketeras den i tre inbyggda format:

Artefakt	Sökväg	Syfte
Ridgun-bundle	`target/bundles/template.rglib`	Portabel distribution och direkt import med `import template`
Kompilerat arkiv	`target/template.rgc`	Typkontrollerad mellanartefakt verifierad av `ridgunc`
Delat ELF64-objekt	`target/libtemplate.so`	Inbyggt dynamiskt bibliotek helt utan C- eller `libc`-beroenden

Varje lib deklarerar sin egen namnrymd med module :: template: skriv bara import template (eller import template as alias) överst och anropa dess funktioner med naturliga mellanslag (min funktion x) och ->-pipelines (x min funktion -> resultat).

22.2.1. Översikt över funktionella familjer i `template`

Signatur / Funktion / Typ	Vad den gör och när den används
`tmpl render / tmpl render html / tmpl render latex`	Renderar Mustache-mallar med enkel, HTML- eller LaTeX-autokodning
`tmpl escape html / tmpl escape latex`	Kodar `& < > " '` för HTML eller `\ { } & % $ # _ ~ ^` för LaTeX
`tmpl extract vars / tmpl has unclosed tags`	Extraherar obligatoriska variabelnamn och validerar taggbalans före rendering

22.2.2. Komplett katalog över typer och signaturer i `src/main/ridgun/lib/template.rg`

Nedan följer hela förteckningen över algebraiska datatyper (type), mixfix-operatorer (op ::) och funktionssignaturer (fn ::) som definieras i src/main/ridgun/lib/template.rg (1 typer, 0 operatorer och 35 funktioner):

Algebraiska datatyper och poster (type) i template:

type TmplEscape = TmplEscapeNone | TmplEscapeHtml | TmplEscapeLatex

#	Funktion / Signatur (`fn ::`)	Returtyp
`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. Djupdykning i `template`: Steg-för-steg-exempel för varje funktion

Det räcker inte med en signaturtabell: låt oss utforska varje funktionalitet i lib:en template genom progressiva, körbara Ridgun-exempel. Vi börjar med två tabellbaserade vardagsrecept och går därefter igenom alla funktionella scenarier, transformationer och gränsfall som verifieras i src/test/ridgun/test template.rg.

22.3.1. Exempel 1: Huvudflöde i tabellform med `template`

Lägg märke till hur =-tecknen och transformationsstegen med template linjeras som en ren tabell utan onödiga muterbara variabler eller dolda sidoeffekter:

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. Exempel 2: Säker komposition och hantering av gränsfall

Varje funktion i lib:en template är utformad för att kombineras sömlöst med booleska vakter | och med övriga 32 libs i 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)]