22 O Livro do Ridgun

A lib `template` — Templates Mustache Seguros com Auto-Escape HTML e LaTeX

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

«Por que preciso de uma lib template escrita de raiz em Ridgun puro em vez de ligar uma biblioteca C tradicional?»

Essa é a primeira pergunta que qualquer engenheiro de sistemas faz ao chegar à template. E a resposta resume toda a filosofia do ridgun-libs:

Sejamos sinceros: montar páginas HTML ou relatórios LaTeX concatenando cadeias à mão é a receita perfeita para uma vulnerabilidade XSS (<script>) ou para que um simples % ou _ quebre o seu PDF.

A lib template oferece um motor Mustache sem lógica arbitrária com auto-escape contextual (TmplPlain, TmplHtml, TmplLatex), substituição bruta explícita ({{{raw}}} / {{&raw}}), comentários ({{! ... }}), secções condicionais ({{#sec}}...{{/sec}}) e invertidas ({{^sec}}...{{/sec}}).

Num ecossistema tradicional, resolver as tarefas do domínio TMPL implica arrastar dependências externas em C, lidar com ponteiros brutos, conversões opacas de tipos, exceções não verificadas ou pausas imprevisíveis do coletor de lixo. Em Ridgun, a lib template (src/main/ridgun/lib/template.rg) aborda o problema com quatro princípios inegociáveis:

Declare import template (ou import template as alias) no início do ficheiro: cada lib define o seu espaço de nomes module :: template e em modo --strict as funções multi-palavra são sempre invocadas com espaços naturais.
Encadeie os seus pipelines da esquerda para a direita com ->: escreva entrada passo um -> passo dois -> resultado, use máscaras (+ _ _ +) para desestruturar sequências e omita _ = em instruções sequenciais (ou descarte com -> ()).
Recursão de cauda com TCO (Tail-Call Optimization): todas as travessias internas da template são compiladas para ciclos nativos em espaço de pilha $O(1)$.
Memória determinística (RMM1 / RMM2): cada estrutura intermédia é libertada no instante exato em que termina a sua última leitura, sem Garbage Collector.

22.2. Artefactos nativos, importação e catálogo completo da API de `template`

No ridgun-libs, template é uma lib de primeira classe localizada em src/main/ridgun/lib/template.rg (domínio TMPL). Ao compilar com stable bundle, é empacotada em três formatos nativos:

Artefacto	Caminho	Finalidade
Bundle Ridgun	`target/bundles/template.rglib`	Distribuição e importação direta com `import template`
Ficheiro compilado	`target/template.rgc`	Artefacto intermédio verificado pelo `ridgunc`
Objeto partilhado ELF64	`target/libtemplate.so`	Biblioteca dinâmica nativa sem dependências de C nem `libc`

Cada lib declara o seu próprio espaço de nomes com module :: template: basta escrever import template (ou import template as alias) no topo e invocar as suas funções com espaços naturais (minha funcao x) e pipelines -> (x minha funcao -> resultado).

22.2.1. Resumo das famílias funcionais da `template`

Assinatura / Função / Tipo	O que faz e quando usar
`tmpl render / tmpl render html / tmpl render latex`	Renderiza templates Mustache com auto-escape simples, HTML ou LaTeX
`tmpl escape html / tmpl escape latex`	Escapa `& < > " '` para HTML ou `\ { } & % $ # _ ~ ^` para LaTeX
`tmpl extract vars / tmpl has unclosed tags`	Extrai os nomes das variáveis necessárias e valida o fecho das etiquetas

22.2.2. Catálogo exaustivo de tipos e assinaturas em `src/main/ridgun/lib/template.rg`

Abaixo encontra-se o inventário completo de tipos algébricos (type), operadores (op ::) e assinaturas de funções (fn ::) definidos em src/main/ridgun/lib/template.rg (1 tipos, 0 operadores e 35 funções):

Tipos algébricos e registos (type) da template:

type TmplEscape = TmplEscapeNone | TmplEscapeHtml | TmplEscapeLatex

#	Função / Assinatura (`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 a `template` a fundo: Exemplos passo a passo de cada funcionalidade

Não basta ver a tabela de assinaturas: vamos explorar cada uma das funcionalidades da lib template através de exemplos progressivos e executáveis em Ridgun. Começaremos pelas duas receitas tabulares de uso diário e depois percorreremos em detalhe todos os cenários funcionais, transformações e casos de fronteira verificados em src/test/ridgun/test template.rg.

22.3.1. Exemplo 1: Fluxo principal em estilo tabular com `template`

Repare como em Ridgun os sinais = e os passos de transformação com template ficam alinhados como uma tabela limpa, sem variáveis mutáveis desnecessárias nem efeitos colaterais 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: Composição segura e tratamento de casos de fronteira

Todas as funções da lib template foram desenhadas para se comporem com guardas booleanas | e com as restantes 32 libs do 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)]