Converter YAML para TOML

Valores simples e arrays são escritos no topo, depois cada mapeamento aninhado aparece como seu próprio cabeçalho de tabela entre colchetes. Aninhar três níveis de profundidade produz um cabeçalho único com pontos nele em vez de três blocos aninhados, então um mapeamento escrito como tool, depois ruff, depois uma configuração, sai como um único cabeçalho [tool.ruff].

Esse achatamento dos cabeçalhos é a diferença visível entre os dois formatos. YAML expressa profundidade com espaço em branco e consegue aninhar sem limite antes de ficar ilegível; TOML expressa profundidade no nome do cabeçalho e continua legível em quatro níveis porque o caminho completo é escrito em todo bloco.

Uma linha escrita chave: sem nada depois é YAML válido e interpreta para null. TOML não tem valor nulo — a especificação simplesmente não o define — então o gravador omite a chave. Sem erro, sem placeholder, sem comentário: a chave estava no seu YAML e não está no seu TOML.

Isso importa mais do que parece porque chaves vazias são um idioma YAML deliberado. Marcam uma configuração como presente mas não definida, guardam um lugar para algo que um operador vai preencher depois. Procure linhas terminando em dois-pontos na origem antes de converter.

O mesmo null dentro de um array se comporta diferente: o gravador se recusa, e a conversão falha com uma mensagem dizendo que arrays não podem conter valores null ou undefined. Nada é produzido.

Esse é o melhor dos dois comportamentos, e a inconsistência é deliberada em vez de acidental. Descartar uma chave de uma tabela deixa o resto da tabela significativo; descartar um elemento de um array desloca todo elemento depois dele, mudando uma lista ordenada numa lista ordenada diferente.

TOML agrupa por tabela. Tudo que pertence a uma tabela precisa aparecer depois de seu cabeçalho e antes do próximo, então o gravador emite todo escalar e array primeiro e depois cada bloco aninhado por vez. Um .gitlab-ci.yml convertido assim coloca seu array de stages no topo e as definições de job abaixo como tabelas.

A consequência a planejar é o diff. Se o arquivo YAML está sob revisão e o TOML o substitui no mesmo repositório, o primeiro commit vai parecer uma reescrita em vez de uma tradução, porque é. Trate a conversão como seu próprio commit, sem mais nada nele.

Um escalar de bloco — o caractere pipe seguido de um script de shell indentado, como todo arquivo CI guarda seus comandos de build — interpreta para uma string contendo quebras de linha, e o gravador a emite como uma string TOML comum entre aspas com escapes \n nela. Um script de dez linhas vira uma linha muito longa.

TOML tem uma sintaxe de string de várias linhas usando aspas triplas que guardaria o script de forma legível, e o gravador não recorre a ela. Isso é uma conversão que você faz à mão: encontre os valores com quebras de linha escapadas neles e reescreva cada um como um bloco entre aspas triplas.

TOML é o único formato desta família com datas de primeira classe: datetimes com offset, datetimes locais, datas locais e horários locais são todos parte da especificação e um interpretador TOML devolve datas em vez de strings. Esse é o motivo principal de um projeto escolher TOML em vez de JSON.

Você não recebe isso desta conversão. YAML 1.2 trata um 2024-01-02 sem aspas como string, então chega no TOML como "2024-01-02" com aspas ao redor. Remover as aspas depois é o trabalho inteiro e leva segundos.

A construção com que as pessoas se preocupam acaba sendo a que funciona melhor. Uma lista YAML cujos itens são mapeamentos — uma lista de autores, uma lista de binários, uma lista de jobs — vira um array de tabelas TOML, com o cabeçalho de colchete duplo repetido uma vez por item.

Uma lista bem no topo do arquivo YAML é a exceção. Documentos TOML são sempre uma tabela, então um documento que é só uma sequência é embrulhado numa tabela com uma única chave chamada items e a lista embaixo.

Chaves nuas do TOML permitem letras, dígitos, underscore e hífen. Qualquer outra coisa precisa de aspas, e o gravador coloca por você: uma chave contendo um ponto sai como "date.timezone" com as aspas incluídas, o mesmo para uma chave contendo espaço. Chaves entre aspas são TOML totalmente válido.

Também são um sinal. Uma chave entre aspas com um ponto nela costuma significar que o YAML estava expressando estrutura no nome da chave em vez de no aninhamento, e em TOML essa estrutura seria melhor escrita como uma tabela de verdade.

Os dois formatos suportam comentários e nenhum dos seus atravessa. O interpretador os descarta ao ler e o gravador não tem nada para escrever. Num arquivo de configuração de projeto isso é um custo real — a nota explicando por que uma dependência está fixada, o bloco comentado mantido como exemplo.

A migração só está terminada quando esses voltam. Converta, depois abra o YAML antigo e o TOML novo lado a lado e reanexe os comentários onde pertencem. São dez minutos num arquivo típico, e é a diferença entre uma configuração que alguém consegue manter e uma que funciona e ninguém ousa mudar.