Funzioni e helper Sprig
Il motore di template di Aggrega collega la libreria di funzioni Sprig v3 più gli helper propri di Aggrega (optional e capitalizedWords) in ogni template Go che il renderer valuta, e sostituisce la funzione index di Go con una che si arresta su una chiave che la mappa non contiene. Gli autori che scrivono il valuesMapping: di una Recipe, l’injectMapping: di una FeatureRecipe o qualsiasi altra superficie di template che il renderer valuta hanno a disposizione l’intero insieme di helper di Sprig accanto alle funzioni integrate di text/template di Go e ai campi del contesto di runtime documentati in template-context-contract.md.
🔴 Leggi «che il renderer valuta» come l’ambito che è, perché una superficie di scrittura ne resta fuori. Una coordinata source: strutturata viene risolta affinché l’artefatto che nomina possa essere fissato, e quella risoluzione non è un passaggio di rendering: registra gli helper propri di Aggrega e nient’altro, quindi una chiamata Sprig in un campo source:, o in una voce locals: che esso legge, arresta il pull. Una voce che nessun campo source: legge viene valutata dal solo rendering, con l’insieme completo. Risolvere una coordinata stabilisce ciò che viene fissato anziché produrre un artefatto, ed è per questo che il suo insieme di funzioni è deliberatamente più ristretto — vedi errors/fatal-halts.md «Resolving a source: coordinate registers a narrower function set (La risoluzione di una coordinata source registra un insieme di funzioni più ristretto)» per l’arresto e la forma portabile da usare invece.
L’insieme di Sprig viene registrato da solo per l’interpolazione dei parametri, e insieme agli helper propri di Aggrega sulle superfici dei template di valore del renderer.
Che cosa è collegato
Sprig v3 espone la sua intera superficie di helper — circa 200 funzioni nelle categorie qui sotto. Questa pagina delinea le categorie con gli helper comuni di ciascuna; il riferimento canonico per singola funzione è la documentazione upstream di Sprig.
- Stringhe —
upper,lower,title,trim,trimAll,trimPrefix,trimSuffix,replace,contains,hasPrefix,hasSuffix,substr,quote,squote,cat,indent,nindent,repeat, helper di stile del nome (snakecase,camelcase,kebabcase), helper di abbreviazione (abbrev,abbrevboth,trunc), helper di checksum (sha1sum,sha256sum,sha512sum,adler32sum),toString. - Liste —
list,tuple,first,last,rest,initial,append/push,prepend,concat,reverse,uniq,without,has,slice,chunk,join,splitList,split,splitn,sortAlpha,compact. - Dizionari —
dict,get,set,unset,hasKey,keys,values,pick,omit,pluck,merge,mergeOverwrite,dig,deepCopy. - Matematica —
add,sub,mul,div,mod,add1,min,max,ceil,floor,round, più le varianti decimali con suffissof(addf,subf,mulf,divf,minf,maxf). - Conversione —
int,int64,float64,atoi,toString,toDecimal,seq,until,untilStep. - Codifica —
b64enc,b64dec,b32enc,b32dec,toJson,toPrettyJson,toRawJson,fromJson, più le varianti JSON con prefissomustche fanno emergere gli errori di decodifica anziché azzerare silenziosamente. - Controlli di tipo —
typeOf,typeIs,typeIsLike,kindOf,kindIs,deepEqual,empty. - Valori predefiniti e flusso —
default,coalesce,all,any,ternary,fail(solleva un errore di template con un messaggio personalizzato — il modo canonico per interrompere un rendering con un messaggio di guardia). - Regex —
regexMatch,regexFind,regexFindAll,regexReplaceAll,regexReplaceAllLiteral,regexSplit,regexQuoteMeta, più le varianti rigorose con prefissomust. - Percorsi —
base,dir,clean,ext,isAbs(in stile Unix);osBase,osClean,osDir,osExt,osIsAbs(dipendenti dal sistema operativo). - SemVer —
semver,semverCompare. - URL —
urlParse,urlJoin. - Date —
ago,date,dateInZone,dateModify,duration,durationRound,htmlDate,htmlDateInZone,now,toDate,unixEpoch.
Avvertenza sul determinismo
Aggrega garantisce un output identico byte per byte a fronte di un input identico byte per byte. Un sottoinsieme degli helper di Sprig legge lo stato dell’ambiente e rompe tale garanzia quando viene invocato da un template. Gli autori dovrebbero evitare i seguenti helper nelle superfici di template che contribuiscono agli artefatti renderizzati:
- Lettori dell’orologio di sistema —
now,date,dateInZone,dateModify,htmlDate,htmlDateInZone,agoquando viene chiamato senza un tempo di riferimento congelato. - Generatori casuali —
randAlpha,randAlphaNum,randAscii,randNumeric,randBytes,randInt,uuidv4. - Lettori dell’ambiente —
env,expandenv(leggono le variabili d’ambiente del processo, che differiscono tra le workstation degli operatori e i runner di CI). - Risolutori di rete —
getHostByName.
Questi helper non sono bloccati dal motore; fanno parte dell’insieme di Sprig v3. La disciplina di evitarli nei template del percorso di rendering è sostenuta dai revisori e dalla garanzia di output deterministico su cui fanno affidamento gli autori e il catalogo della libreria standard.
Numeri in un template di valore
Un numero che un autore scrive raggiunge un template di valore come numero. Un numero senza parte decimale è un intero e si stampa per intero: 1000000 stampa 1000000. Qualsiasi altro numero si stampa nella sua forma decimale esatta più breve, mai in forma esponenziale: un 0.0000001 scritto dall’autore stampa 0.0000001 e un 1e21 scritto dall’autore stampa 1000000000000000000000, sia che il template scriva il valore direttamente sia che lo trasformi in testo con toString, quote, printf "%v" o toJson. Un numero restituito da una funzione matematica — mulf, float64, round e simili — è il valore proprio di quella funzione e si stampa nella forma propria di quella funzione, che è la forma esponenziale per un valore molto piccolo o molto grande: {{ mulf .values.ratio 1 }} stampa 1e-07 per un 0.0000001 scritto dall’autore.
I confronti — eq, ne, lt, le, gt e ge — leggono due numeri per valore, qualunque sia il tipo che porta ciascuno, quindi un intero scritto dall’autore si confronta con un decimale scritto nel template, e 3 è uguale a 3.0:
{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → trueUn numero non viene mai confrontato con un testo: uno qualsiasi dei sei, ricevendo un numero e un testo tra virgolette, arresta la build, nominando entrambi i tipi. Confronta il numero con un numero scritto senza virgolette, oppure trasformalo prima in testo:
{{ eq .values.port "8080" }} # halts: cannot compare a number with text{{ eq .values.port 8080 }} # .values.port = 8080 → true{{ eq (toString .values.port) "8080" }} # .values.port = 8080 → trueL’arresto è A value template failed while it ran (Un template di valore non è riuscito durante l’esecuzione). Un’asserzione legge un numero scritto dall’autore allo stesso modo; vedi Numeri su questa superficie.
Presenza e vuoto — due domande diverse
Un template pone una di due domande su un valore, e ogni domanda ha i propri helper.
- L’autore lo ha scritto?
hasKeyeoptionalrispondono in base alla presenza. Una chiave che l’autore ha scritto è presente qualunque cosa contenga —0,""efalseinclusi — e solo una chiave che l’autore ha omesso è assente. - È vuoto?
default,with,ifeemptyrispondono in base al vuoto.0,"",false, una lista vuota, una mappa vuota e un valore assente contano tutti come vuoti in quel caso, come in Helm.
.values.replicas | hasKey .values "replicas" | optional .values "replicas" 1 | .values.replicas | default 1 | if .values.replicas |
|---|---|---|---|---|
| assente | false | 1 | 1 | false |
0 | true | 0 | 1 | false |
3 | true | 3 | 3 | true |
Un valore che può legittimamente essere 0, "" o false — un numero di repliche pari a zero, un timeout pari a zero, un flag disattivato — si verifica con hasKey o optional, così il valore 0 dell’autore raggiunge l’output come 0. default, with e if si adattano a un valore la cui forma vuota non ha un significato proprio, dove «vuoto» e «non scritto» possono essere trattati allo stesso modo. Leggi una data chiave in un solo modo per template: una chiave che il template legge anche come percorso puntato conta come presente, come descrive il limite di optional.
Helper specifici di Aggrega
optional — fallback sensibile alla presenza
optional <map> <key> <fallback> restituisce il valore in <key> in <map> se la chiave è presente, altrimenti restituisce <fallback>. A differenza di default di Sprig, optional distingue «chiave assente» da «chiave presente con un valore zero, vuoto o falso».
La firma accetta la mappa e la chiave come argomenti separati perché un valore passato attraverso l’operatore | dei template Go ha perso l’accesso alla sua mappa padre. Senza la mappa padre nell’ambito, la presenza non può essere verificata.
Un limite al controllo di presenza, che deriva dal template e non dall’helper: un template di valore legge una chiave assente come nulla, e lo fa fornendo un valore vuoto in ogni chiave assente che il template nomina come percorso puntato e legge come valore. Quindi un template che legge una chiave sia tramite optional sia come tale percorso trova quella chiave presente e vuota, e ottiene il valore vuoto anziché il fallback. Leggi una chiave in un solo modo per template e le due risposte coincidono.
# Present and non-zero: returns 3{{ optional .infra `replicas` 1 }} # .infra.replicas = 3 → 3
# Absent: returns the fallback{{ optional .infra `replicas` 1 }} # .infra.replicas unset → 1
# Present but authored zero: returns 0 (the discriminator){{ optional .infra `replicas` 1 }} # .infra.replicas = 0 → 0L’ultimo caso è la distinzione che il default di Sprig non può fare. {{ .infra.replicas | default 1 }} restituisce 1 sia che replicas sia stato scritto come 0 sia che sia stato omesso — la confusione che impedisce i pattern legittimi di scale-to-zero, nessun retry, nessun timeout e flag falso.
Convenzione per le virgolette delle chiavi: preferire i backtick. I template Go accettano per l’argomento chiave sia letterali stringa tra virgolette doppie ("replicas") sia tra backtick (`replicas`); entrambi producono la stessa stringa al momento della valutazione del template. Gli esempi del catalogo e della documentazione usano uniformemente la forma con backtick perché è sicura per YAML in ogni contesto di quoting. Una chiave tra virgolette doppie dentro uno scalare YAML tra virgolette doppie termina la stringa YAML a metà del template:
# BROKEN — the inner " closes the outer YAML string:service_port: "{{ optional .infra "port" 8080 }}"
# WORKS — backticks are not a YAML escape character:service_port: "{{ optional .infra `port` 8080 }}"Quando il template si trova dentro uno scalare a blocco YAML (forma |) o come scalare a valore nudo, entrambe le forme vengono renderizzate correttamente. Quando il template è incorporato dentro uno scalare YAML tra virgolette doppie (il pattern field: "{{ ... }}" del valore di campo come template), i backtick sono obbligatori. L’unica convenzione (sempre backtick) evita del tutto la trappola delle virgolette YAML.
Quando preferire optional a default. Usa optional quando il campo può legittimamente essere zero, vuoto o falso e l’autore del catalogo deve distinguere «l’autore non l’ha impostato» da «l’autore l’ha impostato a un valore falsy». Usa default quando la confusione è accettabile (ad es. campi stringa in cui il vuoto non è valido; campi numerici in cui lo zero non è valido).
Disponibilità per superficie. optional è registrato su ogni superficie che il renderer valuta: le superfici dei template di valore (valuesMapping della Recipe, injectMapping della FeatureRecipe, provides, pipeline.with, il corpo del Workload), il valutatore delle asserzioni e i template di percorso (directory: / subDirectory: sui confini della Release). Ciò che differisce sulla superficie dei template di percorso non è l’insieme di helper ma la politica sulle chiavi mancanti: un template di percorso tratta una chiave assente come un errore anziché come vuota, perché un segmento di percorso silenziosamente vuoto produce un layout del filesystem rotto che viene scoperto solo dopo la build. optional legge una chiave senza che quella politica rigorosa scatti prima, ed è questo che lo rende utilizzabile lì.
capitalizedWords — ridurre un nome a lettere e cifre
capitalizedWords <string> legge il suo argomento come parole separate da sequenze di qualsiasi carattere diverso da lettere e cifre ASCII, rende maiuscola la prima lettera di ogni parola e le unisce. Ogni carattere del risultato è una lettera o una cifra.
Esiste perché alcuni target accettano solo lettere e cifre nei nomi con cui indirizzano le risorse, mentre un id di componente può legittimamente contenere un punto, un trattino o un trattino basso. Scrivere quella conversione a mano in ogni Recipe che ne ha bisogno produce diverse grafie di una stessa idea; un unico helper dà a ogni autore la stessa risposta.
# separators become word boundaries{{ capitalizedWords `payments-db` }} # → PaymentsDb{{ capitalizedWords `payments_db` }} # → PaymentsDb{{ capitalizedWords `payments.db` }} # → PaymentsDb
# a run of separators is one boundary, and leading or trailing ones add nothing{{ capitalizedWords `-payments--db-` }} # → PaymentsDb
# characters already inside a word keep the case they were authored with{{ capitalizedWords `MY-app` }} # → MYApp
# a word beginning with a digit is carried as authored{{ capitalizedWords `1st-app` }} # → 1stApp
# anything outside the alphabet is a boundary, including a non-ASCII letter{{ capitalizedWords `café-app` }} # → CafApp🔴 Il risultato non identifica il nome da cui proviene. Ogni separatore viene scartato, quindi due id che differiscono solo per la posizione dei separatori arrivano allo stesso risultato — payments-db e payments_db danno entrambi PaymentsDb. L’helper non può rilevarlo, perché vede un nome alla volta; intercettarlo spetta a ciò che indirizza le risorse in base al risultato. Un target che lo fa rifiuta la collisione anziché emettere una distribuzione in cui manca uno dei due: nella build per CloudFormation, due componenti i cui id si riducono a un unico nome arrestano la build, e il messaggio nomina ogni id che vi è arrivato. Scegli id che differiscano per più della punteggiatura, e la questione non si pone.
Disponibilità per superficie. capitalizedWords è registrato ovunque lo sia optional: ogni superficie che il renderer valuta e la risoluzione di una coordinata source: strutturata. Non è disponibile nell’interpolazione dei parametri dell’Aggregate, che offre solo l’insieme di Sprig.
index — una chiave che la mappa deve contenere
index <collection> <key>... legge una collezione per posizione o per chiave, come fa l’index di Go stesso — con una differenza. Quando la collezione è una mappa e la mappa non contiene la chiave, index arresta la build e nomina la chiave, laddove quello di Go risponde con un valore vuoto che si stampa come il testo letterale <no value>.
# Present: returns the value{{ index .values `replicas` }} # .values.replicas = 3 → 3
# A position in a list, or in a string, reads as Go's does{{ index .values.zones 0 }} # .values.zones = [a, b] → a
# Absent: halts, naming the key{{ index .values `replicas` }} # .values.replicas unset → halts: (key "replicas")È la lettura da usare dove la chiave deve esserci — una credenziale letta sotto il nome di variabile che la Recipe ha calcolato, una chiave che un altro template pubblica — affinché una chiave mancante fermi la build invece di raggiungere un artefatto come <no value>. Dove la chiave può legittimamente essere assente, verificala prima: {{ optional .values `replicas` 1 }} fornisce un fallback, get di Sprig restituisce una stringa vuota e hasKey verifica senza leggere. Leggere tramite index e poi applicare default non fornisce un fallback, perché l’arresto avviene prima che default venga eseguito. Una chiave presente che contiene null non è assente: index la restituisce, e si stampa come <no value>.
L’arresto è una proprietà del solo index, ed è lo stesso su ogni superficie — i template di valore, il valutatore delle asserzioni, i template di percorso, una coordinata source: strutturata, l’interpolazione dei parametri dell’Aggregate, il predicato validate: di un parametro e i predicati x-aggrega-when: / x-aggrega-validate: di uno schema. Una lettura puntata di una chiave non impostata segue la politica sulle chiavi mancanti della propria superficie e non ne è influenzata. L’arresto è documentato in errors/fatal-halts.md «A template indexes a map with a key the map does not hold (Un template indicizza una mappa con una chiave che la mappa non contiene)».
Helper comuni NON disponibili
Helm estende il text/template di Go con helper per i template dei chart che vengono comunemente scambiati per helper generici di Sprig. Nessuno di questi è registrato nel renderer di Aggrega. I template che il renderer di Aggrega valuta (valuesMapping: della Recipe, injectMapping: della FeatureRecipe, provides, corpo del Workload, il valutatore delle asserzioni) non possono chiamarli:
include— la forma preferita di Helm per invocare un frammento di template definito con un output stringa concatenabile in pipe. Il renderer di Aggrega non lo registra. Usa invece{{ template "name" . }}del template Go standard (la forma con soli effetti collaterali); per un output concatenabile in pipe, componi usando frammenti di MappingLibrary e direttive$import:.tpl— rivaluta una stringa come template annidato rispetto al contesto corrente. Aggrega non lo registra; la rivalutazione annidata non fa parte della superficie dei template. Gli autori che hanno bisogno di valori calcolati dovrebbero comporli con gli helper per stringhe di Sprig ed emettere direttamente il valore finale.required— fa fallire il rendering del chart con un messaggio personalizzato quando il valore nominato manca. Aggrega non lo registra. L’applicazione dei campi obbligatori in Aggrega risiede nel livello dei contratti di parametri tipizzati (uno slotparameters:di un Aggregate conrequired: trueche la Release lascia non compilato arresta la build conE0165, nominando lo slot e il punto in cui l’Aggregate lo dichiara); i controlli dei marcatori di obbligatorietà per template usanofaildi Sprig per sollevare un errore di template fatale che porta la stringa fornita.warn— emette una nota non fatale sul terminale dell’operatore. Aggrega non lo registra. I template che devono arrestare il rendering con un messaggio esplicativo dovrebbero usarefaildi Sprig; i template che devono ripiegare su un fallback senza arrestarsi dovrebbero affidarsi ai ramiif/elsestandard di Go.
Inventario degli helper tra motori (essenziale per gli autori di MappingLibrary)
I frammenti di MappingLibrary possono avere come destinazione uno dei due siti di consumo:
- Consumo lato Aggrega (
valuesMapping:della Recipe,injectMapping:della FeatureRecipe, ecc., valutati dal renderer di Aggrega). Gli helper disponibili sono: Sprig v3 completo (default,coalesce,quote,nindent,indent,b64enc, ecc.) più quelli propri di Aggrega (optional,capitalizedWords), eindexsi arresta su una chiave che la mappa non contiene. Gli helper per i template dei chart (include,tpl,required,warn) NON sono disponibili. - Consumo interno al chart Helm (contenuto
values.yamldel chart otemplates/*.yamldel chart renderizzati a valle dal motore di template proprio di Helm). Gli helper disponibili sono: Sprig v3 completo più gli helper per i template dei chart di Helm (include,tpl,required,warn). Gli helper propri di Aggrega NON sono disponibili, eindexlì è quello di Go stesso, che risponde a una chiave assente con un valore vuoto anziché arrestarsi.
I due insiemi di helper condividono la superficie di Sprig ma divergono sulle estensioni specifiche del motore. Le voci di MappingLibrary destinate al consumo interno al chart Helm usano le convenzioni di Helm (radice .Values.<key> con la V maiuscola, | default, composizione basata su include); le voci destinate al consumo lato Aggrega usano le convenzioni di Aggrega (.values.<key> in minuscolo, optional per il fallback sensibile alla presenza). L’entità di libreria memorizza i frammenti alla lettera; la forma di scrittura segue il punto in cui il frammento è destinato a essere renderizzato.
Gli helper personalizzati di Aggrega oltre a Sprig sono optional e capitalizedWords, entrambi documentati sopra, e il suo index sostituisce quello di Go, come documentato sopra. Il resto della superficie degli helper è esattamente l’insieme di Sprig v3.
Riferimenti incrociati
template-context-contract.md— i campi di runtime che i template leggono accanto agli helper di Sprig.expansion-matrix.md— ordine di valutazione per sito di template.05-templates.md— panoramica del templating e convenzioni di scrittura.- Documentazione di Sprig v3 — riferimento canonico per singola funzione.