Функції та допоміжні функції Sprig
Рушій шаблонів Aggrega підключає бібліотеку функцій Sprig v3, а також власні допоміжні функції Aggrega (optional і capitalizedWords) до кожного шаблону Go, який обчислює рендерер, і замінює index з Go на версію, що зупиняє роботу на ключі, якого немає в мапі. Автори, які пишуть valuesMapping: у сутності Recipe, injectMapping: у сутності FeatureRecipe або будь-яку іншу поверхню шаблонів, яку обчислює рендерер, мають у своєму розпорядженні повний набір допоміжних функцій Sprig разом із вбудованими функціями Go text/template і полями контексту виконання, описаними в template-context-contract.md.
🔴 Розумійте «яку обчислює рендерер» як точну межу, бо одна поверхня написання лежить поза нею. Структуровану координату source: розв’язують, щоб закріпити артефакт, який вона називає, і це розв’язання не є проходом рендерингу: воно реєструє лише власні допоміжні функції Aggrega і нічого більше, тож виклик Sprig у полі source: або в записі locals:, який це поле читає, зупиняє отримання. Запис, який не читає жодне поле source:, обчислюється лише рендерингом, з повним набором. Розв’язання координати визначає, що буде закріплено, а не створює артефакт, тому його набір функцій навмисно вужчий — див. errors/fatal-halts.md «Resolving a source: coordinate registers a narrower function set (Розв’язання координати реєструє вужчий набір функцій)», де описано зупинку та переносну форму, яку слід використовувати натомість.
Набір Sprig реєструється окремо для інтерполяції параметрів, а на поверхнях шаблонів значень рендерера — разом із власними допоміжними функціями Aggrega.
Що підключено
Sprig v3 надає повний набір своїх допоміжних функцій — приблизно 200 функцій у категоріях, наведених нижче. Ця сторінка коротко описує категорії та поширені функції в кожній із них; канонічним довідником окремих функцій є документація Sprig.
- Рядки —
upper,lower,title,trim,trimAll,trimPrefix,trimSuffix,replace,contains,hasPrefix,hasSuffix,substr,quote,squote,cat,indent,nindent,repeat, функції регістру (snakecase,camelcase,kebabcase), функції скорочення (abbrev,abbrevboth,trunc), функції контрольних сум (sha1sum,sha256sum,sha512sum,adler32sum),toString. - Списки —
list,tuple,first,last,rest,initial,append/push,prepend,concat,reverse,uniq,without,has,slice,chunk,join,splitList,split,splitn,sortAlpha,compact. - Словники —
dict,get,set,unset,hasKey,keys,values,pick,omit,pluck,merge,mergeOverwrite,dig,deepCopy. - Математика —
add,sub,mul,div,mod,add1,min,max,ceil,floor,round, а також десяткові варіанти із суфіксомf(addf,subf,mulf,divf,minf,maxf). - Перетворення —
int,int64,float64,atoi,toString,toDecimal,seq,until,untilStep. - Кодування —
b64enc,b64dec,b32enc,b32dec,toJson,toPrettyJson,toRawJson,fromJson, а також варіанти JSON із префіксомmust, які повідомляють про помилки декодування замість тихого обнулення. - Перевірки типів —
typeOf,typeIs,typeIsLike,kindOf,kindIs,deepEqual,empty. - Типові значення та керування потоком —
default,coalesce,all,any,ternary,fail(викликає помилку шаблону з власним повідомленням — канонічний спосіб перервати рендеринг із захисним повідомленням). - Регулярні вирази —
regexMatch,regexFind,regexFindAll,regexReplaceAll,regexReplaceAllLiteral,regexSplit,regexQuoteMeta, а також суворі варіанти з префіксомmust. - Шляхи —
base,dir,clean,ext,isAbs(у стилі Unix);osBase,osClean,osDir,osExt,osIsAbs(з урахуванням ОС). - SemVer —
semver,semverCompare. - URL —
urlParse,urlJoin. - Дати —
ago,date,dateInZone,dateModify,duration,durationRound,htmlDate,htmlDateInZone,now,toDate,unixEpoch.
Застереження щодо детермінованості
Aggrega гарантує побайтово ідентичний вихід для побайтово ідентичного входу. Частина допоміжних функцій Sprig зчитує зовнішній стан і порушує цю гарантію, коли їх викликають із шаблону. Авторам слід уникати таких функцій у шаблонах, що впливають на згенеровані артефакти:
- Читачі системного годинника —
now,date,dateInZone,dateModify,htmlDate,htmlDateInZone,ago, якщо їх викликано без зафіксованого опорного часу. - Генератори випадкових значень —
randAlpha,randAlphaNum,randAscii,randNumeric,randBytes,randInt,uuidv4. - Читачі середовища —
env,expandenv(зчитують змінні середовища процесу, які відрізняються на робочих станціях операторів і на CI-раннерах). - Мережеві резолвери —
getHostByName.
Рушій не блокує ці функції: вони входять до набору Sprig v3. Дисципліну уникати їх у шаблонах шляху рендерингу підтримують рецензенти та гарантія детермінованого виходу, на яку покладаються автори й каталог стандартної бібліотеки.
Числа в шаблоні значень
Число, яке записує автор, доходить до шаблону значень як число. Ціле число є integer і виводиться цілим: 1000000 виводиться як 1000000. Будь-яке інше число виводиться в найкоротшій точній десятковій формі, ніколи в експоненційній: записане 0.0000001 виводиться як 0.0000001, а записане 1e21 — як 1000000000000000000000, незалежно від того, чи шаблон пише значення безпосередньо, чи перетворює його на текст за допомогою toString, quote, printf "%v" або toJson. Число, яке повертає математична функція, — mulf, float64, round і подібні до них, — є власним значенням цієї функції й виводиться в її власній формі, яка для дуже малого чи дуже великого значення є експоненційною: для записаного 0.0000001 вираз {{ mulf .values.ratio 1 }} виводить 1e-07.
Порівняння — eq, ne, lt, le, gt і ge — читають два числа за значенням, хоч би яким видом було подано кожне, тож записане автором ціле число порівнюється з десятковим, записаним у шаблоні, і 3 дорівнює 3.0:
{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → trueЧисло ніколи не порівнюється з текстом: будь-яке з шести порівнянь, отримавши число й текст у лапках, зупиняє збирання й називає обидва види. Порівнюйте число з числом, записаним без лапок, або спершу перетворіть його на текст:
{{ 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 → trueЦя зупинка — A value template failed while it ran (Шаблон значень зазнав збою під час виконання). Твердження читає записане автором число так само; див. Числа на цій поверхні.
Наявність і порожність — два різні запитання
Шаблон ставить щодо значення одне з двох запитань, і кожне запитання має власні допоміжні функції.
- Чи записав це автор?
hasKeyіoptionalвідповідають за наявністю. Ключ, записаний автором, присутній, хоч би що він містив, — зокрема0,""іfalse, — а відсутній лише ключ, який автор пропустив. - Чи це порожнє?
default,with,ifіemptyвідповідають за порожністю.0,"",false, порожній список, порожня мапа й відсутнє значення там вважаються порожніми, як і в Helm.
.values.replicas | hasKey .values "replicas" | optional .values "replicas" 1 | .values.replicas | default 1 | if .values.replicas |
|---|---|---|---|---|
| відсутнє | false | 1 | 1 | false |
0 | true | 0 | 1 | false |
3 | true | 3 | 3 | true |
Значення, яке може законно бути 0, "" або false, — нульова кількість реплік, нульовий тайм-аут, вимкнений прапорець, — перевіряється через hasKey або optional, щоб 0 автора дійшов до виводу як 0. default, with і if підходять для значення, порожня форма якого сама по собі нічого не означає, де «порожнє» і «не записане» можна вважати однаковими. Читайте кожен ключ у шаблоні одним способом: ключ, який шаблон також читає як шлях через крапку, вважається присутнім, як описано в розділі про обмеження optional.
Допоміжні функції, специфічні для Aggrega
optional — запасне значення з урахуванням наявності ключа
optional <map> <key> <fallback> повертає значення за <key> у <map>, якщо ключ наявний, інакше повертає <fallback>. На відміну від default у Sprig, optional розрізняє «ключ відсутній» і «ключ наявний з нульовим, порожнім або хибним значенням».
Сигнатура приймає мапу й ключ як окремі аргументи, бо значення, передане через оператор | шаблонів Go, втрачає доступ до батьківської мапи. Без батьківської мапи в області видимості наявність перевірити неможливо.
Перевірка наявності має одне обмеження, і походить воно від шаблону, а не від допоміжної функції: шаблон значення читає відсутній ключ як «нічого», і робить це, підставляючи порожнє значення для кожного відсутнього ключа, який шаблон називає як шлях через крапку й читає як значення. Тож шаблон, що читає один ключ і через optional, і як такий шлях, вважає цей ключ наявним і порожнім та отримує порожнє значення замість запасного. Читайте ключ одним способом у межах шаблону, і обидві відповіді збігатимуться.
# 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 → 0Останній випадок — саме те розрізнення, якого не може зробити default у Sprig. {{ .infra.replicas | default 1 }} повертає 1 незалежно від того, чи replicas задано як 0, чи пропущено, — це змішування унеможливлює легітимні шаблони масштабування до нуля, відсутності повторних спроб, відсутності тайм-ауту та хибних прапорців.
Домовленість щодо лапок для ключів: надавайте перевагу зворотним апострофам. Шаблони Go приймають для аргументу-ключа як рядкові літерали в подвійних лапках ("replicas"), так і у зворотних апострофах (`replicas`); обидва дають той самий рядок під час обчислення шаблону. Приклади каталогу й документації одноманітно використовують форму зі зворотними апострофами, бо вона безпечна для YAML у будь-якому контексті лапок. Ключ у подвійних лапках усередині скаляра YAML у подвійних лапках завершує рядок YAML посеред шаблону:
# 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 }}"Коли шаблон розміщено всередині блокового скаляра YAML (форма |) або як скаляр без лапок, обидві форми рендеряться правильно. Коли шаблон вбудовано в скаляр YAML у подвійних лапках (шаблон field: "{{ ... }}", де значення поля є шаблоном), зворотні апострофи обов’язкові. Єдина домовленість (завжди зворотні апострофи) повністю усуває пастку з лапками YAML.
Коли надавати перевагу optional над default. Використовуйте optional, коли поле може легітимно бути нульовим, порожнім або хибним і автору каталогу потрібно відрізнити «автор цього не задав» від «автор задав хибне значення». Використовуйте default, коли змішування прийнятне (наприклад, рядкові поля, де порожнє значення некоректне; числові поля, де нуль некоректний).
Доступність за поверхнями. optional зареєстровано на кожній поверхні, яку обчислює рендерер: поверхнях шаблонів значень (valuesMapping у Recipe, injectMapping у FeatureRecipe, provides, pipeline.with, тіло Workload), в обчислювачі тверджень і в шаблонах шляхів (directory: / subDirectory: на межах Release). На поверхні шаблонів шляхів відрізняється не набір допоміжних функцій, а політика щодо відсутніх ключів: шаблон шляху вважає відсутній ключ помилкою, а не порожнім значенням, бо мовчки порожній сегмент шляху створює зламану структуру файлової системи, яку виявляють лише після збирання. optional читає ключ до того, як спрацює ця сувора політика, і саме тому його можна там використовувати.
capitalizedWords — згортання імені в літери й цифри
capitalizedWords <string> читає свій аргумент як слова, розділені послідовностями будь-яких символів, крім літер і цифр ASCII, робить першу літеру кожного слова великою і з’єднує їх. Кожен символ результату — літера або цифра.
Вона існує тому, що деякі цільові платформи приймають в іменах, за якими звертаються до ресурсів, лише літери й цифри, тоді як ідентифікатор компонента може легітимно містити крапку, дефіс або підкреслення. Ручне написання цього перетворення в кожному Recipe, якому воно потрібне, породжує кілька варіантів однієї ідеї; одна допоміжна функція дає кожному автору ту саму відповідь.
# 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🔴 Результат не ідентифікує ім’я, з якого його отримано. Усі роздільники відкидаються, тож два ідентифікатори, що відрізняються лише розташуванням роздільників, дають той самий результат — payments-db і payments_db обидва дають PaymentsDb. Допоміжна функція не може цього виявити, бо бачить одне ім’я за раз; виявлення — справа того, що звертається до ресурсів за результатом. Цільова платформа, яка так робить, відхиляє колізію замість того, щоб видати розгортання без одного з двох: під час збирання для CloudFormation два компоненти, чиї ідентифікатори згортаються в одне ім’я, зупиняють збирання, а повідомлення називає кожен ідентифікатор, що дав це ім’я. Обирайте ідентифікатори, які відрізняються не лише пунктуацією, і питання не виникне.
Доступність за поверхнями. capitalizedWords зареєстровано всюди, де й optional: на кожній поверхні, яку обчислює рендерер, і при розв’язанні структурованої координати source:. Вона недоступна в інтерполяції параметрів Aggregate, яка пропонує лише набір Sprig.
index — ключ, який мапа мусить містити
index <collection> <key>... читає колекцію за позицією або за ключем, як і власна index у Go, — з однією відмінністю. Коли колекція є мапою і мапа не містить ключа, index зупиняє збирання й називає ключ, тоді як версія Go відповідає порожнім значенням, що друкується як буквальний текст <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")Це читання слід використовувати там, де ключ мусить бути, — облікові дані, прочитані під ім’ям змінної, яке обчислив Recipe, ключ, який публікує інший шаблон, — щоб відсутній ключ зупиняв збирання, а не потрапляв в артефакт як <no value>. Там, де ключ може легітимно бути відсутнім, спершу перевірте його: {{ optional .values `replicas` 1 }} надає запасне значення, get у Sprig повертає порожній рядок, а hasKey перевіряє без читання. Читання через index з подальшим застосуванням default не дає запасного значення, бо зупинка настає раніше, ніж виконується default. Ключ, який наявний і містить null, не є відсутнім: index повертає його, і він друкується як <no value>.
Зупинка — властивість лише index, і вона однакова на кожній поверхні: у шаблонах значень, обчислювачі тверджень, шаблонах шляхів, структурованій координаті source:, інтерполяції параметрів Aggregate, предикаті validate: параметра та предикатах x-aggrega-when: / x-aggrega-validate: схеми. Читання незаданого ключа через крапку дотримується власної політики своєї поверхні щодо відсутніх ключів, і зупинка на нього не впливає. Зупинку задокументовано в errors/fatal-halts.md: «A template indexes a map with a key the map does not hold (Шаблон індексує мапу ключем, якого мапа не містить)».
Поширені допоміжні функції, які НЕ доступні
Helm розширює text/template мови Go допоміжними функціями шаблонів чартів, які часто помилково вважають загальними допоміжними функціями Sprig. Жодна з них не зареєстрована в рендерері Aggrega. Шаблони, які обчислює рендерер Aggrega (Recipe valuesMapping:, FeatureRecipe injectMapping:, provides, тіло Workload, обчислювач тверджень), не можуть їх викликати:
include— бажана в Helm форма виклику визначеного фрагмента шаблону з рядковим виводом, який можна передати в конвеєр. Рендерер Aggrega її не реєструє. Натомість використовуйте стандартний для шаблонів Go{{ template "name" . }}(форма лише з побічним ефектом); для виводу, який можна передати в конвеєр, компонуйте за допомогою фрагментів MappingLibrary і директив$import:.tpl— повторно обчислює рядок як вкладений шаблон у поточному контексті. Aggrega її не реєструє; вкладене повторне обчислення не входить до поверхні шаблонів. Авторам, яким потрібні обчислені значення, слід компонувати їх за допомогою рядкових допоміжних функцій Sprig і виводити кінцеве значення безпосередньо.required— перериває рендеринг чарту з власним повідомленням, коли вказане значення відсутнє. Aggrega її не реєструє. Контроль обов’язкових полів в Aggrega відбувається на рівні типізованого контракту параметрів (слотparameters:сутності Aggregate зrequired: true, який Release залишає незаповненим, зупиняє збирання зE0165, називаючи слот і місце, де Aggregate його оголошує); перевірки маркерів обов’язковості в окремих шаблонах використовуютьfailзі Sprig, щоб викликати фатальну помилку шаблону з переданим рядком.warn— виводить нефатальне повідомлення в термінал оператора. Aggrega її не реєструє. Шаблонам, яким потрібно зупинити рендеринг із пояснювальним повідомленням, слід використовуватиfailзі Sprig; шаблонам, яким потрібно перейти до запасного значення без зупинки, слід покладатися на стандартні гілки Goif/else.
Перелік допоміжних функцій різних рушіїв (суттєвий для авторів MappingLibrary)
Фрагменти MappingLibrary можуть бути призначені для одного з двох місць використання:
- Використання на боці Aggrega (Recipe
valuesMapping:, FeatureRecipeinjectMapping:тощо, обчислюються рендерером Aggrega). Доступні допоміжні функції: повний Sprig v3 (default,coalesce,quote,nindent,indent,b64encтощо) плюс власні функції Aggrega (optional,capitalizedWords), аindexзупиняє збірку на ключі, якого немає в мапі. Допоміжні функції шаблонів чартів (include,tpl,required,warn) НЕ доступні. - Використання всередині чарту Helm (вміст
values.yamlчарту абоtemplates/*.yamlчарту, які далі рендерить власний рушій шаблонів Helm). Доступні допоміжні функції: повний Sprig v3 плюс допоміжні функції шаблонів чартів Helm (include,tpl,required,warn). Власні допоміжні функції Aggrega НЕ доступні, аindexтам — власна функція Go, яка на відсутній ключ відповідає порожнім значенням, а не зупинкою.
Обидва набори допоміжних функцій мають спільну поверхню Sprig, але розходяться в розширеннях, специфічних для рушія. Записи MappingLibrary, призначені для використання всередині чарту Helm, дотримуються домовленостей Helm (корінь .Values.<key> з великою V, | default, композиція на основі include); записи, призначені для використання на боці Aggrega, дотримуються домовленостей Aggrega (.values.<key> з малої літери, optional для запасного значення з урахуванням наявності). Сутність бібліотеки зберігає фрагменти дослівно; форма написання залежить від того, де фрагмент має рендеритися.
Власні допоміжні функції Aggrega поверх Sprig — це optional і capitalizedWords, обидві описані вище, а її index замінює функцію Go, як описано вище. Решта поверхні допоміжних функцій — це рівно набір Sprig v3.
Перехресні посилання
template-context-contract.md— поля середовища виконання, які шаблони читають поряд із допоміжними функціями Sprig.expansion-matrix.md— порядок обчислення для кожного місця шаблону.05-templates.md— огляд шаблонізації та домовленості щодо написання.- Документація Sprig v3 — канонічний довідник за кожною функцією.