Converter XML para TOML

Todo elemento com filhos vira uma tabela, escrita como um cabeçalho entre colchetes nomeando o caminho completo com pontos. Um elemento três níveis abaixo produz um cabeçalho contendo três nomes em vez de três blocos aninhados, porque o TOML expressa profundidade no cabeçalho, não na indentação.

Dentro de cada tabela, valores simples vêm primeiro e tabelas aninhadas vêm depois, a única ordem que o TOML permite — tudo sob um cabeçalho pertence a ele até o próximo cabeçalho aparecer. Isso significa que o resultado não lê na mesma ordem que o XML, e num arquivo com muitos elementos pequenos essa reorganização é considerável. É uma reordenação, não uma mudança: nenhum valor muda de caminho.

Esta é a parte da conversão que não precisa de conserto. Dois ou mais elementos irmãos com a mesma tag viram um array de tabelas do TOML, com o cabeçalho de colchete duplo escrito uma vez por item na ordem do documento. Uma lista de dependências, uma lista de servidores, uma lista de regras — todas caem na forma que uma configuração TOML já usaria de qualquer jeito.

A ressalva conhecida do XML continua valendo por baixo disso. Uma única ocorrência de um elemento repetível não é um array, então vira uma tabela comum com cabeçalho de colchete simples em vez disso. Converta um arquivo com uma entrada e o mesmo arquivo com duas, e os dois resultados diferem estruturalmente.

Uma chave TOML sem aspas permite letra, número, sublinhado e hífen, nada mais. Atributos chegam do interpretador como chaves começando com arroba, o texto próprio de um elemento sob uma chave chamada #text, e uma declaração de namespace como algo parecido. Todas essas são escritas entre aspas no resultado, o que é TOML correto e parece exatamente tão estranho quanto soa.

Também são uma lista de tarefas. Uma chave entre aspas é o conversor avisando que esse nome veio da maquinaria do XML, não da sua configuração, e quase toda deveria ser renomeada. Faça essa passagem uma vez, imediatamente, enquanto você ainda lembra o que o XML queria dizer.

Um documento TOML é ele mesmo uma tabela, e um documento XML tem exatamente um elemento raiz, então a configuração inteira aparece um nível mais fundo do que você quer — sob um único cabeçalho nomeado a partir da raiz. Um arquivo com raiz chamada configuração produz uma tabela configuração contendo tudo dentro dela.

Promover o conteúdo é uma edição mecânica: apague o primeiro cabeçalho e remova esse segmento de todo outro cabeçalho no arquivo. Vale fazer isso em vez de conviver com aquilo, porque todo caminho da configuração fica um nível mais curto, e um arquivo TOML é lido pelos seus cabeçalhos.

O TOML não tem valor nulo, e converter a partir de formatos que têm — YAML em particular — significa chave sumindo em silêncio quando o valor está vazio. Isso não pode acontecer aqui, porque o XML também não tem nulo. Um elemento vazio e um elemento autofechado significam a mesma coisa, e os dois viram uma string vazia, escrita como duas aspas.

Então a garantia nesta direção é mais forte que nas vizinhas: todo elemento que tinha um valor no XML tem uma chave no TOML. Strings vazias são fáceis de passar batido num arquivo longo, então, se a migração também é uma chance de remover configuração que ninguém usa, procurar por esses pares vazios no resultado é o jeito mais rápido de achar.

O TOML tem data e hora na especificação principal, e um interpretador devolve isso como data de verdade, não como texto. Um valor XML é texto, então uma data na origem chega como uma string entre aspas e continua assim.

Tirar as aspas desses valores no resultado é o que os transforma em datas TOML de verdade, e leva um minuto. O caso inverso também vale observar: um valor escrito como "1.0" no XML é interpretado como número e escrito como o inteiro TOML 1, então uma versão virou inteiro e perdeu a forma. Colocar aspas de volta é o conserto.

Um elemento contendo várias linhas — uma descrição, um bloco de licença, um script embutido — vira uma única string TOML básica com sequências de escape onde as quebras de linha estavam. É correto e é ilegível, e anula o propósito de migrar para um formato que as pessoas editam à mão.

O TOML tem uma sintaxe de string de várias linhas, com aspas triplas, que guarda esse valor de forma legível, e o gravador não usa. Ache os valores com escape e reescreva cada um como um bloco de aspas triplas. Na maioria das configurações há um ou dois; numa configuração cheia de texto embutido, isso é um sinal de que o conteúdo deveria viver no próprio arquivo, não dentro de uma configuração.

Comentários são descartados, mesmo os dois formatos suportando comentário, então as explicações do arquivo antigo não aparecem no novo. Namespace deixa de significar qualquer coisa no momento em que o prefixo vira caractere dentro de uma chave. E o esquema vai embora: XML pode ser validado contra um XSD antes de uma aplicação iniciar, e o TOML não tem linguagem de esquema nenhuma na própria especificação.

Esse último é a troca a fazer conscientemente. TOML é mais fácil de ler, mais fácil de escrever à mão e inequívoco quanto a tipo, e abre mão da capacidade de rejeitar uma configuração malformada mecanicamente. Se o XML de fato era validado no seu processo de build, você está removendo uma checagem, e substituir isso é parte da migração, não um extra opcional.

O que a ferramenta entrega é todo valor do XML, na tabela certa, com o nome certo na maioria dos casos e um nome entre aspas, obviamente errado, no resto. É um bom ponto de partida e não é um arquivo de configuração pronto.

O trabalho depois é pequeno e não é opcional: derrube a tabela raiz, renomeie as chaves de atributo e de texto, tire as aspas das datas, reescreva os valores de várias linhas, e copie os comentários do original. Uma hora num arquivo grande. Pular isso produz uma configuração TOML que funciona e que ninguém que a ler depois vai acreditar que foi escrita de propósito.