Como tabelas TOML se tornam objetos JSON: [tabela], [[array]] e chaves pontilhadas

De onde veio o aninhamento? - um arquivo TOML de aparência simples convertido em JSON profundamente aninhado e os cabeçalhos que o causaram

Um arquivo TOML pode parecer quase plano porque os colchetes carregam o aninhamento. `[a.b.c]` abre tabelas intermediárias, então `d = 1` abaixo dele se torna `{"a":{"b":{"c":{"d":1}}}}`. As chaves JSON tornam visível uma hierarquia que TOML expressa através do caminho da tabela ativa.

ToolAcre delega a análise de sintaxe para smol-toml e depois normaliza os valores que JSON não pode transportar. Esta não é uma reescrita baseada em linhas. Tabelas, chaves pontilhadas e matrizes de tabelas tornam-se objetos e matrizes comuns antes da serialização JSON, razão pela qual sua ortografia e comentários não estão disponíveis na saída.

Cabeçalhos [tabela] — como um cabeçalho abre um objeto aninhado e como [a.b.c] cria objetos intermediários implicitamente

Um cabeçalho de colchete único abre uma tabela. `[owner]` direciona as seguintes atribuições para `owner`; `[owner.contact]` cria ou insere o objeto de contato aninhado. Os objetos intermediários não precisam ter cabeçalhos separados. Sua existência decorre dos segmentos de caminho no cabeçalho.

As atribuições antes de qualquer cabeçalho permanecem na raiz. As tabelas posteriores não as movem retroativamente. Ao revisar JSON convertido, siga o caminho completo da propriedade em vez da distância física entre as linhas: a tabela atual de TOML permanece ativa até que outro cabeçalho a altere.

[[matriz de tabelas]] — por que um cabeçalho repetido com colchetes duplos anexa objetos a uma matriz e a ordem que ele preserva

Um cabeçalho com colchetes duplos anexa uma tabela a um array. Duas seções `[[server]]` tornam-se `server: [{...},{...}]` na ordem de origem. Os campos sob cada cabeçalho pertencem a esse membro da matriz até que outro cabeçalho comece, tornando a configuração repetida explícita em JSON.

A ordem dentro da matriz são dados e são preservados. A apresentação da chave do objeto pode ser classificada posteriormente quando a opção é selecionada, mas os membros da matriz nunca são reordenados. Confundir os dois mudaria a prioridade do servidor ou a sequência do plug-in, em vez de apenas formatar um documento.

Chaves pontilhadas e tabelas embutidas — a.b = 1 e { x = 1 } como mais duas maneiras de expressar o mesmo aninhamento

As atribuições pontilhadas fornecem outra notação de caminho: `a.b.c = true` produz o mesmo formato de objeto aninhado que os cabeçalhos de tabela correspondentes. Tabelas embutidas como `point = { x = 1, y = 2 }` tornam-se objetos aninhados imediatamente. Esses formulários podem descrever árvores semelhantes, embora pareçam muito diferentes para um revisor.

JSON registra apenas as chaves e valores resultantes, não qual notação TOML os criou. A conversão reversa, portanto, não pode restaurar a escolha original entre cabeçalhos, chaves pontilhadas e tabelas embutidas. O gravador TOML escolhe sua própria serialização válida na árvore.

Tipos que são transferidos e tipos que não são — inteiros, flutuantes, booleanos e strings são mapeados diretamente; data-hora tornam-se strings e JSON null não tem fonte TOML

Strings, inteiros seguros, floats, booleanos, arrays e tabelas são mapeados diretamente. Os quatro tipos temporais de TOML não: deslocamento de data e hora, data e hora local, data local e hora local se tornam suas strings de origem semelhantes a RFC 3339, e um aviso nomeia cada caminho e tipo. Posteriormente, o escritor cita essas strings em vez de recriar tokens de data e hora.

Os números inteiros assinados de 64 bits de TOML podem exceder o intervalo de números inteiros seguros de JavaScript. smol-toml retorna valores como BigInt quando necessário; ToolAcre converte-os em strings decimais e avisa em vez de arredondar os dígitos. Isso preserva a ortografia ao custo de alterar o tipo JSON.

Exemplo resolvido: uma lista pyproject.toml — [projeto], [project.optional-dependências] e uma lista [[tool.plugins]] convertida em JSON com cada nível rastreado

Experimente `name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]` e, em seguida, duas tabelas `[[tool.plugins]]` com nomes distintos. JSON coloca o nome na raiz, aninha o projeto e o opcional e produz um array de plugins abaixo da ferramenta.

Adicione `released = 1979-05-27` e `huge = 9223372036854775807`. A primeira passa a ser a string `1979-05-27`; o segundo se torna uma string decimal. Ambos os avisos identificam os caminhos alterados, tornando os tipos não JSON revisáveis ​​em vez de permitir coerção silenciosa de data ou número.

O que isso não cobre - conversão de JSON de volta para TOML idiomático com agrupamento de cabeçalho sensato, que envolve escolhas de estilo que nenhuma regra determina totalmente

JSON-to-TOML é compatível com um objeto raiz, mas não recria escolhas ou comentários idiomáticos do autor. Chaves com valor nulo são omitidas; null dentro de um array se torna uma string vazia para preservar posições. Um array raiz, escalar ou nulo é recusado porque um documento TOML deve ser uma tabela.

Esse comportamento corrige a implicação do esboço de que a conversão reversa está fora do escopo. O conversor grava TOML, mas a fidelidade do estilo está fora de sua promessa. A distinção é importante: a serialização suportada não é o mesmo que restaurar o arquivo de origem byte por byte ou escolher o layout que um mantenedor preferiria.

Escrever JSON de volta para TOML é suportado, mas comentários, tipos de data e hora e estilo autoral não retornam

Leia os cabeçalhos TOML como caminhos e colchetes duplos como operações de acréscimo. A visualização JSON é valiosa para rastrear a árvore resultante, enquanto os avisos expõem datas e números inteiros largos que cruzam um limite de tipo. Não chame a operação sem perdas quando um dos avisos aparecer.

Para migração de configuração, mantenha o original ao lado da saída convertida. Verifique os valores primeiro e depois edite a organização TOML para leitores e a ferramenta de destino. Os conversores de sintaxe executam a etapa mecânica de análise e gravação; ele não pode decidir o agrupamento específico do projeto, as chaves aceitas ou se o aplicativo suporta esse arquivo.

Uma comparação final deve separar três questões que são fáceis de confundir. Primeiro, os valores analisados ​​sobreviveram? Em segundo lugar, algum tipo somente TOML se tornou uma string JSON ou qualquer nulo desapareceu? Terceiro, o TOML recém-serializado está organizado de uma forma que um mantenedor possa entender? Os dois primeiros podem ser verificados em relação a valores e avisos; o terceiro precisa de uma revisão humana. Manter essas verificações separadas evita que uma serialização tecnicamente válida seja chamada de migração fiel quando seus tipos ou estrutura autoral forem alterados.