Funções e helpers Sprig
O motor de templates do Aggrega conecta a biblioteca de funções Sprig v3 mais os helpers próprios do Aggrega (optional e capitalizedWords) em todo template Go que o renderizador avalia, e substitui a função index do Go por uma que interrompe diante de 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 junto com as funções nativas de text/template do Go e os campos do contexto de runtime documentados em template-context-contract.md.
🔴 Leia “que o renderizador avalia” como o escopo que é, porque uma superfície de autoria fica fora dele. Uma coordenada source: estruturada é resolvida para que o artefato que ela nomeia possa ser fixado, e essa resolução não é uma passagem de renderização: ela registra os helpers próprios do Aggrega e nada mais, então uma chamada Sprig em um campo source:, ou em uma 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 artefato, e é por isso que seu conjunto de funções é deliberadamente mais restrito — veja errors/fatal-halts.md “Resolving a source: coordinate registers a narrower function set (A resolução de uma coordenada source registra um conjunto de funções mais restrito)” para a interrupção e a forma portável a usar em vez disso.
O conjunto do Sprig é registrado sozinho para a interpolação de parâmetros, e junto com os helpers próprios do Aggrega nas superfícies de template de valor do renderizador.
O que está conectado
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 abreviação (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 decodificação em vez de zerar silenciosamente. - Verificações de tipo —
typeOf,typeIs,typeIsLike,kindOf,kindIs,deepEqual,empty. - Valores padrão 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 operacional). - 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 saída idêntica byte a byte para 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 artefatos renderizados:
- Leitores do relógio do sistema —
now,date,dateInZone,dateModify,htmlDate,htmlDateInZone,agoquando chamado sem um horário de referência congelado. - 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 as estações de trabalho dos operadores e os runners de CI). - Resolvedores de rede —
getHostByName.
Esses helpers não são bloqueados pelo motor; eles fazem parte do conjunto do Sprig v3. A disciplina de evitá-los 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 em um 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 em 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 retorna — 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 carrega cada um, de modo 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 o build, nomeando os dois tipos. Compare o número com um número escrito sem aspas, ou converta-o 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; veja 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 seus próprios helpers.
- O autor o escreveu?
hasKeyeoptionalrespondem pela presença. Uma chave que o autor escreveu está presente seja qual for seu conteúdo —0,""efalseincluídos — e somente 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 ali, 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 — uma contagem de réplicas igual a zero, um timeout igual a zero, uma flag desativada — é 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. Leia uma determinada chave 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> retorna o valor em <key> dentro de <map> se a chave estiver presente; caso contrário, retorna <fallback>. Diferentemente 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 escopo, a presença não pode ser verificada.
Um limite à verificação de presença, e ele 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 por meio de optional quanto como esse caminho encontra essa chave presente e vazia, e obtém o valor vazio em vez do valor alternativo. Leia uma chave de uma única maneira por template e as duas respostas concordam.
# 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 }} retorna 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 falsa.
Convenção para as aspas das chaves: prefira crases. Os templates Go aceitam para o argumento de chave tanto literais de string entre aspas duplas ("replicas") quanto entre crases (`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 crases porque ela é segura para YAML em qualquer contexto de aspas. Uma chave entre aspas duplas dentro de um escalar YAML entre aspas duplas encerra a string YAML no 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 fica dentro de um escalar de bloco YAML (forma |) ou como um escalar de valor simples, ambas as formas são renderizadas corretamente. Quando o template está incorporado em um escalar YAML entre aspas duplas (o padrão field: "{{ ... }}" de valor de campo como template), as crases são obrigatórias. A convenção única (sempre crases) evita por completo a armadilha das aspas do YAML.
Quando preferir optional a default. Use optional quando o campo puder legitimamente ser zero, vazio ou falso e o autor do catálogo precisar distinguir “o autor não definiu isto” de “o autor definiu isto com um valor falsy”. Use default quando a confusão for 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á registrado em toda superfície 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 ausente: um template de caminho trata uma chave ausente como erro e não como vazia, porque um segmento de caminho silenciosamente vazio produz um layout de sistema de arquivos quebrado que só é descoberto depois do build. optional lê uma chave sem que essa política estrita dispare primeiro, e é isso que o torna utilizável ali.
capitalizedWords — reduzir um nome a letras e dígitos
capitalizedWords <string> lê seu argumento como palavras separadas por sequências de qualquer caractere fora das letras e dígitos ASCII, coloca em maiúscula a primeira letra de cada palavra e as junta. Todo caractere do resultado é uma letra ou um dígito.
Ele 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 precisa dela produz várias grafias de uma mesma ideia; um único helper dá a todo autor 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 veio. Todo separador é descartado, de modo que dois ids que diferem apenas na posição de seus separadores chegam ao mesmo resultado — payments-db e payments_db dão ambos PaymentsDb. O helper não consegue detectar isso, porque vê um nome de cada vez; capturá-lo cabe ao que endereça recursos pelo resultado. Um destino que faz isso rejeita a colisão em vez de emitir uma implantação em que falta um dos dois: no build para CloudFormation, dois componentes cujos ids se reduzem a um mesmo nome interrompem o build, e a mensagem nomeia cada id que chegou a ele. Escolha ids que difiram em mais do que a pontuação, e a questão não se coloca.
Disponibilidade por superfície. capitalizedWords está registrado onde quer que optional esteja: em toda superfície 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 deve conter
index <collection> <key>... lê uma coleção por posição ou por chave, como faz 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 o build 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 precisa 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 ausente pare o build em vez de chegar a um artefato como <no value>. Onde a chave pode legitimamente estar ausente, teste-a primeiro: {{ optional .values `replicas` 1 }} fornece um valor alternativo, o get do Sprig retorna uma string vazia e hasKey testa sem ler. Ler por meio de index e depois aplicar default não fornece um valor alternativo, porque a interrupção vem antes de default ser executado. Uma chave que está presente e contém null não está ausente: index a retorna, e ela é impressa como <no value>.
A interrupção é uma propriedade apenas de index, e é a mesma em toda superfície — 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 ausente da 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 costumam ser confundidos com helpers gerais do Sprig. Nenhum deles está registrado 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 podem chamá-los:
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 registra. Use em vez disso{{ template "name" . }}do template Go padrão (a forma apenas com efeitos colaterais); para uma saída encadeável por pipe, componha usando fragmentos de MappingLibrary e diretivas$import:.tpl— reavalia uma string como template aninhado em relação ao contexto atual. O Aggrega não o registra; a reavaliação aninhada não faz parte da superfície de templates. Autores que precisam de valores calculados devem compô-los com os helpers de string do Sprig e emitir o valor final diretamente.required— faz a renderização do chart falhar com uma mensagem personalizada quando o valor nomeado está ausente. O Aggrega não o registra. A aplicação de campos obrigatórios no Aggrega fica na camada de contratos de parâmetros tipados (um slotparameters:de um Aggregate comrequired: trueque a Release deixa sem preencher interrompe o build comE0165, nomeando o slot e o lugar 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 carrega a string fornecida.warn— emite uma nota não fatal no terminal do operador. O Aggrega não o registra. Templates que precisam interromper a renderização com uma mensagem explicativa devem usar ofaildo Sprig; templates que precisam recorrer a um valor alternativo sem interromper devem contar com as ramificaçõesif/elsepadrão do Go.
Inventário de helpers entre motores (fundamental para 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,b64encetc.) mais os próprios do Aggrega (optional,capitalizedWords), eindexinterrompe diante de 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, eindexali é o próprio do Go, que responde a uma chave ausente com um valor vazio em vez de interromper.
Os dois conjuntos de helpers compartilham 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 armazena os fragmentos literalmente; a forma de autoria segue o local onde o fragmento se destina a ser renderizado.
Os helpers personalizados do Aggrega além do Sprig são optional e capitalizedWords, ambos documentados acima, e o seu index substitui o do Go, como documentado acima. O restante da superfície de helpers é exatamente o conjunto do Sprig v3.
Referências cruzadas
template-context-contract.md— os campos de runtime que os templates leem junto com os helpers do Sprig.expansion-matrix.md— ordem de avaliação por local de template.05-templates.md— visão geral do uso de templates e convenções de autoria.- Documentação do Sprig v3 — referência canônica por função.