Sprig-Funktionen und Helfer
Die Template-Engine von Aggrega bindet die Funktionsbibliothek Sprig v3 sowie die eigenen Helfer von Aggrega (optional und capitalizedWords) in jedes Go-Template ein, das der Renderer auswertet, und ersetzt die Funktion index von Go durch eine, die bei einem Map-Schlüssel abbricht, den die Map nicht enthält. Autoren, die valuesMapping: eines Recipe, injectMapping: eines FeatureRecipe oder eine andere Template-Oberfläche schreiben, die der Renderer auswertet, steht der vollständige Sprig-Helfersatz zur Verfügung, neben den eingebauten Funktionen von Go text/template und den Laufzeitkontextfeldern, die in template-context-contract.md dokumentiert sind.
🔴 Lesen Sie „das der Renderer auswertet“ als den Geltungsbereich, der es ist, denn eine Authoring-Oberfläche liegt außerhalb davon. Eine strukturierte Koordinate source: wird aufgelöst, damit das Artefakt, das sie nennt, fixiert werden kann, und diese Auflösung ist kein Rendering-Durchlauf: Sie registriert die eigenen Helfer von Aggrega und nichts anderes, daher bricht ein Sprig-Aufruf in einem Feld source: oder in einem Eintrag locals:, den es liest, den Pull ab. Ein Eintrag, den kein Feld source: liest, wird allein vom Rendering ausgewertet, mit dem vollständigen Satz. Das Auflösen einer Koordinate legt fest, was fixiert wird, statt ein Artefakt zu erzeugen, weshalb ihr Funktionssatz bewusst enger ist — siehe errors/fatal-halts.md „Resolving a source: coordinate registers a narrower function set (Das Auflösen einer source-Koordinate registriert eine engere Funktionsmenge)“ für den Abbruch und die portable Form, die stattdessen zu verwenden ist.
Der Sprig-Satz wird für die Parameterinterpolation allein registriert und zusammen mit den eigenen Helfern von Aggrega auf den Value-Template-Oberflächen des Renderers.
Was eingebunden ist
Sprig v3 stellt seine vollständige Helfer-Oberfläche bereit — rund 200 Funktionen in den unten aufgeführten Kategorien. Diese Seite skizziert die Kategorien mit den gängigen Helfern in jeder; die kanonische Referenz pro Funktion ist die Upstream-Dokumentation von Sprig.
- Zeichenketten —
upper,lower,title,trim,trimAll,trimPrefix,trimSuffix,replace,contains,hasPrefix,hasSuffix,substr,quote,squote,cat,indent,nindent,repeat, Helfer für Schreibweisen (snakecase,camelcase,kebabcase), Helfer für Abkürzungen (abbrev,abbrevboth,trunc), Helfer für Prüfsummen (sha1sum,sha256sum,sha512sum,adler32sum),toString. - Listen —
list,tuple,first,last,rest,initial,append/push,prepend,concat,reverse,uniq,without,has,slice,chunk,join,splitList,split,splitn,sortAlpha,compact. - Wörterbücher —
dict,get,set,unset,hasKey,keys,values,pick,omit,pluck,merge,mergeOverwrite,dig,deepCopy. - Mathematik —
add,sub,mul,div,mod,add1,min,max,ceil,floor,round, dazu die dezimalen Varianten mit dem Suffixf(addf,subf,mulf,divf,minf,maxf). - Konvertierung —
int,int64,float64,atoi,toString,toDecimal,seq,until,untilStep. - Kodierung —
b64enc,b64dec,b32enc,b32dec,toJson,toPrettyJson,toRawJson,fromJson, dazu die JSON-Varianten mit dem Präfixmust, die Dekodierfehler sichtbar machen, statt stillschweigend auf null zu setzen. - Typprüfungen —
typeOf,typeIs,typeIsLike,kindOf,kindIs,deepEqual,empty. - Standardwerte und Ablauf —
default,coalesce,all,any,ternary,fail(löst einen Template-Fehler mit einer eigenen Meldung aus — der kanonische Weg, ein Rendering mit einer Schutzmeldung abzubrechen). - Regex —
regexMatch,regexFind,regexFindAll,regexReplaceAll,regexReplaceAllLiteral,regexSplit,regexQuoteMeta, dazu die strikten Varianten mit dem Präfixmust. - Pfade —
base,dir,clean,ext,isAbs(im Unix-Stil);osBase,osClean,osDir,osExt,osIsAbs(betriebssystemabhängig). - SemVer —
semver,semverCompare. - URL —
urlParse,urlJoin. - Datumsangaben —
ago,date,dateInZone,dateModify,duration,durationRound,htmlDate,htmlDateInZone,now,toDate,unixEpoch.
Vorbehalt zum Determinismus
Aggrega garantiert byteidentische Ausgabe für byteidentische Eingabe. Eine Teilmenge der Sprig-Helfer liest Umgebungszustand und bricht diese Garantie, wenn sie aus einem Template aufgerufen wird. Autoren sollten die folgenden Helfer in Template-Oberflächen vermeiden, die zu gerenderten Artefakten beitragen:
- Leser der Systemuhr —
now,date,dateInZone,dateModify,htmlDate,htmlDateInZone,ago, wenn ohne eingefrorene Referenzzeit aufgerufen. - Zufallsgeneratoren —
randAlpha,randAlphaNum,randAscii,randNumeric,randBytes,randInt,uuidv4. - Umgebungsleser —
env,expandenv(lesen Umgebungsvariablen des Prozesses, die sich zwischen den Arbeitsplatzrechnern der Operatoren und CI-Runnern unterscheiden). - Netzwerk-Resolver —
getHostByName.
Diese Helfer werden von der Engine nicht blockiert; sie gehören zum Sprig-v3-Satz. Die Disziplin, sie in Templates des Render-Pfads zu vermeiden, wird von Reviewern und von der Garantie deterministischer Ausgabe getragen, auf die sich Autoren und der Katalog der Standardbibliothek verlassen.
Zahlen in einem Value-Template
Eine Zahl, die ein Autor schreibt, erreicht ein Value-Template als Zahl. Eine Zahl ohne Nachkommastellen ist ein Integer und wird ganz ausgegeben: 1000000 gibt 1000000 aus. Jede andere Zahl wird in ihrer kürzesten exakten Dezimalform ausgegeben, nie in Exponentialschreibweise: Ein vom Autor geschriebenes 0.0000001 gibt 0.0000001 aus, und ein vom Autor geschriebenes 1e21 gibt 1000000000000000000000 aus, ob das Template den Wert direkt schreibt oder ihn mit toString, quote, printf "%v" oder toJson in Text umwandelt. Eine Zahl, die eine mathematische Funktion zurückgibt — mulf, float64, round und verwandte Funktionen —, ist der eigene Wert dieser Funktion und wird in deren eigener Form ausgegeben, die für einen sehr kleinen oder sehr großen Wert die Exponentialschreibweise ist: {{ mulf .values.ratio 1 }} gibt für ein vom Autor geschriebenes 0.0000001 den Wert 1e-07 aus.
Die Vergleiche — eq, ne, lt, le, gt und ge — lesen zwei Zahlen nach ihrem Wert, gleich welche Art jede trägt, sodass sich eine vom Autor geschriebene Ganzzahl mit einer im Template geschriebenen Dezimalzahl vergleichen lässt und 3 gleich 3.0 ist:
{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → trueEine Zahl wird nie mit einem Text verglichen: Jeder der sechs bricht, wenn er eine Zahl und einen Text in Anführungszeichen erhält, den Build ab und nennt beide Arten. Vergleichen Sie die Zahl mit einer ohne Anführungszeichen geschriebenen Zahl, oder wandeln Sie sie zuerst in Text um:
{{ 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 → trueDer Abbruch ist A value template failed while it ran (Ein Werte-Template ist während der Ausführung fehlgeschlagen). Eine Assertion liest eine vom Autor geschriebene Zahl auf dieselbe Weise; siehe Zahlen auf dieser Oberfläche.
Vorhandensein und Leere — zwei verschiedene Fragen
Ein Template stellt über einen Wert eine von zwei Fragen, und jede Frage hat ihre eigenen Helfer.
- Hat der Autor ihn geschrieben?
hasKeyundoptionalantworten nach dem Vorhandensein. Ein Schlüssel, den der Autor geschrieben hat, ist vorhanden, was immer er enthält —0,""undfalseeingeschlossen —, und nur ein Schlüssel, den der Autor weggelassen hat, fehlt. - Ist er leer?
default,with,ifundemptyantworten nach der Leere.0,"",false, eine leere Liste, eine leere Map und ein fehlender Wert gelten dort alle als leer, wie in Helm.
.values.replicas | hasKey .values "replicas" | optional .values "replicas" 1 | .values.replicas | default 1 | if .values.replicas |
|---|---|---|---|---|
| fehlend | false | 1 | 1 | false |
0 | true | 0 | 1 | false |
3 | true | 3 | 3 | true |
Ein Wert, der legitimerweise 0, "" oder false sein kann — eine Replikatanzahl von null, ein Timeout von null, ein ausgeschaltetes Flag —, wird mit hasKey oder optional geprüft, sodass die 0 des Autors als 0 in der Ausgabe ankommt. default, with und if passen zu einem Wert, dessen leere Form keine eigene Bedeutung trägt, wo „leer“ und „nicht geschrieben“ gleich behandelt werden dürfen. Lesen Sie einen bestimmten Schlüssel pro Template auf eine einzige Weise: Ein Schlüssel, den das Template auch als gepunkteten Pfad liest, gilt als vorhanden, wie die Einschränkung von optional beschreibt.
Aggrega-spezifische Helfer
optional — Fallback, der das Vorhandensein berücksichtigt
optional <map> <key> <fallback> gibt den Wert unter <key> in <map> zurück, wenn der Schlüssel vorhanden ist, andernfalls <fallback>. Anders als default von Sprig unterscheidet optional zwischen „Schlüssel fehlt“ und „Schlüssel vorhanden mit einem Null-, leeren oder falschen Wert“.
Die Signatur nimmt die Map und den Schlüssel als getrennte Argumente, weil ein Wert, der durch den Operator | eines Go-Templates geleitet wurde, den Zugriff auf seine übergeordnete Map verloren hat. Ohne die übergeordnete Map im Gültigkeitsbereich lässt sich das Vorhandensein nicht prüfen.
Eine Einschränkung der Vorhandenseinsprüfung, und sie kommt vom Template statt vom Helfer: Ein Value-Template liest einen fehlenden Schlüssel als nichts, was es tut, indem es an jedem fehlenden Schlüssel, den das Template als gepunkteten Pfad nennt und als Wert liest, einen leeren Wert liefert. Ein Template, das einen Schlüssel sowohl über optional als auch als einen solchen Pfad liest, findet diesen Schlüssel daher vorhanden und leer und erhält den leeren Wert statt des Fallbacks. Lesen Sie einen Schlüssel pro Template auf eine einzige Weise, und die beiden Antworten stimmen überein.
# 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 → 0Der letzte Fall ist die Unterscheidung, die default von Sprig nicht treffen kann. {{ .infra.replicas | default 1 }} gibt 1 zurück, ob replicas als 0 geschrieben oder weggelassen wurde — die Vermischung, die legitime Muster wie Scale-to-Zero, keine Wiederholungen, kein Timeout und ausgeschaltete Flags verhindert.
Konvention für das Quoten von Schlüsseln: Backticks bevorzugen. Go-Templates akzeptieren für das Schlüsselargument sowohl Zeichenkettenliterale in doppelten Anführungszeichen ("replicas") als auch in Backticks (`replicas`); beide erzeugen zur Auswertungszeit des Templates dieselbe Zeichenkette. Die Beispiele des Katalogs und der Dokumentation verwenden einheitlich die Backtick-Form, weil sie in jedem Quoting-Kontext YAML-sicher ist. Ein Schlüssel in doppelten Anführungszeichen innerhalb eines YAML-Skalars in doppelten Anführungszeichen beendet die YAML-Zeichenkette mitten im 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 }}"Wenn das Template in einem YAML-Block-Skalar (Form |) oder als Skalar mit nacktem Wert steht, werden beide Formen korrekt gerendert. Wenn das Template in einen YAML-Skalar in doppelten Anführungszeichen eingebettet ist (das Muster field: "{{ ... }}", ein Feldwert als Template), sind Backticks erforderlich. Die eine Konvention (immer Backticks) vermeidet die YAML-Quoting-Falle vollständig.
Wann optional gegenüber default vorzuziehen ist. Verwenden Sie optional, wenn das Feld legitimerweise null, leer oder falsch sein kann und der Katalogautor „der Autor hat das nicht gesetzt“ von „der Autor hat das auf einen falsy-Wert gesetzt“ unterscheiden muss. Verwenden Sie default, wenn die Vermischung akzeptabel ist (z. B. Zeichenkettenfelder, bei denen leer ungültig ist; numerische Felder, bei denen null ungültig ist).
Verfügbarkeit pro Oberfläche. optional ist auf jeder Oberfläche registriert, die der Renderer auswertet: den Value-Template-Oberflächen (valuesMapping eines Recipe, injectMapping eines FeatureRecipe, provides, pipeline.with, dem Workload-Body), dem Assertion-Evaluator und Pfad-Templates (directory: / subDirectory: an Release-Boundaries). Was sich auf der Pfad-Template-Oberfläche unterscheidet, ist nicht der Helfersatz, sondern die Richtlinie für fehlende Schlüssel: Ein Pfad-Template behandelt einen fehlenden Schlüssel als Fehler statt als leer, weil ein stillschweigend leeres Pfadsegment ein defektes Dateisystem-Layout erzeugt, das erst nach dem Build entdeckt wird. optional liest einen Schlüssel, ohne dass diese strikte Richtlinie zuerst greift, und genau das macht ihn dort nutzbar.
capitalizedWords — einen Namen auf Buchstaben und Ziffern reduzieren
capitalizedWords <string> liest sein Argument als Wörter, die durch Folgen beliebiger Zeichen außerhalb der ASCII-Buchstaben und -Ziffern getrennt sind, schreibt den ersten Buchstaben jedes Wortes groß und fügt sie zusammen. Jedes Zeichen des Ergebnisses ist ein Buchstabe oder eine Ziffer.
Er existiert, weil manche Ziele in den Namen, unter denen sie Ressourcen adressieren, nur Buchstaben und Ziffern akzeptieren, während eine Komponenten-ID legitimerweise einen Punkt, einen Bindestrich oder einen Unterstrich enthalten kann. Diese Umwandlung in jedem Recipe, das sie benötigt, von Hand zu schreiben, erzeugt mehrere Schreibweisen einer Idee; ein einziger Helfer gibt jedem Autor dieselbe Antwort.
# 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🔴 Das Ergebnis identifiziert nicht den Namen, aus dem es stammt. Jedes Trennzeichen wird entfernt, sodass zwei IDs, die sich nur in der Position ihrer Trennzeichen unterscheiden, dasselbe Ergebnis erreichen — payments-db und payments_db ergeben beide PaymentsDb. Der Helfer kann das nicht erkennen, weil er jeweils nur einen Namen sieht; es abzufangen ist Sache dessen, was Ressourcen über das Ergebnis adressiert. Ein Ziel, das dies tut, weist die Kollision zurück, statt eine Bereitstellung auszugeben, in der einer der beiden fehlt: Beim Build für CloudFormation brechen zwei Komponenten, deren IDs auf einen Namen zusammenfallen, den Build ab, und die Meldung nennt jede ID, die ihn erreicht hat. Wählen Sie IDs, die sich in mehr als der Zeichensetzung unterscheiden, und die Frage stellt sich nicht.
Verfügbarkeit pro Oberfläche. capitalizedWords ist überall registriert, wo optional es ist: auf jeder Oberfläche, die der Renderer auswertet, und bei der Auflösung einer strukturierten Koordinate source:. In der Parameterinterpolation des Aggregate, die allein den Sprig-Satz bietet, ist er nicht verfügbar.
index — ein Schlüssel, den die Map enthalten muss
index <collection> <key>... liest eine Sammlung nach Position oder nach Schlüssel, wie es das eigene index von Go tut — mit einem Unterschied. Wenn die Sammlung eine Map ist und die Map den Schlüssel nicht enthält, bricht index den Build ab und nennt den Schlüssel, während das von Go mit einem leeren Wert antwortet, der als der literale Text <no value> ausgegeben wird.
# 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")Es ist der Lesezugriff für Fälle, in denen der Schlüssel vorhanden sein muss — ein Credential, das unter dem Variablennamen gelesen wird, den das Recipe berechnet hat, ein Schlüssel, den ein anderes Template veröffentlicht —, sodass ein fehlender Schlüssel den Build stoppt, statt als <no value> in ein Artefakt zu gelangen. Wo der Schlüssel legitimerweise fehlen darf, prüfen Sie ihn zuerst: {{ optional .values `replicas` 1 }} liefert einen Fallback, get von Sprig gibt eine leere Zeichenkette zurück, und hasKey prüft, ohne zu lesen. Über index zu lesen und dann default anzuwenden liefert keinen Fallback, weil der Abbruch erfolgt, bevor default läuft. Ein Schlüssel, der vorhanden ist und null enthält, fehlt nicht: index gibt ihn zurück, und er wird als <no value> ausgegeben.
Der Abbruch ist eine Eigenschaft von index allein, und er ist auf jeder Oberfläche derselbe — die Value-Templates, der Assertion-Evaluator, Pfad-Templates, eine strukturierte Koordinate source:, die Parameterinterpolation des Aggregate, das Prädikat validate: eines Parameters und die Prädikate x-aggrega-when: / x-aggrega-validate: eines Schemas. Ein Punktzugriff auf einen nicht gesetzten Schlüssel folgt der eigenen Richtlinie seiner Oberfläche für fehlende Schlüssel und ist nicht betroffen. Der Abbruch ist in errors/fatal-halts.md „A template indexes a map with a key the map does not hold (Ein Template indiziert eine Map mit einem Schlüssel, den die Map nicht enthält)“ dokumentiert.
Gängige Helfer, die NICHT verfügbar sind
Helm erweitert text/template von Go um Chart-Template-Helfer, die häufig für allgemeine Sprig-Helfer gehalten werden. Keiner davon ist im Renderer von Aggrega registriert. Templates, die der Aggrega-Renderer auswertet (valuesMapping: eines Recipe, injectMapping: eines FeatureRecipe, provides, Workload-Body, der Assertion-Evaluator), können sie nicht aufrufen:
include— die von Helm bevorzugte Form, ein definiertes Template-Fragment mit einer per Pipe weiterleitbaren Zeichenkettenausgabe aufzurufen. Der Renderer von Aggrega registriert es nicht. Verwenden Sie stattdessen{{ template "name" . }}des Standard-Go-Templates (die Form nur mit Seiteneffekten); für eine per Pipe weiterleitbare Ausgabe komponieren Sie mit MappingLibrary-Fragmenten und Direktiven$import:.tpl— wertet eine Zeichenkette als verschachteltes Template gegen den aktuellen Kontext erneut aus. Aggrega registriert es nicht; verschachtelte Neuauswertung ist nicht Teil der Template-Oberfläche. Autoren, die berechnete Werte benötigen, sollten sie mit den Zeichenketten-Helfern von Sprig zusammensetzen und den endgültigen Wert direkt ausgeben.required— lässt das Chart-Rendering mit einer eigenen Meldung fehlschlagen, wenn der genannte Wert fehlt. Aggrega registriert es nicht. Die Durchsetzung von Pflichtfeldern liegt bei Aggrega auf der Ebene der typisierten Parameterverträge (ein Slotparameters:eines Aggregate mitrequired: true, den das Release nicht befüllt, bricht den Build mitE0165ab und nennt den Slot und die Stelle, an der das Aggregate ihn deklariert); Prüfungen von Pflichtmarkierungen pro Template verwendenfailvon Sprig, um einen fatalen Template-Fehler mit der übergebenen Zeichenkette auszulösen.warn— gibt einen nicht fatalen Hinweis im Terminal des Operators aus. Aggrega registriert es nicht. Templates, die das Rendering mit einer erklärenden Meldung abbrechen müssen, solltenfailvon Sprig verwenden; Templates, die ohne Abbruch auf einen Fallback zurückgreifen müssen, sollten sich auf die Standard-Go-Verzweigungenif/elsestützen.
Engine-übergreifendes Helfer-Inventar (maßgeblich für MappingLibrary-Autoren)
MappingLibrary-Fragmente können eine von zwei Verbrauchsstellen zum Ziel haben:
- Verbrauch auf Aggrega-Seite (
valuesMapping:eines Recipe,injectMapping:eines FeatureRecipe usw., ausgewertet vom Renderer von Aggrega). Die verfügbaren Helfer sind: das vollständige Sprig v3 (default,coalesce,quote,nindent,indent,b64encusw.) plus die eigenen von Aggrega (optional,capitalizedWords), undindexbricht bei einem Map-Schlüssel ab, den die Map nicht enthält. Die Chart-Template-Helfer (include,tpl,required,warn) sind NICHT verfügbar. - Chart-interner Verbrauch in Helm (Inhalt von
values.yamldes Charts odertemplates/*.yamldes Charts, nachgelagert von der eigenen Template-Engine von Helm gerendert). Die verfügbaren Helfer sind: das vollständige Sprig v3 plus die Chart-Template-Helfer von Helm (include,tpl,required,warn). Die eigenen Helfer von Aggrega sind NICHT verfügbar, undindexist dort das eigene von Go, das einen fehlenden Schlüssel mit einem leeren Wert beantwortet, statt abzubrechen.
Die beiden Helfersätze teilen die Sprig-Oberfläche, gehen aber bei den Engine-spezifischen Erweiterungen auseinander. MappingLibrary-Einträge, die auf den Chart-internen Verbrauch in Helm zielen, verwenden Helm-Konventionen (Wurzel .Values.<key> mit großem V, | default, auf include basierende Komposition); Einträge, die auf den Verbrauch auf Aggrega-Seite zielen, verwenden Aggrega-Konventionen (kleingeschriebenes .values.<key>, optional für den Fallback, der das Vorhandensein berücksichtigt). Die Bibliotheksentität speichert Fragmente unverändert; die Authoring-Form folgt dem Ort, an dem das Fragment gerendert werden soll.
Die eigenen Helfer von Aggrega zusätzlich zu Sprig sind optional und capitalizedWords, beide oben dokumentiert, und sein index ersetzt das von Go, wie oben dokumentiert. Der Rest der Helfer-Oberfläche ist genau der Sprig-v3-Satz.
Querverweise
template-context-contract.md— die Laufzeitfelder, die Templates neben den Sprig-Helfern lesen.expansion-matrix.md— Auswertungsreihenfolge pro Template-Stelle.05-templates.md— Überblick über das Templating und Authoring-Konventionen.- Sprig-v3-Dokumentation — kanonische Referenz pro Funktion.