Folha de referências do formato TOON

Se você já sentiu que JSON é muito detalhado (todos aqueles colchetes!), mas YAML é um pouco "mágico" e imprevisível, você pode simplesmente se apaixonar por TOON. Este formato atinge um equilíbrio único entre a legibilidade humana e a velocidade de análise da máquina. Ele foi projetado para ser denso, explícito e incrivelmente rápido de analisar.

Esteja você migrando dados ou apenas tentando depurar um arquivo de configuração, esta folha de dicas cobre a sintaxe essencial que você precisa saber.

A filosofia: menos ruído, mais dados

A primeira coisa que você notará é que TOON se parece muito com YAML, mas se comporta estritamente como JSON. Ele dispensa os colchetes de abertura e fechamento em favor do recuo e das novas linhas, fazendo com que seus dados pareçam mais limpos imediatamente.

Objetos e aninhamento

Em JSON, você está acostumado a colocar tudo entre chaves. No TOON, a estrutura está implícita no recuo.

JSON:

{ 
"projeto": { 
"metadados": { 
"nome": "Alfa-Centauri", 
"status": "ativo" 
}, 
"marcos": [ 
{ 
"fase": "projeto", 
"prioridade": 1 
}, 
{ 
"fase": "teste", 
"prioridade": 2 
} 
] 
} 
} 

TOON:

projeto: 
metadados: 
Nome: Alfa-Centauri 
estado: ativo 
marcos[2]{fase,prioridade}: 
projeto,1 
testes,2 

Observe que as chaves não exigem aspas, a menos que contenham caracteres especiais e a hierarquia seja visualmente óbvia.

O poder dos arrays

É aqui que o TOON realmente diverge de outros formatos. TOON exige que você declare o comprimento do array na própria chave. Isso pode parecer estranho à primeira vista, mas permite que o analisador pré-aloque memória, tornando-o extremamente rápido.

Matrizes Primitivas

Para listas simples de strings ou números, TOON usa uma sintaxe compacta separada por vírgulas.

A Sintaxe:

chave[comprimento]:item1,item2,item3 

Se você tiver um array raiz (o arquivo inteiro é apenas uma lista), ficará assim:

Matrizes tabulares (o recurso matador)

Esse é o recurso que geralmente conquista os desenvolvedores. Se você tiver uma matriz de objetos que compartilham as mesmas chaves (como linhas em um banco de dados), TOON permite definir o esquema uma vez no cabeçalho e depois apenas listar os valores. Isso remove grandes quantidades de redundância encontradas em JSON.

A Sintaxe:

chave[linhas]{col1,col2}: 

JSON:

{ 
"inventário": [ 
{ 
"sku": "KB-99", 
"quantidade": 50, 
"corredor": 4, 
"reordenar": falso 
}, 
{ 
"sku": "MS-12", 
"quantidade": 12, 
"corredor": 7, 
"reordenar": verdadeiro 
}, 
{ 
"sku": "MN-44", 
"quantidade": 8, 
"corredor": 2, 
"reordenar": verdadeiro 
} 
] 
} 

TOON:

inventário[3]{sku,quantidade,corredor,reordenar}: 
KB-99,50,4,falso 
MS-12,12,7, verdadeiro 
MN-44,8,2, verdadeiro 

Essa abordagem "CSV-inside-YAML" torna grandes conjuntos de dados incrivelmente legíveis e compactos.

Matrizes mistas e aninhadas

Às vezes, os dados não são uniformes. Se sua matriz contiver diferentes tipos de dados (números misturados com objetos) ou se contiver objetos aninhados complexos, TOON recorrerá a uma sintaxe de estilo de marcador usando hífens.

Você pode até ter arrays dentro de arrays. Observe como o array interno também declara seu comprimento:

Citação: quando usar

Uma das coisas mais legais do TOON é que você raramente precisa de orçamentos. Você pode escrever Olá 世界 👋 sem envolvê-lo em "". No entanto, como o TOON tenta inferir tipos (números, booleanos), existem regras específicas para quando você deve usar aspas.

A lista de "citações obrigatórias"

Você deve colocar sua string entre aspas duplas "" se:

1. Parece um número ou booleano: Se você quiser a string "123" ou "true", coloque-a entre aspas. Caso contrário, eles se tornarão o número 123 e o booleano true.

2. Contém delimitadores: Se sua string tiver uma vírgula , (ou qualquer que seja seu delimitador ativo), coloque-a entre aspas.

3. Possui bordas com espaços em branco: Espaços iniciais ou finais requerem aspas.

4. Contém caracteres especiais: Caracteres como :, ", \, [, ], {, }.

5. Está vazio: Uma string vazia é representada como "".

Exemplos:

Sequências de escape

Mantenha a simplicidade. TOON reconhece apenas cinco sequências de escape dentro de strings. Qualquer outra coisa é inválida.

• \\ (barra invertida)

• \" (aspas duplas)

• \n (nova linha)

• \r (retorno de carro)

• \t (Guia)

Cabeçalhos e delimitadores avançados

E se seus dados estiverem cheios de vírgulas? Você não quer citar todos os campos. TOON permite alterar o delimitador no cabeçalho do array.

Você pode usar um Tab ou um Pipe (|) colocando-o entre colchetes ou colchetes.

Exemplo de delimitador de tubo:

Ao adicionar | no cabeçalho, o analisador sabe que deve procurar barras verticais em vez de vírgulas, mantendo sua sintaxe limpa.

Chave dobrável

Se você tiver um aninhamento profundo, mas apenas um caminho de dados, não será necessário recuar cinco vezes. Você pode usar a notação de ponto (Key Folding) para nivelar sua estrutura.

Aninhamento padrão:

usuário: 
perfil: 
configurações: 
notificações: 
e-mail: verdadeiro 
sms: falso 

Dobrado (Limpador):

user.profile.settings.notificações: 
e-mail: verdadeiro 
sms: falso 

Referência rápida de digitação

TOON mapeia diretamente para tipos JSON, mas lida com casos extremos específicos de JavaScript normalmente para garantir uma saída válida.

• Números: Armazenados como decimais canônicos. 1.0 torna-se 1.

• Infinity / NaN: Tornam-se null (já que JSON não os suporta).

• Datas: Convertido em strings ISO entre aspas.

• Indefinido/Funções: Convertido para null.

• Objetos vazios: Representado como nada (saída vazia).

• Matrizes Vazias: Representado como key[0]:.

TOON é um formato que recompensa a precisão. Pode demorar um pouco para se acostumar a contar os itens do array, mas a recompensa em legibilidade e tamanho do arquivo vale o esforço. Boa codificação!