Sprig fonksiyonları ve yardımcıları
Aggrega şablon motoru, Sprig v3 fonksiyon kütüphanesini ve Aggrega’nın kendi yardımcılarını (optional ve capitalizedWords) oluşturucunun değerlendirdiği her Go şablonuna bağlar ve Go’nun index fonksiyonunu, haritanın içermediği bir harita anahtarında duran bir sürümle değiştirir. Recipe valuesMapping:, FeatureRecipe injectMapping: ya da oluşturucunun değerlendirdiği başka herhangi bir şablon yüzeyini yazan yazarlar, Go text/template yerleşiklerinin ve template-context-contract.md içinde belgelenen çalışma zamanı bağlam alanlarının yanında Sprig yardımcı setinin tamamını kullanabilir.
🔴 “Oluşturucunun değerlendirdiği” ifadesini bir kapsam olarak okuyun, çünkü bir yazım yüzeyi bu kapsamın dışında kalır. Yapılandırılmış bir source: koordinatı, adlandırdığı yapıtın sabitlenebilmesi için çözümlenir ve bu çözümleme bir oluşturma geçişi değildir: yalnızca Aggrega’nın kendi yardımcılarını kaydeder; dolayısıyla bir source: alanındaki ya da bu alanın okuduğu bir locals: girdisindeki Sprig çağrısı çekme işlemini durdurur. Hiçbir source: alanının okumadığı bir girdi yalnızca oluşturma tarafından, tam setle değerlendirilir. Bir koordinatı çözümlemek bir yapıt üretmez, neyin sabitleneceğini belirler; bu yüzden fonksiyon seti bilerek daha dardır — duruş ve onun yerine kullanılacak taşınabilir biçim için errors/fatal-halts.md içindeki “Resolving a source: coordinate registers a narrower function set” (Bir koordinatı çözümlemek daha dar bir fonksiyon seti kaydeder) bölümüne bakın.
Sprig seti, parametre enterpolasyonu için tek başına, oluşturucunun değer şablonu yüzeylerinde ise Aggrega’nın kendi yardımcılarıyla birlikte kaydedilir.
Neler bağlanmıştır
Sprig v3, yardımcılarının tamamını sunar: aşağıdaki kategorilere dağılmış yaklaşık 200 fonksiyon. Bu sayfa kategorileri, her birindeki yaygın yardımcılarla birlikte ana hatlarıyla verir; fonksiyon bazında esas başvuru kaynağı, Sprig’in kendi belgeleridir.
- Dizgeler —
upper,lower,title,trim,trimAll,trimPrefix,trimSuffix,replace,contains,hasPrefix,hasSuffix,substr,quote,squote,cat,indent,nindent,repeat, büyük/küçük harf yardımcıları (snakecase,camelcase,kebabcase), kısaltma yardımcıları (abbrev,abbrevboth,trunc), sağlama toplamı yardımcıları (sha1sum,sha256sum,sha512sum,adler32sum),toString. - Listeler —
list,tuple,first,last,rest,initial,append/push,prepend,concat,reverse,uniq,without,has,slice,chunk,join,splitList,split,splitn,sortAlpha,compact. - Sözlükler —
dict,get,set,unset,hasKey,keys,values,pick,omit,pluck,merge,mergeOverwrite,dig,deepCopy. - Matematik —
add,sub,mul,div,mod,add1,min,max,ceil,floor,roundve ayrıcafsonekli ondalık türevleri (addf,subf,mulf,divf,minf,maxf). - Dönüştürme —
int,int64,float64,atoi,toString,toDecimal,seq,until,untilStep. - Kodlama —
b64enc,b64dec,b32enc,b32dec,toJson,toPrettyJson,toRawJson,fromJsonve ayrıca kod çözme hatalarını sessizce sıfır değere düşürmek yerine görünür kılanmustönekli JSON türevleri. - Tür denetimleri —
typeOf,typeIs,typeIsLike,kindOf,kindIs,deepEqual,empty. - Varsayılanlar ve akış —
default,coalesce,all,any,ternary,fail(özel bir iletiyle şablon hatası oluşturur; bir işlemeyi koruma iletisiyle durdurmanın esas yolu budur). - Düzenli ifadeler —
regexMatch,regexFind,regexFindAll,regexReplaceAll,regexReplaceAllLiteral,regexSplit,regexQuoteMetave ayrıcamustönekli katı türevleri. - Yollar —
base,dir,clean,ext,isAbs(Unix tarzı);osBase,osClean,osDir,osExt,osIsAbs(işletim sistemine duyarlı). - SemVer —
semver,semverCompare. - URL —
urlParse,urlJoin. - Tarihler —
ago,date,dateInZone,dateModify,duration,durationRound,htmlDate,htmlDateInZone,now,toDate,unixEpoch.
Determinizm uyarısı
Aggrega, bayt bayt aynı girdi için bayt bayt aynı çıktıyı garanti eder. Sprig yardımcılarının bir alt kümesi ortam durumunu okur ve bir şablondan çağrıldığında bu garantiyi bozar. Yazarlar, oluşturulan yapıtlara katkıda bulunan şablon yüzeylerinde aşağıdaki yardımcılardan kaçınmalıdır:
- Duvar saati okuyucuları —
now,date,dateInZone,dateModify,htmlDate,htmlDateInZone, sabitlenmiş bir referans zamanı olmadan çağrıldığındaago. - Rastgele üreteçler —
randAlpha,randAlphaNum,randAscii,randNumeric,randBytes,randInt,uuidv4. - Ortam okuyucuları —
env,expandenv(operatör iş istasyonları ile CI çalıştırıcıları arasında farklılık gösteren süreç ortam değişkenlerini okur). - Ağ çözümleyicileri —
getHostByName.
Bu yardımcılar motor tarafından engellenmez; Sprig v3 setinin parçasıdırlar. Oluşturma yolundaki şablonlarda bunlardan kaçınma disiplini, gözden geçirenler ve yazarlar ile standart kütüphane kataloğunun dayandığı deterministik çıktı garantisi tarafından sürdürülür.
Bir değer şablonundaki sayılar
Bir yazarın yazdığı sayı, bir değer şablonuna sayı olarak ulaşır. Tam sayı bir integer’dır ve tam olarak yazdırılır: 1000000, 1000000 olarak yazdırılır. Diğer her sayı en kısa kesin ondalık biçiminde yazdırılır, asla üstel biçimde değil: yazılmış bir 0.0000001, 0.0000001 olarak ve yazılmış bir 1e21, 1000000000000000000000 olarak yazdırılır; şablon değeri doğrudan yazsa da onu toString, quote, printf "%v" ya da toJson ile metne dönüştürse de bu böyledir. Bir matematik fonksiyonunun döndürdüğü sayı — mulf, float64, round ve benzerleri — o fonksiyonun kendi değeridir ve o fonksiyonun kendi biçiminde yazdırılır; bu, çok küçük ya da çok büyük bir değer için üstel biçimdir: yazılmış bir 0.0000001 için {{ mulf .values.ratio 1 }}, 1e-07 yazdırır.
Karşılaştırmalar — eq, ne, lt, le, gt ve ge — her birini hangi tür taşırsa taşısın iki sayıyı değerlerine göre okur; bu yüzden yazılmış bir tam sayı şablonda yazılmış bir ondalık sayıyla karşılaştırılabilir ve 3, 3.0 değerine eşittir:
{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → trueBir sayı asla bir metin parçasıyla karşılaştırılmaz: altı karşılaştırmadan herhangi biri bir sayı ve tırnak içindeki bir metin aldığında, iki türü de belirterek derlemeyi durdurur. Sayıyı tırnaksız yazılmış bir sayıyla karşılaştırın ya da önce metne dönüştürün:
{{ 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 → trueBu durdurma A value template failed while it ran (Bir değer şablonu çalışırken başarısız oldu) durdurmasıdır. Bir doğrulama, yazılmış bir sayıyı aynı şekilde okur; bkz. Bu yüzeydeki sayılar.
Varlık ve boşluk — iki farklı soru
Bir şablon bir değer hakkında iki sorudan birini sorar ve her sorunun kendi yardımcıları vardır.
- Yazar onu yazdı mı?
hasKeyveoptionalvarlığa göre yanıt verir. Yazarın yazdığı bir anahtar, ne tutarsa tutsun —0,""vefalsedahil — mevcuttur; yalnızca yazarın atladığı bir anahtar yoktur. - Boş mu?
default,with,ifveemptyboşluğa göre yanıt verir. Orada0,"",false, boş bir liste, boş bir eşlem ve bulunmayan bir değer, Helm’de olduğu gibi, boş sayılır.
.values.replicas | hasKey .values "replicas" | optional .values "replicas" 1 | .values.replicas | default 1 | if .values.replicas |
|---|---|---|---|---|
| yok | false | 1 | 1 | false |
0 | true | 0 | 1 | false |
3 | true | 3 | 3 | true |
Meşru olarak 0, "" ya da false olabilecek bir değer — sıfır kopya sayısı, sıfır zaman aşımı, kapatılmış bir bayrak — hasKey ya da optional ile sınanır; böylece yazarın 0 değeri çıktıya 0 olarak ulaşır. default, with ve if, boş biçimi kendine özgü bir anlam taşımayan ve “boş” ile “yazılmamış” durumlarının aynı şekilde ele alınabileceği bir değere uygundur. Belirli bir anahtarı şablon başına tek bir yolla okuyun: şablonun noktalı yol olarak da okuduğu bir anahtar, optional üzerindeki sınırın açıkladığı gibi, mevcut sayılır.
Aggrega’ya özgü yardımcılar
optional — varlığı dikkate alan geri dönüş değeri
optional <map> <key> <fallback>, anahtar mevcutsa <map> içindeki <key> konumundaki değeri, aksi halde <fallback> değerini döndürür. Sprig’in default yardımcısından farklı olarak optional, “anahtar yok” durumunu “anahtar var ve değeri sıfır, boş ya da false” durumundan ayırt eder.
İmza, eşlemi ve anahtarı ayrı argümanlar olarak alır, çünkü Go template’in | operatörüyle aktarılan bir değer üst eşlemine erişimini yitirmiştir. Üst eşlem kapsamda olmadan varlık denetlenemez.
Varlık denetiminin bir sınırı vardır ve bu sınır yardımcıdan değil şablondan gelir: bir değer şablonu, olmayan bir anahtarı hiçbir şey olarak okur ve bunu, şablonun noktalı yol olarak adlandırıp değer olarak okuduğu her olmayan anahtara boş bir değer sağlayarak yapar. Dolayısıyla bir anahtarı hem optional aracılığıyla hem de böyle bir yol olarak okuyan bir şablon, o anahtarı mevcut ve boş bulur ve geri dönüş değeri yerine boş değeri alır. Bir anahtarı her şablonda tek bir yolla okuyun; böylece iki yanıt örtüşür.
# 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 → 0Son durum, Sprig’in default yardımcısının yapamadığı ayrımdır. {{ .infra.replicas | default 1 }}, replicas ister 0 olarak yazılmış ister atlanmış olsun 1 döndürür — bu karıştırma, meşru sıfıra ölçekleme, yeniden denemesiz, zaman aşımısız ve false bayrak kalıplarını engeller.
Anahtar tırnaklama uzlaşımı: ters tırnağı tercih edin. Go şablonları, anahtar argümanı için hem çift tırnaklı ("replicas") hem de ters tırnaklı (`replicas`) dize sabitlerini kabul eder; ikisi de şablon değerlendirme zamanında aynı dizeyi üretir. Katalog ve dokümantasyon örnekleri tutarlı olarak ters tırnak biçimini kullanır, çünkü bu biçim her tırnaklama bağlamında YAML açısından güvenlidir. Çift tırnaklı bir YAML skalerinin içindeki çift tırnaklı bir anahtar, YAML dizesini şablonun ortasında sonlandırır:
# 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 }}"Şablon bir YAML blok skalerinin (| biçimi) içinde ya da yalın değerli bir skaler olarak yer aldığında her iki biçim de doğru işlenir. Şablon çift tırnaklı bir YAML skalerinin içine gömüldüğünde (field: "{{ ... }}" biçimindeki, alan değerinin şablon olduğu kalıp) ters tırnak gereklidir. Tek bir uzlaşım (her zaman ters tırnak), YAML tırnaklama tuzağından tümüyle kaçınır.
optional ne zaman default yerine tercih edilmeli. Alan meşru olarak sıfır, boş ya da false olabiliyorsa ve katalog yazarının “yazar bunu ayarlamadı” durumunu “yazar bunu yanlış değerli (falsy) bir değere ayarladı” durumundan ayırması gerekiyorsa optional kullanın. Karıştırma kabul edilebilir olduğunda (ör. boş değerin geçersiz olduğu dize alanları; sıfırın geçersiz olduğu sayısal alanlar) default kullanın.
Yüzeye göre kullanılabilirlik. optional, işleyicinin değerlendirdiği her yüzeyde kayıtlıdır: değer şablonu yüzeyleri (Recipe valuesMapping, FeatureRecipe injectMapping, provides, pipeline.with, Workload gövdesi), doğrulama değerlendiricisi ve yol şablonları (Release sınırlarında directory: / subDirectory:). Yol şablonu yüzeyinde farklı olan, yardımcı kümesi değil eksik anahtar politikasıdır: bir yol şablonu, olmayan bir anahtarı boş olarak değil hata olarak ele alır, çünkü sessizce boş kalan bir yol parçası ancak derlemeden sonra fark edilen bozuk bir dosya sistemi düzeni üretir. optional, bir anahtarı bu katı politika önce devreye girmeden okur; onu orada kullanılabilir kılan da budur.
capitalizedWords — bir adı harf ve rakamlara indirgeme
capitalizedWords <string>, argümanını ASCII harfleri ve rakamları dışındaki herhangi bir karakter dizisiyle ayrılmış sözcükler olarak okur, her sözcüğün ilk harfini büyük harfe çevirir ve sözcükleri birleştirir. Sonucun her karakteri bir harf ya da rakamdır.
Bu yardımcı, bazı hedeflerin kaynakları adreslerken kullandıkları adlarda yalnızca harf ve rakam kabul etmesi, bir component kimliğinin ise meşru olarak nokta, kısa çizgi ya da alt çizgi içerebilmesi nedeniyle vardır. Bu dönüşümü ihtiyaç duyan her Recipe’te elle yazmak, tek bir fikrin birkaç farklı yazımını üretir; tek bir yardımcı her yazara aynı yanıtı verir.
# 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🔴 Sonuç, geldiği adı tanımlamaz. Her ayırıcı atılır; bu nedenle yalnızca ayırıcılarının yeri farklı olan iki kimlik aynı sonuca ulaşır — payments-db ve payments_db ikisi de PaymentsDb verir. Yardımcı bunu algılayamaz, çünkü her seferinde tek bir ad görür; bunu yakalamak, kaynakları sonuca göre adresleyen bileşenin işidir. Bunu yapan bir hedef, iki kaynaktan biri eksik bir dağıtım üretmek yerine çakışmayı reddeder: CloudFormation için derlerken kimlikleri tek bir ada indirgenen iki component derlemeyi durdurur ve ileti o ada ulaşan her kimliği adlandırır. Noktalama işaretlerinden fazlasıyla farklılaşan kimlikler seçin; bu sorun hiç ortaya çıkmaz.
Yüzeye göre kullanılabilirlik. capitalizedWords, optional neredeyse orada kayıtlıdır: işleyicinin değerlendirdiği her yüzeyde ve yapılandırılmış bir source: koordinatının çözümlenmesinde. Yalnızca Sprig kümesini sunan Aggregate parametre enterpolasyonunda kullanılamaz.
index — eşlemin içermesi gereken bir anahtar
index <collection> <key>..., bir koleksiyonu Go’nun kendi index işlevi gibi konuma ya da anahtara göre okur — tek bir farkla. Koleksiyon bir eşlem olduğunda ve eşlem anahtarı içermediğinde index derlemeyi durdurur ve anahtarı adlandırır; Go’nunki ise <no value> sabit metni olarak yazdırılan boş bir değerle yanıt verir.
# 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")Anahtarın mutlaka bulunması gereken yerde kullanılacak okuma budur — Recipe’in hesapladığı değişken adı altında okunan bir kimlik bilgisi, başka bir şablonun yayımladığı bir anahtar —; böylece eksik bir anahtar bir artefakta <no value> olarak ulaşmak yerine derlemeyi durdurur. Anahtarın meşru olarak bulunmayabileceği yerde önce onu sınayın: {{ optional .values `replicas` 1 }} bir geri dönüş değeri sağlar, Sprig’in get yardımcısı boş bir dize döndürür ve hasKey okumadan sınar. index ile okuyup ardından default uygulamak bir geri dönüş değeri sağlamaz, çünkü durdurma default çalışmadan önce gerçekleşir. Mevcut olup null tutan bir anahtar olmayan anahtar değildir: index onu döndürür ve o <no value> olarak yazdırılır.
Durdurma yalnızca index’in bir özelliğidir ve her yüzeyde aynıdır — değer şablonları, doğrulama değerlendiricisi, yol şablonları, yapılandırılmış bir source: koordinatı, Aggregate parametre enterpolasyonu, bir parametrenin validate: yüklemi ve bir şemanın x-aggrega-when: / x-aggrega-validate: yüklemleri. Ayarlanmamış bir anahtarın nokta ile okunması, kendi yüzeyinin eksik anahtar politikasını izler ve bundan etkilenmez. Durdurma, errors/fatal-halts.md içinde “A template indexes a map with a key the map does not hold (Bir şablon, eşlemin içermediği bir anahtarla eşlemi dizinliyor)” başlığında belgelenmiştir.
Kullanılamayan yaygın yardımcılar
Helm, Go’nun text/template paketini, genellikle genel Sprig yardımcılarıyla karıştırılan chart şablonu yardımcılarıyla genişletir. Bunların hiçbiri Aggrega’nın işleyicisinde kayıtlı değildir. Aggrega işleyicisinin değerlendirdiği şablonlar (Recipe valuesMapping:, FeatureRecipe injectMapping:, provides, Workload gövdesi, doğrulama değerlendiricisi) bunları çağıramaz:
include— Helm’in, tanımlı bir şablon parçasını boru hattına aktarılabilir bir dize çıktısıyla çağırmak için tercih ettiği biçim. Aggrega’nın işleyicisi bunu kaydetmez. Bunun yerine standart Go şablonunun{{ template "name" . }}biçimini (yalnızca yan etki üreten biçim) kullanın; boru hattına aktarılabilir çıktı için MappingLibrary parçaları ve$import:yönergeleriyle birleştirme yapın.tpl— bir dizeyi geçerli bağlama karşı iç içe bir şablon olarak yeniden değerlendirir. Aggrega bunu kaydetmez; iç içe yeniden değerlendirme şablon yüzeyinin bir parçası değildir. Hesaplanmış değerlere ihtiyaç duyan yazarlar bunları Sprig’in dize yardımcılarıyla oluşturmalı ve nihai değeri doğrudan üretmelidir.required— adlandırılan değer eksik olduğunda chart işlemesini özel bir iletiyle başarısız kılar. Aggrega bunu kaydetmez. Aggrega’nın zorunlu alan denetimi tipli parametre sözleşmesi katmanında yer alır (required: trueiçeren ve Release’in doldurmadan bıraktığı bir Aggregateparameters:yuvası, yuvayı ve Aggregate’in onu nerede bildirdiğini belirterek derlemeyiE0165ile durdurur); şablon başına zorunluluk işaretçisi denetimleri, verilen dizeyi taşıyan ölümcül bir şablon hatası oluşturmak için Sprig’infailişlevini kullanır.warn— operatörün terminaline ölümcül olmayan bir not yazar. Aggrega bunu kaydetmez. İşlemeyi açıklayıcı bir iletiyle durdurması gereken şablonlar Sprig’infailişlevini kullanmalıdır; durdurmadan geri dönüş değerine başvurması gereken şablonlar standart Goif/elsedallarına dayanmalıdır.
Motorlar arası yardımcı envanteri (MappingLibrary yazarları için temel öneme sahip)
MappingLibrary parçaları iki tüketim noktasından birini hedefleyebilir:
- Aggrega tarafında tüketim (Recipe
valuesMapping:, FeatureRecipeinjectMapping:vb., Aggrega’nın işleyicisi tarafından değerlendirilir). Kullanılabilir yardımcılar şunlardır: Sprig v3’ün tamamı (default,coalesce,quote,nindent,indent,b64encvb.) artı Aggrega’nın kendi yardımcıları (optional,capitalizedWords); ayrıcaindex, haritanın tutmadığı bir harita anahtarında durur. Chart şablonu yardımcıları (include,tpl,required,warn) kullanılamaz. - Helm chart içi tüketim (chart
values.yamliçeriği veya Helm’in kendi şablon motoru tarafından sonradan işlenen charttemplates/*.yamldosyaları). Kullanılabilir yardımcılar şunlardır: Sprig v3’ün tamamı artı Helm’in chart şablonu yardımcıları (include,tpl,required,warn). Aggrega’nın kendi yardımcıları kullanılamaz ve oradakiindexGo’nun kendisidir; eksik bir anahtara durmak yerine boş bir değerle yanıt verir.
İki yardımcı kümesi Sprig yüzeyini paylaşır ancak motora özgü uzantılarda ayrışır. Helm chart içi tüketimi hedefleyen MappingLibrary girdileri Helm uzlaşımlarını kullanır (büyük V’li .Values.<key> kökü, | default, include tabanlı birleştirme); Aggrega tarafında tüketimi hedefleyen girdiler Aggrega uzlaşımlarını kullanır (küçük harfli .values.<key>, varlığa duyarlı geri dönüş için optional). Kütüphane varlığı parçaları olduğu gibi saklar; yazım biçimi, parçanın nerede işlenmesinin amaçlandığına göre belirlenir.
Aggrega’nın Sprig üzerindeki özel yardımcıları, ikisi de yukarıda belgelenen optional ve capitalizedWords’tür; ayrıca yukarıda belgelendiği gibi index Go’nunkinin yerini alır. Yardımcı yüzeyinin geri kalanı tam olarak Sprig v3 setidir.
Çapraz başvurular
template-context-contract.md— şablonların Sprig yardımcılarıyla birlikte okuduğu çalışma zamanı alanları.expansion-matrix.md— şablon konumu başına değerlendirme sırası.05-templates.md— şablonlamaya genel bakış ve yazım uzlaşımları.- Sprig v3 belgeleri — işlev başına standart başvuru kaynağı.