Funções e helpers Sprig
O motor de templates do Aggrega liga a biblioteca de funções Sprig v3 mais os helpers próprios do Aggrega (optional e capitalizedWords) a cada template Go que o renderizador avalia, e substitui a função index do Go por uma que interrompe perante uma chave que o mapa não contém. Os autores que escrevem o valuesMapping: de uma Recipe, o injectMapping: de uma FeatureRecipe ou qualquer outra superfície de template que o renderizador avalia têm à disposição o conjunto completo de helpers do Sprig, a par das funções nativas de text/template do Go e dos campos do contexto de execução documentados em template-context-contract.md.
🔴 A expressão «que o renderizador avalia» deve ler-se como o âmbito que é, porque uma superfície de autoria fica fora dele. Uma coordenada source: estruturada é resolvida para que o artefacto que nomeia possa ser fixado, e essa resolução não é uma passagem de renderização: regista os helpers próprios do Aggrega e nada mais, pelo que uma chamada Sprig num campo source:, ou numa entrada locals: que ele lê, interrompe o pull. Uma entrada que nenhum campo source: lê é avaliada apenas pela renderização, com o conjunto completo. Resolver uma coordenada determina o que é fixado em vez de produzir um artefacto, e é por isso que o seu conjunto de funções é deliberadamente mais restrito — consulte errors/fatal-halts.md «Resolving a source: coordinate registers a narrower function set (A resolução de uma coordenada source regista um conjunto de funções mais restrito)» para a interrupção e a forma portável a usar em alternativa.
O conjunto do Sprig é registado isoladamente para a interpolação de parâmetros, e juntamente com os helpers próprios do Aggrega nas superfícies de template de valor do renderizador.
O que está ligado
O Sprig v3 expõe toda a sua superfície de helpers — cerca de 200 funções nas categorias abaixo. Esta página esboça as categorias com os helpers comuns de cada uma; a referência canónica por função é a documentação upstream do Sprig.
- Strings —
upper,lower,title,trim,trimAll,trimPrefix,trimSuffix,replace,contains,hasPrefix,hasSuffix,substr,quote,squote,cat,indent,nindent,repeat, helpers de estilo de nome (snakecase,camelcase,kebabcase), helpers de abreviatura (abbrev,abbrevboth,trunc), helpers de checksum (sha1sum,sha256sum,sha512sum,adler32sum),toString. - Listas —
list,tuple,first,last,rest,initial,append/push,prepend,concat,reverse,uniq,without,has,slice,chunk,join,splitList,split,splitn,sortAlpha,compact. - Dicionários —
dict,get,set,unset,hasKey,keys,values,pick,omit,pluck,merge,mergeOverwrite,dig,deepCopy. - Matemática —
add,sub,mul,div,mod,add1,min,max,ceil,floor,round, mais as variantes decimais com o sufixof(addf,subf,mulf,divf,minf,maxf). - Conversão —
int,int64,float64,atoi,toString,toDecimal,seq,until,untilStep. - Codificação —
b64enc,b64dec,b32enc,b32dec,toJson,toPrettyJson,toRawJson,fromJson, mais as variantes JSON com o prefixomustque expõem erros de descodificação em vez de pôr silenciosamente a zero. - Verificações de tipo —
typeOf,typeIs,typeIsLike,kindOf,kindIs,deepEqual,empty. - Valores predefinidos e fluxo —
default,coalesce,all,any,ternary,fail(gera um erro de template com uma mensagem personalizada — a forma canónica de abortar uma renderização com uma mensagem de guarda). - Regex —
regexMatch,regexFind,regexFindAll,regexReplaceAll,regexReplaceAllLiteral,regexSplit,regexQuoteMeta, mais as variantes estritas com o prefixomust. - Caminhos —
base,dir,clean,ext,isAbs(estilo Unix);osBase,osClean,osDir,osExt,osIsAbs(conforme o sistema operativo). - SemVer —
semver,semverCompare. - URL —
urlParse,urlJoin. - Datas —
ago,date,dateInZone,dateModify,duration,durationRound,htmlDate,htmlDateInZone,now,toDate,unixEpoch.
Ressalva sobre o determinismo
O Aggrega garante uma saída idêntica byte a byte para uma entrada idêntica byte a byte. Um subconjunto dos helpers do Sprig lê o estado do ambiente e quebra essa garantia quando invocado a partir de um template. Os autores devem evitar os seguintes helpers nas superfícies de template que contribuem para artefactos renderizados:
- Leitores do relógio do sistema —
now,date,dateInZone,dateModify,htmlDate,htmlDateInZone,agoquando chamado sem uma hora de referência fixa. - Geradores aleatórios —
randAlpha,randAlphaNum,randAscii,randNumeric,randBytes,randInt,uuidv4. - Leitores do ambiente —
env,expandenv(leem variáveis de ambiente do processo, que diferem entre os postos de trabalho dos operadores e os runners de CI). - Resolvedores de rede —
getHostByName.
Estes helpers não são bloqueados pelo motor; fazem parte do conjunto do Sprig v3. A disciplina de os evitar em templates do caminho de renderização é mantida pelos revisores e pela garantia de saída determinística da qual dependem os autores e o catálogo da biblioteca padrão.
Números num template de valor
Um número que um autor escreve chega a um template de valor como número. Um número sem parte decimal é um inteiro e é impresso inteiro: 1000000 imprime 1000000. Qualquer outro número é impresso na sua forma decimal exata mais curta, nunca em notação exponencial: um 0.0000001 escrito pelo autor imprime 0.0000001 e um 1e21 escrito pelo autor imprime 1000000000000000000000, quer o template escreva o valor diretamente, quer o converta em texto com toString, quote, printf "%v" ou toJson. Um número que uma função matemática devolve — mulf, float64, round e afins — é o valor próprio dessa função e é impresso na forma própria dessa função, que é a notação exponencial para um valor muito pequeno ou muito grande: {{ mulf .values.ratio 1 }} imprime 1e-07 para um 0.0000001 escrito pelo autor.
As comparações — eq, ne, lt, le, gt e ge — leem dois números pelo valor, seja qual for o tipo que transporta cada um, pelo que um inteiro escrito pelo autor se compara com um decimal escrito no template, e 3 é igual a 3.0:
{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → trueUm número nunca é comparado com um texto: qualquer uma das seis, ao receber um número e um texto entre aspas, interrompe a compilação, nomeando os dois tipos. Deve comparar o número com um número escrito sem aspas ou convertê-lo primeiro em texto:
{{ 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 → trueA interrupção é A value template failed while it ran (Um template de valores falhou durante a execução). Uma asserção lê um número escrito pelo autor da mesma forma; consulte Números nesta superfície.
Presença e vazio — duas perguntas diferentes
Um template faz uma de duas perguntas sobre um valor, e cada pergunta tem os seus próprios helpers.
- Foi o autor que o escreveu?
hasKeyeoptionalrespondem pela presença. Uma chave que o autor escreveu está presente seja qual for o seu conteúdo —0,""efalseincluídos — e apenas uma chave que o autor omitiu está ausente. - Está vazio?
default,with,ifeemptyrespondem pelo vazio.0,"",false, uma lista vazia, um mapa vazio e um valor ausente contam todos como vazios aí, tal como no Helm.
.values.replicas | hasKey .values "replicas" | optional .values "replicas" 1 | .values.replicas | default 1 | if .values.replicas |
|---|---|---|---|---|
| ausente | false | 1 | 1 | false |
0 | true | 0 | 1 | false |
3 | true | 3 | 3 | true |
Um valor que pode legitimamente ser 0, "" ou false — um número de réplicas igual a zero, um timeout igual a zero, uma flag desligada — é testado com hasKey ou optional, para que o 0 do autor chegue à saída como 0. default, with e if servem para um valor cuja forma vazia não tem significado próprio, em que «vazio» e «não escrito» podem ser tratados da mesma forma. Cada chave deve ser lida de uma única maneira por template: uma chave que o template também lê como caminho com pontos conta como presente, como descreve o limite de optional.
Helpers específicos do Aggrega
optional — valor alternativo sensível à presença
optional <map> <key> <fallback> devolve o valor em <key> dentro de <map> se a chave estiver presente; caso contrário, devolve <fallback>. Ao contrário do default do Sprig, optional distingue «chave ausente» de «chave presente com um valor zero, vazio ou falso».
A assinatura recebe o mapa e a chave como argumentos separados porque um valor passado pelo operador | do template Go perdeu o acesso ao seu mapa pai. Sem o mapa pai no âmbito, não é possível verificar a presença.
Um limite à verificação de presença, e vem do template e não do helper: um template de valor lê uma chave ausente como nada, o que faz fornecendo um valor vazio em cada chave ausente que o template nomeia como caminho com pontos e lê como valor. Assim, um template que lê uma chave tanto através de optional como através desse caminho encontra essa chave presente e vazia, e obtém o valor vazio em vez do valor alternativo. Lendo cada chave de uma única maneira por template, as duas respostas coincidem.
# 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 → 0O último caso é a distinção que o default do Sprig não consegue fazer. {{ .infra.replicas | default 1 }} devolve 1 quer replicas tenha sido escrito como 0, quer tenha sido omitido — a confusão que impede os padrões legítimos de scale-to-zero, sem novas tentativas, sem timeout e de flag a falso.
Convenção para as aspas das chaves: preferir acentos graves. Os templates Go aceitam para o argumento de chave tanto literais de string entre aspas duplas ("replicas") como entre acentos graves (`replicas`); ambos produzem a mesma string no momento da avaliação do template. Os exemplos do catálogo e da documentação usam uniformemente a forma com acentos graves porque é segura para YAML em qualquer contexto de aspas. Uma chave entre aspas duplas dentro de um escalar YAML entre aspas duplas termina a string YAML a meio do 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 }}"Quando o template está dentro de um escalar de bloco YAML (forma |) ou como escalar de valor simples, ambas as formas são renderizadas corretamente. Quando o template está incorporado num escalar YAML entre aspas duplas (o padrão field: "{{ ... }}" de valor de campo como template), os acentos graves são obrigatórios. A convenção única (sempre acentos graves) evita por completo a armadilha das aspas do YAML.
Quando preferir optional a default. Deve usar-se optional quando o campo pode legitimamente ser zero, vazio ou falso e o autor do catálogo precisa de distinguir «o autor não definiu isto» de «o autor definiu isto com um valor falsy». Deve usar-se default quando a confusão é aceitável (p. ex., campos de string em que vazio é inválido; campos numéricos em que zero é inválido).
Disponibilidade por superfície. optional está registado em todas as superfícies que o renderizador avalia: as superfícies de template de valor (valuesMapping da Recipe, injectMapping da FeatureRecipe, provides, pipeline.with, o corpo do Workload), o avaliador de asserções e os templates de caminho (directory: / subDirectory: nas fronteiras da Release). O que difere na superfície de templates de caminho não é o conjunto de helpers, mas a política de chave em falta: um template de caminho trata uma chave ausente como erro e não como vazia, porque um segmento de caminho silenciosamente vazio produz uma estrutura de sistema de ficheiros danificada que só é descoberta depois da compilação. optional lê uma chave sem que essa política estrita seja acionada primeiro, e é isso que o torna utilizável aí.
capitalizedWords — reduzir um nome a letras e dígitos
capitalizedWords <string> lê o seu argumento como palavras separadas por sequências de qualquer carácter fora das letras e dígitos ASCII, coloca em maiúscula a primeira letra de cada palavra e junta-as. Cada carácter do resultado é uma letra ou um dígito.
Existe porque alguns destinos aceitam apenas letras e dígitos nos nomes pelos quais endereçam recursos, enquanto um id de componente pode legitimamente conter um ponto, um hífen ou um sublinhado. Escrever essa conversão à mão em cada Recipe que dela precisa produz várias grafias de uma mesma ideia; um único helper dá a todos os autores a mesma resposta.
# 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🔴 O resultado não identifica o nome de onde provém. Cada separador é descartado, pelo que dois ids que diferem apenas na posição dos seus separadores chegam ao mesmo resultado — payments-db e payments_db dão ambos PaymentsDb. O helper não o consegue detetar, porque vê um nome de cada vez; apanhá-lo cabe ao que endereça recursos pelo resultado. Um destino que o faz rejeita a colisão em vez de emitir uma implementação em que falta um dos dois: na compilação para CloudFormation, dois componentes cujos ids se reduzem a um mesmo nome interrompem a compilação, e a mensagem nomeia cada id que lá chegou. Escolhendo ids que difiram em mais do que a pontuação, a questão não se coloca.
Disponibilidade por superfície. capitalizedWords está registado onde quer que optional esteja: em todas as superfícies que o renderizador avalia e na resolução de uma coordenada source: estruturada. Não está disponível na interpolação de parâmetros do Aggregate, que oferece apenas o conjunto do Sprig.
index — uma chave que o mapa tem de conter
index <collection> <key>... lê uma coleção por posição ou por chave, tal como o próprio index do Go — com uma diferença. Quando a coleção é um mapa e o mapa não contém a chave, index interrompe a compilação e nomeia a chave, enquanto o do Go responde com um valor vazio que é impresso como o texto 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")É a leitura a usar onde a chave tem de estar presente — uma credencial lida sob o nome de variável que a Recipe calculou, uma chave que outro template publica — para que uma chave em falta pare a compilação em vez de chegar a um artefacto como <no value>. Onde a chave pode legitimamente estar ausente, deve testá-la primeiro: {{ optional .values `replicas` 1 }} fornece um valor alternativo, o get do Sprig devolve uma string vazia e hasKey testa sem ler. Ler através de index e depois aplicar default não fornece um valor alternativo, porque a interrupção ocorre antes de default ser executado. Uma chave que está presente e contém null não está ausente: index devolve-a, e é impressa como <no value>.
A interrupção é uma propriedade apenas de index, e é a mesma em todas as superfícies — os templates de valor, o avaliador de asserções, os templates de caminho, uma coordenada source: estruturada, a interpolação de parâmetros do Aggregate, o predicado validate: de um parâmetro e os predicados x-aggrega-when: / x-aggrega-validate: de um esquema. Uma leitura com ponto de uma chave não definida segue a política de chave em falta da sua própria superfície e não é afetada. A interrupção está documentada em errors/fatal-halts.md «A template indexes a map with a key the map does not hold (Um template indexa um mapa com uma chave que o mapa não contém)».
Helpers comuns NÃO disponíveis
O Helm estende o text/template do Go com helpers de template de chart que são frequentemente confundidos com helpers gerais do Sprig. Nenhum deles está registado no renderizador do Aggrega. Os templates que o renderizador do Aggrega avalia (valuesMapping: da Recipe, injectMapping: da FeatureRecipe, provides, o corpo do Workload, o avaliador de asserções) não os podem chamar:
include— a forma preferida do Helm para invocar um fragmento de template definido com uma saída de string encadeável por pipe. O renderizador do Aggrega não o regista. Deve usar-se em alternativa{{ template "name" . }}do template Go padrão (a forma apenas com efeitos secundários); para uma saída encadeável por pipe, deve compor-se com fragmentos de MappingLibrary e diretivas$import:.tpl— reavalia uma string como template aninhado em relação ao contexto atual. O Aggrega não o regista; a reavaliação aninhada não faz parte da superfície de templates. Os autores que precisam de valores calculados devem compô-los com os helpers de string do Sprig e emitir diretamente o valor final.required— faz falhar a renderização do chart com uma mensagem personalizada quando o valor nomeado está em falta. O Aggrega não o regista. A aplicação dos campos obrigatórios no Aggrega situa-se na camada dos contratos de parâmetros tipados (um slotparameters:de um Aggregate comrequired: trueque a Release deixa por preencher interrompe a compilação comE0165, nomeando o slot e o local onde o Aggregate o declara); as verificações de marcadores de obrigatoriedade por template usam ofaildo Sprig para gerar um erro de template fatal que transporta a string fornecida.warn— emite uma nota não fatal no terminal do operador. O Aggrega não o regista. Os templates que precisam de interromper a renderização com uma mensagem explicativa devem usar ofaildo Sprig; os templates que precisam de recorrer a um valor alternativo sem interromper devem apoiar-se nas ramificaçõesif/elsepadrão do Go.
Inventário de helpers entre motores (fundamental para os autores de MappingLibrary)
Os fragmentos de MappingLibrary podem ter como destino um de dois locais de consumo:
- Consumo do lado do Aggrega (
valuesMapping:da Recipe,injectMapping:da FeatureRecipe, etc., avaliados pelo renderizador do Aggrega). Os helpers disponíveis são: o Sprig v3 completo (default,coalesce,quote,nindent,indent,b64enc, etc.) mais os próprios do Aggrega (optional,capitalizedWords), eindexinterrompe perante uma chave que o mapa não contém. Os helpers de template de chart (include,tpl,required,warn) NÃO estão disponíveis. - Consumo interno ao chart do Helm (conteúdo de
values.yamldo chart outemplates/*.yamldo chart renderizados a jusante pelo próprio motor de templates do Helm). Os helpers disponíveis são: o Sprig v3 completo mais os helpers de template de chart do Helm (include,tpl,required,warn). Os helpers próprios do Aggrega NÃO estão disponíveis, eindexaí é o próprio do Go, que responde a uma chave ausente com um valor vazio em vez de interromper.
Os dois conjuntos de helpers partilham a superfície do Sprig, mas divergem nas extensões específicas do motor. As entradas de MappingLibrary destinadas ao consumo interno ao chart do Helm usam as convenções do Helm (raiz .Values.<key> com V maiúsculo, | default, composição baseada em include); as entradas destinadas ao consumo do lado do Aggrega usam as convenções do Aggrega (.values.<key> em minúsculas, optional para o valor alternativo sensível à presença). A entidade de biblioteca guarda os fragmentos literalmente; a forma de criação segue o local onde o fragmento se destina a ser renderizado.
Os helpers personalizados do Aggrega para além do Sprig são optional e capitalizedWords, ambos documentados acima, e o seu index substitui o do Go, como documentado acima. O resto da superfície de helpers é exatamente o conjunto do Sprig v3.
Referências cruzadas
template-context-contract.md— os campos de execução que os templates leem a par dos helpers do Sprig.expansion-matrix.md— ordem de avaliação por local de template.05-templates.md— visão geral da utilização de templates e convenções de autoria.- Documentação do Sprig v3 — referência canónica por função.