Fungsi dan helper Sprig
Mesin templat Aggrega memasang pustaka fungsi Sprig v3 beserta helper milik Aggrega sendiri (optional dan capitalizedWords) ke dalam setiap templat Go yang dievaluasi oleh renderer, dan mengganti index bawaan Go dengan versi yang berhenti pada kunci map yang tidak dimiliki oleh map tersebut. Penulis yang menulis valuesMapping: pada Recipe, injectMapping: pada FeatureRecipe, atau permukaan templat lain yang dievaluasi oleh renderer dapat menggunakan seluruh set helper Sprig bersama fungsi bawaan Go text/template dan field konteks runtime yang didokumentasikan dalam template-context-contract.md.
🔴 Pahami “dievaluasi oleh renderer” sebagai cakupan sebagaimana adanya, karena ada satu permukaan penulisan yang berada di luarnya. Koordinat source: terstruktur di-resolve agar artefak yang disebutnya dapat di-pin, dan resolusi tersebut bukan tahap rendering: resolusi itu mendaftarkan helper milik Aggrega sendiri dan tidak ada yang lain, sehingga pemanggilan Sprig di field source:, atau di entri locals: yang dibacanya, menghentikan proses pull. Entri yang tidak dibaca oleh field source: mana pun hanya dievaluasi oleh render, dengan set lengkap. Me-resolve koordinat menetapkan apa yang di-pin alih-alih menghasilkan artefak, itulah sebabnya set fungsinya sengaja dibuat lebih sempit — lihat errors/fatal-halts.md “Resolving a source: coordinate registers a narrower function set (Me-resolve koordinat mendaftarkan set fungsi yang lebih sempit)” untuk penghentian tersebut dan bentuk portabel yang dapat digunakan sebagai gantinya.
Set Sprig didaftarkan sendiri untuk interpolasi parameter, dan bersama helper milik Aggrega sendiri pada permukaan templat nilai milik renderer.
Apa yang terpasang
Sprig v3 menyediakan seluruh permukaan helper-nya — sekitar 200 fungsi dalam kategori di bawah ini. Halaman ini menguraikan kategori-kategori tersebut beserta helper yang umum di masing-masing kategori; referensi kanonis per fungsi adalah dokumentasi Sprig upstream.
- String —
upper,lower,title,trim,trimAll,trimPrefix,trimSuffix,replace,contains,hasPrefix,hasSuffix,substr,quote,squote,cat,indent,nindent,repeat, helper huruf besar-kecil (snakecase,camelcase,kebabcase), helper singkatan (abbrev,abbrevboth,trunc), helper checksum (sha1sum,sha256sum,sha512sum,adler32sum),toString. - List —
list,tuple,first,last,rest,initial,append/push,prepend,concat,reverse,uniq,without,has,slice,chunk,join,splitList,split,splitn,sortAlpha,compact. - Dict —
dict,get,set,unset,hasKey,keys,values,pick,omit,pluck,merge,mergeOverwrite,dig,deepCopy. - Matematika —
add,sub,mul,div,mod,add1,min,max,ceil,floor,round, ditambah varian desimal berakhiranf(addf,subf,mulf,divf,minf,maxf). - Konversi —
int,int64,float64,atoi,toString,toDecimal,seq,until,untilStep. - Encoding —
b64enc,b64dec,b32enc,b32dec,toJson,toPrettyJson,toRawJson,fromJson, ditambah varian JSON berawalanmustyang memunculkan galat dekode alih-alih diam-diam menghasilkan nilai nol. - Pemeriksaan tipe —
typeOf,typeIs,typeIsLike,kindOf,kindIs,deepEqual,empty. - Default dan alur —
default,coalesce,all,any,ternary,fail(memunculkan galat template dengan pesan khusus — cara kanonis untuk menghentikan render dengan pesan penjaga). - Regex —
regexMatch,regexFind,regexFindAll,regexReplaceAll,regexReplaceAllLiteral,regexSplit,regexQuoteMeta, ditambah varian ketat berawalanmust. - Path —
base,dir,clean,ext,isAbs(gaya Unix);osBase,osClean,osDir,osExt,osIsAbs(sadar OS). - SemVer —
semver,semverCompare. - URL —
urlParse,urlJoin. - Tanggal —
ago,date,dateInZone,dateModify,duration,durationRound,htmlDate,htmlDateInZone,now,toDate,unixEpoch.
Catatan tentang determinisme
Aggrega menjamin keluaran yang identik byte demi byte untuk masukan yang identik byte demi byte. Sebagian helper Sprig membaca keadaan lingkungan dan merusak jaminan tersebut ketika dipanggil dari templat. Penulis sebaiknya menghindari helper berikut pada permukaan templat yang berkontribusi pada artefak hasil render:
- Pembaca jam dinding —
now,date,dateInZone,dateModify,htmlDate,htmlDateInZone,agoketika dipanggil tanpa waktu acuan yang dibekukan. - Pembangkit acak —
randAlpha,randAlphaNum,randAscii,randNumeric,randBytes,randInt,uuidv4. - Pembaca lingkungan —
env,expandenv(membaca variabel lingkungan proses, yang berbeda antara workstation operator dan runner CI). - Resolver jaringan —
getHostByName.
Helper ini tidak diblokir oleh mesin; helper ini merupakan bagian dari set Sprig v3. Disiplin untuk menghindarinya dalam templat jalur render dijaga oleh peninjau dan oleh jaminan keluaran deterministik yang diandalkan oleh penulis dan katalog pustaka standar.
Angka dalam templat nilai
Angka yang ditulis penulis mencapai templat nilai sebagai angka. Bilangan bulat adalah integer dan dicetak utuh: 1000000 dicetak 1000000. Angka lainnya dicetak dalam bentuk desimal eksak terpendek, tidak pernah dalam bentuk eksponen: 0.0000001 yang ditulis penulis dicetak 0.0000001 dan 1e21 yang ditulis penulis dicetak 1000000000000000000000, baik templat menulis nilai itu secara langsung maupun mengubahnya menjadi teks dengan toString, quote, printf "%v" atau toJson. Angka yang dikembalikan fungsi matematika — mulf, float64, round dan sejenisnya — adalah nilai milik fungsi itu sendiri dan dicetak dalam bentuk fungsi itu sendiri, yaitu bentuk eksponen untuk nilai yang sangat kecil atau sangat besar: {{ mulf .values.ratio 1 }} mencetak 1e-07 untuk 0.0000001 yang ditulis penulis.
Perbandingan — eq, ne, lt, le, gt dan ge — membaca dua angka berdasarkan nilai, apa pun jenis yang membawa masing-masing, sehingga bilangan bulat yang ditulis penulis dapat dibandingkan dengan desimal yang ditulis dalam templat, dan 3 sama dengan 3.0:
{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → trueAngka tidak pernah dibandingkan dengan teks: salah satu dari keenam perbandingan yang diberi angka dan teks berkutip akan menghentikan build, dengan menyebutkan kedua jenisnya. Bandingkan angka itu dengan angka yang ditulis tanpa kutip, atau ubah terlebih dahulu menjadi teks:
{{ 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 → truePenghentiannya adalah A value template failed while it ran (Templat nilai gagal saat berjalan). Asersi membaca angka yang ditulis penulis dengan cara yang sama; lihat Angka pada permukaan ini.
Keberadaan dan kekosongan — dua pertanyaan yang berbeda
Templat mengajukan salah satu dari dua pertanyaan tentang suatu nilai, dan setiap pertanyaan memiliki helper-nya sendiri.
- Apakah penulis menuliskannya?
hasKeydanoptionalmenjawab berdasarkan keberadaan. Kunci yang ditulis penulis ada, apa pun isinya — termasuk0,""danfalse— dan hanya kunci yang dihilangkan penulis yang tidak ada. - Apakah nilainya kosong?
default,with,ifdanemptymenjawab berdasarkan kekosongan.0,"",false, daftar kosong, map kosong, dan nilai yang tidak ada semuanya dihitung sebagai kosong di sana, sama seperti di Helm.
.values.replicas | hasKey .values "replicas" | optional .values "replicas" 1 | .values.replicas | default 1 | if .values.replicas |
|---|---|---|---|---|
| tidak ada | false | 1 | 1 | false |
0 | true | 0 | 1 | false |
3 | true | 3 | 3 | true |
Nilai yang secara sah dapat berupa 0, "" atau false — jumlah replika nol, timeout nol, flag yang dimatikan — diuji dengan hasKey atau optional, sehingga 0 milik penulis mencapai output sebagai 0. default, with dan if cocok untuk nilai yang bentuk kosongnya tidak memiliki makna sendiri, ketika “kosong” dan “tidak ditulis” boleh diperlakukan sama. Bacalah suatu kunci dengan satu cara per templat: kunci yang juga dibaca templat sebagai path bertitik dihitung sebagai ada, sebagaimana dijelaskan batasan pada optional.
Helper khusus Aggrega
optional — fallback yang memperhatikan keberadaan kunci
optional <map> <key> <fallback> mengembalikan nilai pada <key> di <map> jika kunci tersebut ada, dan jika tidak, mengembalikan <fallback>. Berbeda dengan default milik Sprig, optional membedakan “kunci tidak ada” dari “kunci ada dengan nilai nol, kosong, atau false.”
Signature-nya menerima map dan kunci sebagai argumen terpisah karena nilai yang dialirkan melalui operator | milik Go template telah kehilangan akses ke map induknya. Tanpa map induk dalam cakupan, keberadaan kunci tidak dapat diperiksa.
Ada satu batasan pada pemeriksaan keberadaan, dan batasan ini berasal dari template, bukan dari helper: template nilai membaca kunci yang tidak ada sebagai kosong, yang dilakukannya dengan menyediakan nilai kosong pada setiap kunci tidak ada yang disebut template sebagai path bertitik dan dibaca sebagai nilai. Jadi, template yang membaca satu kunci baik melalui optional maupun sebagai path semacam itu akan mendapati kunci tersebut ada dan kosong, sehingga memperoleh nilai kosong, bukan fallback. Bacalah suatu kunci dengan satu cara per template, maka kedua jawaban akan sama.
# 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 → 0Kasus terakhir adalah pembeda yang tidak dapat dibuat oleh default milik Sprig. {{ .infra.replicas | default 1 }} mengembalikan 1 baik ketika replicas ditulis sebagai 0 maupun dihilangkan — pencampuradukan yang menghalangi pola sah seperti scale-to-zero, tanpa retry, tanpa timeout, dan flag bernilai false.
Konvensi pengutipan kunci: utamakan backtick. Go template menerima literal string berkutip ganda ("replicas") maupun berkutip backtick (`replicas`) untuk argumen kunci; keduanya menghasilkan string yang sama saat evaluasi template. Contoh dalam katalog dan dokumentasi secara seragam menggunakan bentuk backtick karena bentuk ini aman bagi YAML dalam setiap konteks pengutipan. Kunci berkutip ganda di dalam skalar YAML berkutip ganda akan mengakhiri string YAML di tengah 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 }}"Ketika template berada di dalam block-scalar YAML (bentuk |) atau sebagai skalar nilai polos, kedua bentuk dirender dengan benar. Ketika template disematkan di dalam skalar YAML berkutip ganda (pola nilai-field-sebagai-template field: "{{ ... }}"), backtick wajib digunakan. Konvensi tunggal (selalu backtick) sepenuhnya menghindari jebakan pengutipan YAML.
Kapan mengutamakan optional daripada default. Gunakan optional ketika field dapat secara sah bernilai nol, kosong, atau false dan penulis katalog perlu membedakan “penulis tidak mengatur ini” dari “penulis mengatur ini ke nilai falsy.” Gunakan default ketika pencampuradukan tersebut dapat diterima (misalnya, field string yang nilai kosongnya tidak valid; field numerik yang nilai nolnya tidak valid).
Ketersediaan per permukaan. optional didaftarkan pada setiap permukaan yang dievaluasi renderer: permukaan template nilai (Recipe valuesMapping, FeatureRecipe injectMapping, provides, pipeline.with, badan Workload), evaluator asersi, dan template path (directory: / subDirectory: pada batas Release). Yang berbeda pada permukaan template path bukanlah himpunan helper-nya, melainkan kebijakan kunci yang hilang: template path memperlakukan kunci yang tidak ada sebagai error, bukan sebagai kosong, karena segmen path yang diam-diam kosong menghasilkan tata letak sistem berkas yang rusak dan baru diketahui setelah build. optional membaca kunci tanpa kebijakan ketat itu terpicu lebih dahulu, dan itulah yang membuatnya dapat digunakan di sana.
capitalizedWords — melipat nama menjadi huruf dan angka
capitalizedWords <string> membaca argumennya sebagai kata-kata yang dipisahkan oleh deretan karakter apa pun di luar huruf dan angka ASCII, mengapitalkan huruf pertama setiap kata, lalu menggabungkannya. Setiap karakter hasilnya adalah huruf atau angka.
Helper ini ada karena sebagian target hanya menerima huruf dan angka dalam nama yang digunakan untuk mengalamati resource, sementara id komponen dapat secara sah memuat titik, tanda hubung, atau garis bawah. Menulis konversi itu secara manual di setiap Recipe yang membutuhkannya menghasilkan beberapa ejaan untuk satu gagasan; satu helper memberi setiap penulis jawaban yang sama.
# 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🔴 Hasilnya tidak mengidentifikasi nama asalnya. Setiap pemisah dibuang, sehingga dua id yang hanya berbeda pada letak pemisahnya menghasilkan hasil yang sama — payments-db dan payments_db sama-sama menghasilkan PaymentsDb. Helper tidak dapat mendeteksi hal itu, karena ia hanya melihat satu nama dalam satu waktu; menangkapnya adalah tugas pihak mana pun yang mengalamati resource berdasarkan hasil tersebut. Target yang melakukannya menolak tabrakan tersebut alih-alih menghasilkan deployment dengan salah satu dari keduanya hilang: saat build untuk CloudFormation, dua komponen yang id-nya terlipat menjadi satu nama akan menghentikan build, dan pesannya menyebutkan setiap id yang menghasilkan nama tersebut. Pilihlah id yang berbeda lebih dari sekadar tanda baca, maka masalah ini tidak akan muncul.
Ketersediaan per permukaan. capitalizedWords didaftarkan di mana pun optional didaftarkan: setiap permukaan yang dievaluasi renderer, serta resolusi koordinat source: terstruktur. Helper ini tidak tersedia dalam interpolasi parameter Aggregate, yang hanya menyediakan himpunan Sprig.
index — kunci yang wajib dimiliki map
index <collection> <key>... membaca koleksi berdasarkan posisi atau kunci, seperti index bawaan Go — dengan satu perbedaan. Ketika koleksinya berupa map dan map tersebut tidak memiliki kunci itu, index menghentikan build dan menyebutkan kuncinya, sedangkan versi Go menjawab dengan nilai kosong yang tercetak sebagai teks literal <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")Inilah cara baca yang digunakan ketika kunci harus ada — kredensial yang dibaca dengan nama variabel yang dihitung Recipe, kunci yang dipublikasikan template lain — sehingga kunci yang hilang menghentikan build alih-alih sampai ke artefak sebagai <no value>. Ketika kunci dapat secara sah tidak ada, ujilah terlebih dahulu: {{ optional .values `replicas` 1 }} menyediakan fallback, get milik Sprig mengembalikan string kosong, dan hasKey menguji tanpa membaca. Membaca melalui index lalu menerapkan default tidak menyediakan fallback, karena penghentian terjadi sebelum default dijalankan. Kunci yang ada dan bernilai null tidak dianggap tidak ada: index mengembalikannya, dan nilainya tercetak sebagai <no value>.
Penghentian ini adalah sifat index semata, dan sama di setiap permukaan — template nilai, evaluator asersi, template path, koordinat source: terstruktur, interpolasi parameter Aggregate, predikat validate: milik parameter, serta predikat x-aggrega-when: / x-aggrega-validate: milik skema. Pembacaan bertitik atas kunci yang tidak diatur mengikuti kebijakan kunci hilang milik permukaannya sendiri dan tidak terpengaruh. Penghentian ini didokumentasikan di errors/fatal-halts.md “A template indexes a map with a key the map does not hold (Template mengindeks map dengan kunci yang tidak dimiliki map tersebut)”.
Helper umum yang TIDAK tersedia
Helm memperluas text/template milik Go dengan helper chart-template yang sering dikira sebagai helper Sprig umum. Tidak satu pun dari helper ini terdaftar di renderer Aggrega. Template yang dievaluasi oleh renderer Aggrega (Recipe valuesMapping:, FeatureRecipe injectMapping:, provides, isi Workload, evaluator asersi) tidak dapat memanggilnya:
include— bentuk yang disukai Helm untuk memanggil fragmen template yang telah didefinisikan dengan keluaran string yang dapat di-pipe. Renderer Aggrega tidak mendaftarkannya. Gunakan{{ template "name" . }}dari template Go standar sebagai gantinya (bentuk yang hanya menghasilkan efek samping); untuk keluaran yang dapat di-pipe, lakukan komposisi menggunakan fragmen MappingLibrary dan direktif$import:.tpl— mengevaluasi ulang sebuah string sebagai template bersarang terhadap konteks saat ini. Aggrega tidak mendaftarkannya; evaluasi ulang bersarang bukan bagian dari permukaan template. Penulis yang memerlukan nilai terhitung sebaiknya menyusunnya dengan helper string Sprig dan langsung mengeluarkan nilai akhirnya.required— menggagalkan render chart dengan pesan kustom ketika nilai yang disebut tidak ada. Aggrega tidak mendaftarkannya. Penegakan bidang wajib di Aggrega berada pada lapisan kontrak parameter bertipe (slotparameters:Aggregate denganrequired: trueyang dibiarkan tidak terisi oleh Release menghentikan build denganE0165, dengan menyebutkan slot tersebut dan tempat Aggregate mendeklarasikannya); pemeriksaan penanda wajib per template menggunakanfaildari Sprig untuk memunculkan galat template fatal yang membawa string yang diberikan.warn— mengeluarkan catatan non-fatal ke terminal operator. Aggrega tidak mendaftarkannya. Template yang perlu menghentikan render dengan pesan penjelasan sebaiknya menggunakanfaildari Sprig; template yang perlu beralih ke nilai cadangan tanpa berhenti sebaiknya mengandalkan cabangif/elseGo standar.
Inventaris helper lintas mesin (penting bagi penulis MappingLibrary)
Fragmen MappingLibrary dapat menargetkan salah satu dari dua tempat konsumsi:
- Konsumsi sisi Aggrega (Recipe
valuesMapping:, FeatureRecipeinjectMapping:, dll., dievaluasi oleh renderer Aggrega). Helper yang tersedia adalah: Sprig v3 lengkap (default,coalesce,quote,nindent,indent,b64enc, dll.) ditambah helper milik Aggrega sendiri (optional,capitalizedWords), danindexberhenti pada kunci map yang tidak dimiliki map tersebut. Helper chart-template (include,tpl,required,warn) TIDAK tersedia. - Konsumsi internal chart Helm (konten
values.yamlchart atautemplates/*.yamlchart yang dirender di hilir oleh mesin template milik Helm sendiri). Helper yang tersedia adalah: Sprig v3 lengkap ditambah helper chart-template Helm (include,tpl,required,warn). Helper milik Aggrega sendiri TIDAK tersedia, danindexdi sana adalah milik Go sendiri, yang menjawab kunci yang tidak ada dengan nilai kosong alih-alih berhenti.
Kedua set helper berbagi permukaan Sprig tetapi berbeda pada ekstensi khusus mesin. Entri MappingLibrary yang menargetkan konsumsi internal chart Helm menggunakan konvensi Helm (root .Values.<key> dengan V kapital, | default, komposisi berbasis include); entri yang menargetkan konsumsi sisi Aggrega menggunakan konvensi Aggrega (.values.<key> huruf kecil, optional untuk nilai cadangan yang sadar keberadaan). Entitas library menyimpan fragmen apa adanya; bentuk penulisannya mengikuti tempat fragmen tersebut dimaksudkan untuk dirender.
Helper kustom Aggrega di atas Sprig adalah optional dan capitalizedWords, keduanya didokumentasikan di atas, dan index miliknya menggantikan milik Go, sebagaimana didokumentasikan di atas. Sisa permukaan helper persis sama dengan set Sprig v3.
Rujukan silang
template-context-contract.md— bidang runtime yang dibaca templat bersama helper Sprig.expansion-matrix.md— urutan evaluasi per situs templat.05-templates.md— ikhtisar templating dan konvensi penulisan.- Dokumentasi Sprig v3 — referensi kanonis per fungsi.