Converter YAML para INI

O INI tem exatamente um nível de agrupamento: uma seção entre colchetes e as chaves dentro dela. O YAML tem quantos níveis você quiser indentar. A conversão resolve isso percorrendo a árvore inteira, construindo um caminho com pontos para cada valor folha, e depois dividindo cada caminho uma vez — a parte antes do primeiro ponto vira a seção, o resto vira a chave.

Então um mapeamento YAML chamado database, contendo pool, contendo timeout, produz uma seção chamada database e uma chave chamada pool.timeout. Todo valor no documento sobrevive; só a forma se perde. Um leitor do outro lado vê chaves planas com pontos nelas e não tem como saber quais pontos eram aninhamento e quais eram parte de um nome.

Uma sequência YAML não tem equivalente no INI, então cada item vira uma chave nomeada a partir do índice dele. Um script de build escrito como uma lista de três comandos sai como script.0, script.1 e script.2 dentro da seção job, na ordem em que foram escritos.

A ordem é preservada, que é a parte que importa, mas a convenção é nossa, não um padrão. Alguns leitores de INI entendem chaves numeradas como uma lista, a maioria não, e alguns esperam um nome de chave repetido no lugar. Confira o que o programa que lê o arquivo faz com elas antes de presumir que a lista sobreviveu em algum sentido significativo — uma sequência ordenada que chega como três ajustes sem relação nenhuma foi convertida corretamente e entendida errado.

Uma lista no nível superior do documento não tem chave para ser numerada embaixo, então vira uma seção nomeada a partir de qualquer chave que a continha, com 0, 1 e 2 como nomes de chave. Um arquivo YAML cuja chave stages guarda duas entradas produz uma seção com cabeçalho stages contendo uma chave 0 e uma chave 1.

Uma seção cheia de números é INI válido e parece errado para quem lê. Se o programa de destino espera uma lista separada por vírgula numa única chave — que é o idioma comum do INI para uma sequência — junte a lista no YAML antes de converter, ou no INI depois. Não há ajuste que faça isso por você, porque as duas convenções não podem estar certas ao mesmo tempo.

Um bloco literal YAML — um caractere de pipe seguido de um bloco indentado, que é como todo arquivo de CI guarda um script de shell — se interpreta como uma única string com quebras de linha dentro. Até 09/08/2026 o gravador emitia essa string exatamente como estava, então as quebras de linha viravam quebras de linha reais: a primeira linha do script ficava depois do sinal de igual, e cada linha abaixo dela ficava sozinha. Ler esse arquivo de volta descartava essas linhas, e qualquer uma delas que parecesse um cabeçalho entre colchetes abria uma seção que nunca existiu no YAML, levando junto a próxima chave.

O gravador agora coloca entre aspas um valor de várias linhas e escreve cada quebra como uma barra invertida e um n, então o script fica numa linha só, fica numa entrada só, e volta inalterado por este conversor. O que não mudou é o destino: dialetos de INI discordam sobre escapes, e um leitor que trata uma barra invertida como um caractere comum vai devolver o seu script com esses dois caracteres dentro dele. Se o programa que lê o arquivo importa mais que a ida e volta, dobre o valor numa linha só no YAML, ou mantenha o script no próprio arquivo e aponte o INI para o caminho.

Uma chave YAML sem nada depois se interpreta como null e é gravada como a chave, um sinal de igual, e nada. O INI não consegue expressar a diferença entre uma chave não definida e uma string vazia, então as duas voltam como uma string vazia do outro lado. Se a distinção importa para o programa que lê o arquivo, ela precisa ser codificada de outro jeito — um valor sentinela, ou deixar a chave de fora inteiramente.

Booleanos são gravados como as palavras true e false. É o que a origem dizia, e não é o que todo consumidor de INI espera: configuração do Windows e o php.ini usam On e Off, e um leitor procurando por eles vai tratar true como uma string não reconhecida. Aspas são aplicadas só onde um valor não sobreviveria de outra forma a ser lido de volta — uma quebra de linha nele, um espaço em qualquer ponta, ou aspas já ao redor dele — então valores comuns mantêm sua pontuação e sua aparência nua. Um valor contendo um sinal de igual é deixado como está e ainda assim é lido corretamente de volta, porque leitores de INI dividem no primeiro sinal de igual.

Uma configuração de dois níveis de profundidade, contendo valores simples, sem valores de várias linhas, converte perfeitamente e não precisa de edição. Muita configuração de aplicativo é exatamente desse formato, o que explica o par existir — um bloco de ambiente de docker-compose ou um conjunto de feature flags achata sem perder nada que um leitor notaria.

Um arquivo com listas de mapeamentos não converte bem. Uma lista YAML de definições de servidor, cada uma com um host e uma porta, vira servers.0.host, servers.0.port, servers.1.host e assim por diante dentro de uma seção, que é uma codificação fiel do dado e um arquivo de configuração ilegível. Se essa é a sua origem, o conselho honesto é que INI não é um destino adequado, e a conversão está produzindo algo que você vai ter que reescrever de qualquer forma.

Um valor simples bem no nível superior do YAML — uma versão, um nome, uma flag única — não tem pai para virar uma seção. Esses valores são gravados primeiro, antes de qualquer cabeçalho entre colchetes, que é o idioma padrão do INI para um bloco global e é entendido pela maioria dos leitores.

Blocos de seção seguem, na ordem em que as chaves apareceram no YAML. Essa ordenação vale saber se o arquivo é revisado a olho em vez de por máquina, porque significa que a saída lê aproximadamente na mesma sequência da origem, e um diff entre duas conversões do mesmo arquivo continua legível.

Comentários são descartados. Os dois formatos suportam eles, o leitor descarta enquanto lê, e o gravador não tem nada para gravar de volta. A explicação acima de um timeout é exatamente o tipo de linha que fazia o YAML valer a pena ler, e ela não está no INI.

Um arquivo contendo separadores --- falha completamente em vez de converter parcialmente. Isso é proposital: um fluxo YAML pode conter vários documentos, um arquivo INI descreve um conjunto de ajustes, e pegar o primeiro documento silenciosamente produziria uma configuração faltando a maior parte de si mesma. Divida o arquivo e converta o documento que você realmente precisa.

A conversão vale a pena rodar quando o YAML é grande, plano e monótono. Não vale a pena rodar quando a origem é pequena — vinte ajustes são mais rápidos de redigitar do que converter e depois consertar, e redigitar força você a ler cada valor uma vez, o que é um benefício, não um custo, numa configuração prestes a ser confiada por um programa antigo.

Também é a ferramenta errada quando o destino espera um dialeto específico de INI. Programas que querem valores entre aspas, booleanos On e Off, listas separadas por vírgula ou chaves repetidas estão pedindo convenções que este gravador não produz. Converta para tirar os valores da árvore, depois remodele para caber no leitor que você realmente está alimentando.