A primeira vez que o TOML me mordeu, não foi a sintaxe Era a ordenação Eu tinha um objeto de configurações JSON de um antigo serviço Node, EU queria isso como um config.toml para uma reescrita de Rust, e EU fiz o que todo mundo faz da primeira vez: EU digitei as mesas à mão Dez minutos depois o analisador estava jogando um erro que EU não entendi, apontando para uma linha que parecia perfeitamente bem O problema era três teclas sentadas abaixo de a [table] cabeçalho que pertencia acima dele TOML tem uma regra que JSON não tem, e uma vez que você tropeça nele você nunca esquece.
eu construo Toolz.dev, e EU enviei uma longa prateleira de conversores de formato lá, então EU escrevi o conversor JSON para TOML para remover toda essa categoria de erro Você cola JSON, você obtém TOML que re-analisa para os mesmos dados, e a ordem é tratada para você Este guia é a coisa que EU gostaria de ter lido naquela tarde: o que TOML é, onde JSON e TOML discordam, e como converter entre eles sem perder nada que você se importasse.
tl;dr: TOML é um formato de configuração digitado usado por Cargo, Poetry, Hugo e muitas ferramentas Rust and Go. A conversão de JSON para TOML é principalmente mecânica, mas três coisas precisam de julgamento: ordenação de tabelas (chaves antes de subtabelas, sempre), como você escreve matrizes de objetos (matrizes de tabelas versus tabelas embutidas) e o que acontece com JSON
null, que TOML não tem como expressar. O Conversor JSON para TOML torna todos os três explícitos e é executado inteiramente no seu navegador.
O que é TOML e por que eu converteria JSON nele?
TOML significa Tom' s Obvious, Minimal Language Ele se lê como um arquivo INI antigo, mas ao contrário do INI tem uma especificação real com valores digitados, datas de primeira classe e uma gramática definida Essa especificação é a razão pela qual ganhou: um formato de configuração que uma pessoa pode ler de relance, que uma máquina analisa da mesma maneira todas as vezes, sem ambiguidade sobre se port = 8080 é uma string ou um número. É um número, porque TOML diz isso.
Você alcança a conversão JSON para TOML quando uma máquina lhe deu JSON e uma ferramenta quer TOML Isso acontece mais do que você pensaria Uma API retorna um blob de configurações como JSON e você precisa dele em pyproject.toml. Você tem um velho config.json e você está movendo o projeto para uma pilha que lê config.toml. Você gerou alguns dados programaticamente, eles saíram como JSON porque é isso JSON.stringify produz, e o consumidor é Cargo ou Hugo ou um serviço Go usando uma biblioteca TOML Em todos os casos os dados são idênticos Apenas a serialização difere.
A direção inversa também existe, mas é um trabalho diferente Se você está indo para o outro lado, o formatador json vale a pena ter aberto para sanidade-verificar o JSON primeiro, e o Conversor JSON para YAML abrange o outro formato de configuração comum Este guia é sobre JSON entrando em TOML.
Como o conversor mapeia JSON em TOML?
Há apenas um punhado de formas em JSON, e cada um tem uma casa em TOML Entender o mapeamento é a maior parte da compreensão da ferramenta.
UM JSON objeto torna-se um TOML tabela. O objeto de nível superior é a tabela raiz, e é por isso que o conversor insiste que a entrada seja um objeto Objetos aninhados se tornam [table] cabeçalhos com caminho pontilhado, então { "database": { "pool": { "max": 10 } } } torna-se um [database.pool] seção com max = 10 dentro dele.
UM JSON matriz de objetos torna-se um TOML matriz de tabelas, escrito com o suporte duplo [[name]] cabeçalho, um bloco por elemento Este é o padrão TOML idiomático para uma lista de registros: uma lista de servidores, uma lista de dependências, uma lista de alvos de construção Cada elemento obtém o seu próprio [[servers]] bloquear.
Cada escalar mapeia diretamente Uma string JSON se torna uma string básica TOML entre aspas duplas, com caracteres de controle escapados Um número JSON se torna um inteiro TOML se for um número inteiro e um float caso contrário Um booleano JSON se torna true ou false. Estes são os casos fáceis, e o conversor nunca os erra.
UM JSON matriz de escalares torna-se uma matriz em linha TOML: ["admin", "editor"] fica ["admin", "editor"]. Matrizes mistas e matrizes aninhadas também são escritas em linha, porque esse é o único lugar onde elas se encaixam.
Por que a ordenação de chaves é tão importante no TOML?
Esta é a regra que pega todos, por isso vale a pena afirmar claramente Em TOML, dentro de qualquer tabela, todos esses tabela' s próprios pares chave/valor deve aparecer antes de qualquer um dos seus cabeçalhos sub-tabela Se você escrever um [server] cabeçalho, em seguida, algumas chaves, em seguida, outra chave que pertence à tabela raiz, o analisador lê essa chave perdida como parte de [server] em vez disso. O melhor caso é que ele cai no lugar errado; o pior caso é que o arquivo não consegue analisar.
JSON não tem tal regra Em JSON, a ordem das chaves nem é significativa, e objetos e escalares se misturam livremente dentro dos mesmos aparelhos, Então uma conversão JSON-para-TOML ingênua que anda o objeto em ordem de inserção e emite cada chave como ele vai produzir TOML quebrado no momento em que um escalar segue um objeto aninhado.
O conversor resolve isso fazendo duas passagens sobre cada tabela Primeiro ele emite todas as chaves simples, os escalares e matrizes inline Só então ele emite os cabeçalhos sub-table e array-of-tables, recursando em cada um Sua ordem de chave é preservada dentro de cada grupo, que é o que você quer, mas o rearranjo necessário entre os dois grupos acontece automaticamente Você nunca tem que pensar sobre isso, e você nunca recebe o erro que EU tenho.
Quando matrizes de objetos devem ser tabelas versus inline?
Aqui está a única escolha genuína. Uma matriz de objetos pode ser escrita de duas maneiras em TOML e ambos são válidos.
O primeiro é um matriz de tabelas, a forma de colchete duplo É prolixo e legível, um bloco por registro, e é o que a maioria dos TOML na natureza se parece Se você viu um Cargo.toml com vários [[bin]] entradas, você viu isso.
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
O segundo é um tabela inline dentro de uma matriz normal, que coloca cada objeto em uma linha.
servers = [
{ name = "web", ip = "10.0.0.1" },
{ name = "api", ip = "10.0.0.2" },
]
Ambos ida e volta para os mesmos dados Qual deles você quer depende do alvo e do gosto Matrizes de tabelas ler melhor para registros um humano vai editar, e eles são a convenção para a maioria das ferramentas de configuração As tabelas inline são mais compactas e mais próximas da forma do JSON original, que algumas pessoas preferem quando a lista é curta ou os objetos são minúsculos O conversor padrão para matrizes de tabelas e dá-lhe um alternador para alternar Se você não tem certeza, deixe-o no padrão: é como um arquivo TOML geralmente se parece.
O que acontece com JSON null em TOML?
TOML não tem nulo Não há palavra-chave, nenhum valor vazio, nada Esta é uma decisão de design deliberada pelo formato, e é o único lugar onde JSON to TOML é genuinamente com perdas.
Então o conversor tem que fazer uma escolha, e ele permite que você faça Por padrão, uma chave cujo valor é null é descartado, e a ferramenta lista as teclas descartadas em uma nota sob a saída para que nada desapareça silenciosamente Se você preferir manter a tecla, você pode mudar para escrever nulo como uma string vazia, que preserva a tecla ao custo de alterar seu tipo Nenhum dos dois é perfeito, porque não há resposta perfeita O que importa é que a escolha é visível em vez de enterrada.
Nulos dentro de matrizes são sempre descartados, com um aviso, porque uma matriz TOML não pode conter nulo em tudo Se o seu JSON tem [1, null, 3], o TOML será [1, 3] e a ferramenta dirá que removeu um. Se esses nulos tiverem significado, isso é um sinal para remodelar os dados antes da conversão e não depois.
Por que meu número perdeu seu decimal, ou ganhou um?
Este surpreende as pessoas que se preocupam com os tipos JSON não distingue 5 desde 5.0. Ambos analisam o mesmo IEEE 754 duplo e na época JSON.parse é feito não há nenhum traço do zero à direita Assim quando o conversor vê o número 5, não tem como saber que você quis dizer um carro alegórico, e desde então 5 é um número inteiro que escreve um número inteiro TOML.
TOML, por outro lado, distingue inteiros de flutuadores, e algumas ferramentas se preocupam com a diferença. Se você precisar de um valor digitado como float, a correção é dar-lhe uma parte fracionária na fonte, 5.1 ou 5.0 escrito de uma forma que sobrevive, ou para editar o valor único após a conversão É uma mudança de um caractere e é raro, mas vale a pena saber por que isso acontece em vez de assumir que o conversor está errado Não é errado JSON simplesmente jogou a informação fora antes que o conversor nunca viu.
O caso inverso aparece com números muito grandes ou muito pequenos, onde JavaScript's String() produz notação de expoente como 1e+21. TOML aceita isso como um float, então ele converte bem, mas a forma do número pode parecer diferente do que você digitou Novamente, o valor é idêntico; apenas a renderização mudou.
Como funcionam as chaves nuas e citadas?
TOML deixa uma chave ser escrita nua se for feita apenas de letras, dígitos, sublinhados e traços Qualquer outra coisa, uma chave com um ponto, um espaço, uma barra, um caractere Unicode, tem que ser citado O conversor verifica cada chave e cita apenas as que precisam, então user-name fica nu e "user.name" obtém aspas para impedir que o ponto seja lido como um caminho de tabela Você não precisa pensar sobre isso, mas se você vir aspas em torno de uma chave na saída, é por isso: a chave continha um caractere que, de outra forma, mudaria seu significado.
Um exemplo trabalhado
Aqui está a amostra que a ferramenta carrega, para que você possa ver todas as regras de uma só vez. O JSON:
{
"title": "Toolz config",
"version": 2,
"enabled": true,
"owner": { "name": "Liton", "roles": ["admin", "editor"] },
"database": { "host": "localhost", "port": 5432, "pool": { "min": 2, "max": 10 } },
"servers": [
{ "name": "web", "ip": "10.0.0.1" },
{ "name": "api", "ip": "10.0.0.2" }
]
}
torna-se TOML onde os escalares raiz vêm primeiro, os objetos aninhados tornam-se tabelas pontilhadas em ordem e a matriz de servidores torna-se duas [[servers]] blocos:
title = "Toolz config"
version = 2
enabled = true
[owner]
name = "Liton"
roles = ["admin", "editor"]
[database]
host = "localhost"
port = 5432
[database.pool]
min = 2
max = 10
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
Reparem que title, version e enabled são escritos antes de qualquer cabeçalho roles permanece uma matriz inline porque é uma matriz de strings e [database.pool] senta-se sob [database] como um caminho pontilhado Cada regra neste guia é visível em nove linhas de saída.
Qual ferramenta para qual conversão?
TOML é um formato em uma família, e a ferramenta certa depende de onde você está começando e terminando Aqui está como EU penso sobre isso.
| Você tem | você quer | usar |
|---|---|---|
| JSON | Configuração TOML | JSON para TOML |
| JSON | Configuração YAML | json para yaml |
| yaml | JSON | YAML para JSON |
| JSON | xml | json para xml |
| Messy JSON | JSON legível | formatador json |
O padrão é que os formatos de configuração são visualizações intercambiáveis dos mesmos dados, e o conversor que você deseja é nomeado para a direção que você está indo. TOML, YAML e JSON expressam dados de chave/valor aninhados; a diferença é qual ferramenta de destino lê.
É seguro converter um arquivo de configuração online?
Configurar arquivos é exatamente o tipo de coisa que você deve ter cuidado ao colar em um site, porque eles geralmente contêm cadeias de conexão, tokens e outros segredos O Conversor JSON para TOML é executado inteiramente no seu navegador O JSON que você cola é analisado na memória do seu dispositivo, o TOML é produzido lá, e nada é enviado para um servidor, escrito em um log, ou armazenado Você pode assistir isso sozinho: abra sua guia de rede, executar uma conversão, e ver que nenhuma solicitação sai Ele também continua trabalhando sem conexão uma vez que a página tenha carregado, que é a prova prática de que o trabalho é local Se você se preocupa com onde seus dados vão, e com um arquivo de configuração que você deve, esta é a propriedade que importa É o mesmo princípio por trás de cada ferramenta no site, e a razão pela qual EU escrevi sobre isso longamente na nota em Privacidade de dados em ferramentas online.
Onde isso se encaixa em um fluxo de trabalho real
A conversão de formato raramente é toda a tarefa É um passo Você puxa um objeto de configurações de uma API, você converte, você o solta em um projeto O valor de um conversor do lado do cliente é que ele se encaixa nesse fluxo sem atrito: sem upload, sem conta, sem esperar em um servidor, sem se perguntar se seus segredos estão agora em logs de alguém' s. Essa é a mesma razão pela qual EU mantenho o todo Toolz.dev defina o lado do cliente e é um tema ao qual volto no Ferramentas de produtividade do desenvolve escreva, porque as ferramentas que você alcança vinte vezes ao dia são aquelas onde uma viagem de ida e volta de dois segundos e uma questão de privacidade se somam.
TOML ganhou seu lugar nesse fluxo por ser chato da melhor maneira Ele analisa o mesmo em todos os lugares, ele lê bem, e sua única aresta nítida, a regra de ordenação, é exatamente o tipo de coisa que um conversor deve arquivar para você Cole seu JSON, escolha como você quer arrays e nulos tratados e copie TOML que apenas funciona.
Perguntas frequentes
Como faço para converter JSON para TOML?
Cole seu objeto JSON no conversor e clique em Converter. A ferramenta serializa objetos em tabelas TOML, matrizes de objetos em matrizes de tabelas e todos os outros valores embutidos e, em seguida, fornece TOML padrão para cópia. O JSON de nível superior deve ser um objeto, porque um documento TOML é sempre uma tabela.
Para que é utilizado o TOML?
TOML é um formato de arquivo de configuração projetado para ser fácil de ler e inequívoco de analisar É o formato de configuração para Rust' s Cargo (Cargo.toml), Python packaging (pyproject.toml), Hugo, e muitas ferramentas Go e Rust As pessoas convertem JSON para TOML para entregar uma configuração gerada por máquina para uma ferramenta que espera TOML.
O que acontece com os valores nulos JSON no TOML?
TOML não tem nenhum tipo nulo, então um nulo JSON não pode ser representado diretamente Por padrão este conversor deixa cair chaves nulas e adiciona uma nota listando-as; você pode mudar para gravá-las como strings vazias em vez disso Nulos dentro de arrays são sempre descartados, porque uma matriz TOML não pode conter nulo.
Qual é a diferença entre uma matriz de tabelas e uma tabela inline?
Uma matriz de tabelas usa cabeçalhos repetidos de colchetes duplos, um bloco por registro, e é a maneira TOML idiomática de escrever uma lista de objetos, como uma lista de servidores ou dependências Uma tabela inline embala um objeto em uma linha como um conjunto de chaves é igual a pares de valores em chaves Esta ferramenta padrão para matrizes de tabelas, mas permite escolher inline em vez disso.
Por que meu número JSON 5.0 se tornou 5 no TOML?
JSON não preserva a diferença entre 5 e 5.0, então a análise lê ambos como o número 5. já que 5 é um número inteiro, o conversor escreve como um inteiro TOML Se você precisar digitado como um float, adicione uma parte fracionária na fonte ou edite o valor único após a conversão.
O conversor mantém minha ordem de chaves?
Sim. As chaves são emitidas na ordem em que aparecem no JSON, com um rearranjo necessário: dentro de cada tabela, as chaves simples são escritas antes de qualquer subtabela ou cabeçalhos de matriz de tabelas. Essa é uma regra de sintaxe TOML, não uma escolha de reordenação, e sem ela o arquivo não analisaria.
Meu JSON foi carregado em um servidor?
Não. Toda a conversão acontece em seu navegador usando JavaScript simples. Seu JSON, incluindo quaisquer segredos ou credenciais em um arquivo de configuração, nunca é transmitido, registrado ou armazenado, e o conversor continua funcionando sem conexão depois que a página é carregada.
Por que diz que o nível superior deve ser um objeto?
Um documento TOML é definido como uma tabela, o que significa que ele deve começar a partir de um conjunto de pares chave/valor Uma matriz JSON nu ou escalar não tem tabela para mapear Em um objeto primeiro, por exemplo, colocando sua matriz sob uma chave nomeada, e ele vai converter.
