Funkcje Sprig i funkcje pomocnicze
Silnik szablonów Aggrega udostępnia bibliotekę funkcji Sprig v3 oraz własne funkcje pomocnicze Aggrega (optional i capitalizedWords) w każdym szablonie Go, który ewaluuje renderer, a funkcję index z Go zastępuje taką, która zatrzymuje kompilację na kluczu, którego mapa nie zawiera. Autorzy piszący valuesMapping: w encji Recipe, injectMapping: w encji FeatureRecipe lub dowolną inną powierzchnię szablonów ewaluowaną przez renderer mają do dyspozycji pełny zestaw funkcji pomocniczych Sprig obok wbudowanych funkcji Go text/template oraz pól kontekstu środowiska uruchomieniowego opisanych w template-context-contract.md.
🔴 Sformułowanie „ewaluuje renderer” należy czytać dosłownie jako zakres, ponieważ jedna powierzchnia autorska leży poza nim. Ustrukturyzowana współrzędna source: jest rozwiązywana po to, aby można było przypiąć wskazywany przez nią artefakt, a to rozwiązywanie nie jest przebiegiem renderowania: rejestruje ono wyłącznie własne funkcje pomocnicze Aggrega, więc wywołanie Sprig w polu source: lub we wpisie locals:, który to pole odczytuje, zatrzymuje pobieranie. Wpis, którego nie odczytuje żadne pole source:, jest ewaluowany wyłącznie przez renderowanie, z pełnym zestawem. Rozwiązanie współrzędnej ustala, co zostanie przypięte, zamiast tworzyć artefakt, dlatego jej zestaw funkcji jest celowo węższy — zatrzymanie i przenośną formę do użycia zamiast tego opisuje errors/fatal-halts.md „Resolving a source: coordinate registers a narrower function set (Rozwiązywanie współrzędnej rejestruje węższy zestaw funkcji)”.
Zestaw Sprig jest rejestrowany samodzielnie na potrzeby interpolacji parametrów, a w powierzchniach szablonów wartości renderera razem z własnymi funkcjami pomocniczymi Aggrega.
Co jest podłączone
Sprig v3 udostępnia pełny zestaw swoich funkcji pomocniczych — około 200 funkcji w poniższych kategoriach. Ta strona opisuje kategorie w zarysie, podając w każdej najczęściej używane funkcje; kanoniczną dokumentacją poszczególnych funkcji jest dokumentacja źródłowa Sprig.
- Ciągi znaków —
upper,lower,title,trim,trimAll,trimPrefix,trimSuffix,replace,contains,hasPrefix,hasSuffix,substr,quote,squote,cat,indent,nindent,repeat, funkcje zmiany wielkości liter (snakecase,camelcase,kebabcase), funkcje skracania (abbrev,abbrevboth,trunc), funkcje sum kontrolnych (sha1sum,sha256sum,sha512sum,adler32sum),toString. - Listy —
list,tuple,first,last,rest,initial,append/push,prepend,concat,reverse,uniq,without,has,slice,chunk,join,splitList,split,splitn,sortAlpha,compact. - Słowniki —
dict,get,set,unset,hasKey,keys,values,pick,omit,pluck,merge,mergeOverwrite,dig,deepCopy. - Matematyka —
add,sub,mul,div,mod,add1,min,max,ceil,floor,roundoraz warianty dziesiętne z przyrostkiemf(addf,subf,mulf,divf,minf,maxf). - Konwersja —
int,int64,float64,atoi,toString,toDecimal,seq,until,untilStep. - Kodowanie —
b64enc,b64dec,b32enc,b32dec,toJson,toPrettyJson,toRawJson,fromJsonoraz warianty JSON z przedrostkiemmust, które zgłaszają błędy dekodowania zamiast po cichu zwracać wartość zerową. - Sprawdzanie typów —
typeOf,typeIs,typeIsLike,kindOf,kindIs,deepEqual,empty. - Wartości domyślne i sterowanie przepływem —
default,coalesce,all,any,ternary,fail(zgłasza błąd szablonu z własnym komunikatem — kanoniczny sposób przerwania renderowania komunikatem zabezpieczającym). - Wyrażenia regularne —
regexMatch,regexFind,regexFindAll,regexReplaceAll,regexReplaceAllLiteral,regexSplit,regexQuoteMetaoraz ścisłe warianty z przedrostkiemmust. - Ścieżki —
base,dir,clean,ext,isAbs(w stylu Unix);osBase,osClean,osDir,osExt,osIsAbs(zależne od systemu operacyjnego). - SemVer —
semver,semverCompare. - URL —
urlParse,urlJoin. - Daty —
ago,date,dateInZone,dateModify,duration,durationRound,htmlDate,htmlDateInZone,now,toDate,unixEpoch.
Zastrzeżenie dotyczące determinizmu
Aggrega gwarantuje identyczne bajt w bajt wyjście dla identycznego bajt w bajt wejścia. Część helperów Sprig odczytuje stan otoczenia i łamie tę gwarancję, gdy zostanie wywołana z szablonu. Autorzy powinni unikać następujących helperów w szablonach, które współtworzą renderowane artefakty:
- Odczyt zegara systemowego —
now,date,dateInZone,dateModify,htmlDate,htmlDateInZone,ago, gdy są wywoływane bez zamrożonego czasu odniesienia. - Generatory losowe —
randAlpha,randAlphaNum,randAscii,randNumeric,randBytes,randInt,uuidv4. - Odczyt środowiska —
env,expandenv(odczytują zmienne środowiskowe procesu, które różnią się między stacjami roboczymi operatorów a runnerami CI). - Rozwiązywanie nazw sieciowych —
getHostByName.
Silnik nie blokuje tych helperów; należą one do zestawu Sprig v3. Dyscyplinę unikania ich w szablonach na ścieżce renderowania utrzymują recenzenci oraz gwarancja deterministycznego wyjścia, na której polegają autorzy i katalog biblioteki standardowej.
Liczby w szablonie wartości
Liczba zapisana przez autora trafia do szablonu wartości jako liczba. Liczba całkowita jest typu integer i wypisuje się jako całkowita: 1000000 wypisuje się jako 1000000. Każda inna liczba wypisuje się w najkrótszej dokładnej postaci dziesiętnej, nigdy w postaci wykładniczej: zapisane 0.0000001 wypisuje się jako 0.0000001, a zapisane 1e21 jako 1000000000000000000000, niezależnie od tego, czy szablon zapisuje wartość bezpośrednio, czy zamienia ją na tekst za pomocą toString, quote, printf "%v" lub toJson. Liczba zwracana przez funkcję matematyczną — mulf, float64, round i im pokrewne — jest własną wartością tej funkcji i wypisuje się w jej własnej postaci, która dla bardzo małej lub bardzo dużej wartości jest wykładnicza: dla zapisanego 0.0000001 wyrażenie {{ mulf .values.ratio 1 }} wypisuje 1e-07.
Porównania — eq, ne, lt, le, gt i ge — odczytują dwie liczby według wartości, niezależnie od rodzaju, który niesie każdą z nich, więc zapisana przez autora liczba całkowita porównuje się z liczbą dziesiętną zapisaną w szablonie, a 3 równa się 3.0:
{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → trueLiczba nigdy nie jest porównywana z tekstem: każde z sześciu porównań, otrzymawszy liczbę i tekst w cudzysłowie, zatrzymuje kompilację, wskazując oba rodzaje. Należy porównać liczbę z liczbą zapisaną bez cudzysłowu lub najpierw zamienić ją na tekst:
{{ 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 → trueTym zatrzymaniem jest A value template failed while it ran (Szablon wartości zakończył się błędem podczas działania). Asercja odczytuje zapisaną przez autora liczbę w ten sam sposób; zob. Liczby na tej powierzchni.
Obecność i pustość — dwa różne pytania
Szablon zadaje o wartość jedno z dwóch pytań, a każde pytanie ma własne funkcje pomocnicze.
- Czy autor to zapisał?
hasKeyioptionalodpowiadają według obecności. Klucz zapisany przez autora jest obecny bez względu na to, co zawiera — łącznie z0,""ifalse— a nieobecny jest tylko klucz, który autor pominął. - Czy to jest puste?
default,with,ifiemptyodpowiadają według pustości.0,"",false, pusta lista, pusta mapa i nieobecna wartość są tam uznawane za puste, tak jak w Helm.
.values.replicas | hasKey .values "replicas" | optional .values "replicas" 1 | .values.replicas | default 1 | if .values.replicas |
|---|---|---|---|---|
| brak | false | 1 | 1 | false |
0 | true | 0 | 1 | false |
3 | true | 3 | 3 | true |
Wartość, która może zasadnie wynosić 0, "" lub false — zerowa liczba replik, zerowy limit czasu, wyłączona flaga — sprawdza się za pomocą hasKey lub optional, aby 0 autora trafiło do wyjścia jako 0. default, with i if pasują do wartości, której pusta postać nie niesie własnego znaczenia, gdzie „puste” i „niezapisane” można traktować tak samo. Dany klucz należy odczytywać w szablonie w jeden sposób: klucz, który szablon odczytuje także jako ścieżkę z kropkami, jest uznawany za obecny, jak opisuje ograniczenie optional.
Funkcje pomocnicze specyficzne dla Aggrega
optional — wartość zastępcza uwzględniająca obecność klucza
optional <map> <key> <fallback> zwraca wartość pod kluczem <key> w <map>, jeśli klucz jest obecny, a w przeciwnym razie zwraca <fallback>. W odróżnieniu od funkcji default z Sprig, optional odróżnia „brak klucza” od „klucza obecnego z wartością zerową, pustą lub fałszywą”.
Sygnatura przyjmuje mapę i klucz jako osobne argumenty, ponieważ wartość przekazana przez operator | szablonów Go traci dostęp do swojej mapy nadrzędnej. Bez mapy nadrzędnej w zasięgu nie można sprawdzić obecności klucza.
Sprawdzanie obecności ma jedno ograniczenie, które wynika z szablonu, a nie z funkcji pomocniczej: szablon wartości odczytuje nieobecny klucz jako nic, co realizuje, podstawiając pustą wartość pod każdy nieobecny klucz, który szablon wskazuje jako ścieżkę z kropkami i odczytuje jako wartość. Dlatego szablon, który odczytuje jeden klucz zarówno przez optional, jak i jako taką ścieżkę, zastaje ten klucz obecny i pusty, i otrzymuje pustą wartość zamiast wartości zastępczej. Jeśli w danym szablonie odczytuje się klucz tylko w jeden sposób, obie odpowiedzi są zgodne.
# 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 → 0Ostatni przypadek to rozróżnienie, którego funkcja default z Sprig nie potrafi przeprowadzić. {{ .infra.replicas | default 1 }} zwraca 1 niezależnie od tego, czy replicas zapisano jako 0, czy pominięto — to utożsamienie uniemożliwia uprawnione wzorce skalowania do zera, braku ponowień, braku limitu czasu i flag ustawionych na fałsz.
Konwencja cytowania kluczy: preferowane są grawisy. Szablony Go akceptują jako argument klucza zarówno literały w cudzysłowach ("replicas"), jak i w grawisach (`replicas`); oba dają ten sam ciąg w czasie ewaluacji szablonu. Przykłady w katalogu i dokumentacji jednolicie używają formy z grawisami, ponieważ jest bezpieczna dla YAML w każdym kontekście cytowania. Klucz w cudzysłowach wewnątrz skalara YAML w cudzysłowach kończy ciąg YAML w połowie szablonu:
# 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 }}"Gdy szablon znajduje się w blokowym skalarze YAML (forma |) lub jako skalar bez cudzysłowów, obie formy renderują się poprawnie. Gdy szablon jest osadzony w skalarze YAML w cudzysłowach (wzorzec field: "{{ ... }}", w którym wartość pola jest szablonem), grawisy są wymagane. Jedna konwencja (zawsze grawisy) całkowicie omija tę pułapkę cytowania YAML.
Kiedy wybrać optional zamiast default. Należy używać optional, gdy pole może być w uprawniony sposób zerowe, puste lub fałszywe, a autor katalogu musi odróżnić „autor tego nie ustawił” od „autor ustawił wartość fałszywą”. Funkcji default należy używać, gdy utożsamienie jest akceptowalne (np. pola tekstowe, w których pusta wartość jest nieprawidłowa; pola liczbowe, w których zero jest nieprawidłowe).
Dostępność według powierzchni. optional jest zarejestrowana na każdej powierzchni, którą ewaluuje renderer: na powierzchniach szablonów wartości (valuesMapping w encji Recipe, injectMapping w encji FeatureRecipe, provides, pipeline.with, treść encji Workload), w ewaluatorze asercji oraz w szablonach ścieżek (directory: / subDirectory: na granicach encji Release). Na powierzchni szablonów ścieżek różni się nie zestaw funkcji pomocniczych, lecz polityka brakujących kluczy: szablon ścieżki traktuje nieobecny klucz jako błąd, a nie jako pustą wartość, ponieważ po cichu pusty segment ścieżki daje uszkodzony układ systemu plików, wykrywany dopiero po kompilacji. optional odczytuje klucz, zanim ta ścisła polityka zadziała, i dlatego można jej tam używać.
capitalizedWords — sprowadzenie nazwy do liter i cyfr
capitalizedWords <string> odczytuje argument jako słowa rozdzielone ciągami dowolnych znaków spoza liter i cyfr ASCII, zmienia pierwszą literę każdego słowa na wielką i łączy je. Każdy znak wyniku jest literą lub cyfrą.
Funkcja istnieje, ponieważ niektóre platformy docelowe akceptują w nazwach, którymi adresują zasoby, tylko litery i cyfry, podczas gdy identyfikator komponentu może w uprawniony sposób zawierać kropkę, łącznik lub podkreślenie. Ręczne pisanie tej konwersji w każdej encji Recipe, która jej potrzebuje, daje kilka zapisów tej samej idei; jedna funkcja pomocnicza daje każdemu autorowi tę samą odpowiedź.
# 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🔴 Wynik nie identyfikuje nazwy, z której powstał. Każdy separator jest usuwany, więc dwa identyfikatory różniące się tylko położeniem separatorów dają ten sam wynik — payments-db i payments_db dają PaymentsDb. Funkcja pomocnicza nie może tego wykryć, ponieważ widzi jedną nazwę naraz; wychwycenie tego należy do tego, co adresuje zasoby wynikiem. Platforma docelowa, która to robi, odrzuca kolizję zamiast emitować wdrożenie bez jednego z dwóch zasobów: przy kompilacji dla CloudFormation dwa komponenty, których identyfikatory sprowadzają się do jednej nazwy, zatrzymują kompilację, a komunikat wymienia każdy identyfikator, który do niej doprowadził. Jeśli identyfikatory różnią się czymś więcej niż interpunkcją, problem nie występuje.
Dostępność według powierzchni. capitalizedWords jest zarejestrowana wszędzie tam, gdzie optional: na każdej powierzchni, którą ewaluuje renderer, oraz przy rozwiązywaniu ustrukturyzowanej współrzędnej source:. Nie jest dostępna w interpolacji parametrów encji Aggregate, która oferuje wyłącznie zestaw Sprig.
index — klucz, który mapa musi zawierać
index <collection> <key>... odczytuje kolekcję według pozycji lub klucza, tak jak natywna funkcja index z Go — z jedną różnicą. Gdy kolekcja jest mapą, a mapa nie zawiera klucza, index zatrzymuje kompilację i wskazuje klucz, podczas gdy wersja z Go odpowiada pustą wartością, wypisywaną jako dosłowny tekst <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")Jest to odczyt do użycia tam, gdzie klucz musi istnieć — dane uwierzytelniające odczytywane pod nazwą zmiennej obliczoną przez encję Recipe, klucz publikowany przez inny szablon — tak aby brakujący klucz zatrzymał kompilację, zamiast trafić do artefaktu jako <no value>. Tam, gdzie klucz może w uprawniony sposób nie istnieć, należy najpierw to sprawdzić: {{ optional .values `replicas` 1 }} dostarcza wartość zastępczą, get z Sprig zwraca pusty ciąg, a hasKey sprawdza bez odczytu. Odczyt przez index, a następnie zastosowanie default nie dostarcza wartości zastępczej, ponieważ zatrzymanie następuje, zanim default się wykona. Klucz obecny z wartością null nie jest nieobecny: index go zwraca i jest on wypisywany jako <no value>.
Zatrzymanie jest właściwością wyłącznie funkcji index i jest takie samo na każdej powierzchni — w szablonach wartości, ewaluatorze asercji, szablonach ścieżek, ustrukturyzowanej współrzędnej source:, interpolacji parametrów encji Aggregate, predykacie validate: parametru oraz predykatach x-aggrega-when: / x-aggrega-validate: schematu. Odczyt nieustawionego klucza przez kropkę podlega polityce brakujących kluczy danej powierzchni i nie jest tym objęty. Zatrzymanie opisano w errors/fatal-halts.md: „A template indexes a map with a key the map does not hold (Szablon indeksuje mapę kluczem, którego mapa nie zawiera)”.
Popularne funkcje pomocnicze NIEDOSTĘPNE
Helm rozszerza text/template z Go o funkcje pomocnicze szablonów chartów, które często są mylone z ogólnymi funkcjami pomocniczymi Sprig. Żadna z nich nie jest zarejestrowana w rendererze Aggrega. Szablony, które ewaluuje renderer Aggrega (Recipe valuesMapping:, FeatureRecipe injectMapping:, provides, treść Workload, ewaluator asercji), nie mogą ich wywoływać:
include— preferowana w Helm forma wywoływania zdefiniowanego fragmentu szablonu z wynikiem tekstowym, który można przekazać potokiem. Renderer Aggrega jej nie rejestruje. Zamiast niej należy użyć standardowego{{ template "name" . }}z szablonów Go (forma działająca wyłącznie przez efekt uboczny); w przypadku wyniku przekazywanego potokiem należy składać fragmenty MappingLibrary i dyrektywy$import:.tpl— ponownie ewaluuje ciąg znaków jako zagnieżdżony szablon względem bieżącego kontekstu. Aggrega jej nie rejestruje; zagnieżdżona ponowna ewaluacja nie należy do powierzchni szablonów. Autorzy potrzebujący wartości obliczanych powinni składać je za pomocą funkcji tekstowych Sprig i emitować wartość końcową bezpośrednio.required— przerywa renderowanie chartu z niestandardowym komunikatem, gdy brakuje wskazanej wartości. Aggrega jej nie rejestruje. Wymuszanie pól wymaganych w Aggrega odbywa się w warstwie typowanego kontraktu parametrów (slotparameters:encji Aggregate zrequired: true, którego encja Release nie wypełni, zatrzymuje kompilację zE0165, wskazując slot i miejsce, w którym encja Aggregate go deklaruje); kontrole znaczników wymagalności w poszczególnych szablonach używająfailze Sprig, aby zgłosić krytyczny błąd szablonu zawierający podany ciąg.warn— wypisuje niekrytyczną uwagę w terminalu operatora. Aggrega jej nie rejestruje. Szablony, które muszą zatrzymać renderowanie z komunikatem wyjaśniającym, powinny używaćfailze Sprig; szablony, które muszą zastosować wartość zastępczą bez zatrzymywania, powinny opierać się na standardowych gałęziachif/elsez Go.
Zestawienie funkcji pomocniczych w obu silnikach (kluczowe dla autorów MappingLibrary)
Fragmenty MappingLibrary mogą być przeznaczone dla jednego z dwóch miejsc użycia:
- Użycie po stronie Aggrega (Recipe
valuesMapping:, FeatureRecipeinjectMapping:itp., ewaluowane przez renderer Aggrega). Dostępne funkcje pomocnicze to: pełny Sprig v3 (default,coalesce,quote,nindent,indent,b64encitp.) oraz własne funkcje Aggrega (optional,capitalizedWords), aindexzatrzymuje kompilację przy kluczu, którego mapa nie zawiera. Funkcje pomocnicze szablonów chartów (include,tpl,required,warn) NIE są dostępne. - Użycie wewnątrz chartu Helm (zawartość
values.yamlchartu lub plikitemplates/*.yamlchartu renderowane dalej przez własny silnik szablonów Helm). Dostępne funkcje pomocnicze to: pełny Sprig v3 oraz funkcje pomocnicze szablonów chartów Helm (include,tpl,required,warn). Własne funkcje pomocnicze Aggrega NIE są dostępne, aindexjest tam funkcją z Go, która na brak klucza odpowiada pustą wartością zamiast zatrzymania.
Oba zestawy funkcji pomocniczych dzielą powierzchnię Sprig, ale różnią się rozszerzeniami specyficznymi dla silnika. Wpisy MappingLibrary przeznaczone do użycia wewnątrz chartu Helm stosują konwencje Helm (korzeń .Values.<key> z wielką literą V, | default, składanie oparte na include); wpisy przeznaczone do użycia po stronie Aggrega stosują konwencje Aggrega (małe litery w .values.<key>, optional jako wartość zastępcza uwzględniająca obecność klucza). Encja biblioteki przechowuje fragmenty dosłownie; kształt autorski zależy od miejsca, w którym fragment ma być renderowany.
Własne funkcje pomocnicze Aggrega dodane do Sprig to optional i capitalizedWords, obie opisane powyżej, a jej index zastępuje funkcję z Go, jak opisano powyżej. Pozostała część powierzchni funkcji pomocniczych to dokładnie zestaw Sprig v3.
Odsyłacze
template-context-contract.md— pola środowiska uruchomieniowego, które szablony odczytują obok helperów Sprig.expansion-matrix.md— kolejność ewaluacji dla poszczególnych miejsc szablonów.05-templates.md— przegląd szablonów i konwencje tworzenia.- Dokumentacja Sprig v3 — kanoniczny opis poszczególnych funkcji.