Foglio informativo in formato TOON

Se hai mai avuto la sensazione che JSON sia troppo prolisso (tutte quelle parentesi graffe!) ma YAML sia un po' troppo "magico" e imprevedibile, potresti innamorarti di TOON. Questo formato raggiunge un equilibrio unico tra leggibilità umana e velocità di analisi della macchina. È progettato per essere denso, esplicito e incredibilmente veloce da analizzare.

Che tu stia eseguendo la migrazione dei dati o semplicemente tentando di eseguire il debug di un file di configurazione, questo cheat sheet copre la sintassi essenziale che devi conoscere.

La filosofia: meno rumore, più dati

La prima cosa che noterai è che TOON assomiglia molto a YAML, ma si comporta strettamente come JSON. Elimina le parentesi graffe di apertura e chiusura a favore del rientro e dei ritorni a capo, rendendo i tuoi dati immediatamente più puliti.

Oggetti e nidificazione

In JSON, sei abituato a racchiudere tutto tra parentesi graffe. In TOON, la struttura è implicita nel rientro.

JSON:

{ 
"progetto": { 
"metadati": { 
"nome": "Alfa-Centauri", 
"stato": "attivo" 
}, 
"pietre miliari": [ 
{ 
"fase": "progettazione", 
"priorità": 1 
}, 
{ 
"fase": "test", 
"priorità": 2 
} 
] 
} 
} 

TOON:

progetto: 
metadati: 
nome: Alfa-Centauri 
stato: attivo 
traguardi[2]{fase,priorità}: 
progettazione,1 
test,2 

Tieni presente che le chiavi non richiedono virgolette a meno che non contengano caratteri speciali e la gerarchia è visivamente ovvia.

Il potere degli array

È qui che TOON si differenzia davvero dagli altri formati. TOON richiede di dichiarare la lunghezza dell'array nella chiave stessa. Ciò potrebbe sembrare strano a prima vista, ma consente al parser di pre-allocare la memoria, rendendola incredibilmente veloce.

Array primitivi

Per semplici elenchi di stringhe o numeri, TOON utilizza una sintassi compatta, separata da virgole.

La sintassi:

chiave[lunghezza]:oggetto1,oggetto2,oggetto3 

Se hai un array root (l'intero file è solo un elenco), assomiglia a questo:

Array tabulari (la funzionalità Killer)

Questa è la caratteristica che di solito conquista gli sviluppatori. Se disponi di un array di oggetti che condividono tutti le stesse chiavi (come le righe in un database), TOON ti consente di definire lo schema once nell'intestazione e quindi elencare semplicemente i valori. Ciò rimuove enormi quantità di ridondanza presenti in JSON.

La sintassi:

chiave[righe]{col1,col2}: 

JSON:

{ 
"inventario": [ 
{ 
"sku": "KB-99", 
"qtà": 50, 
"corridoio": 4, 
"riordinare": falso 
}, 
{ 
"sku": "MS-12", 
"qtà": 12, 
"corridoio": 7, 
"riordinare": vero 
}, 
{ 
"sku": "MN-44", 
"qtà": 8, 
"corridoio": 2, 
"riordinare": vero 
} 
] 
} 

TOON:

inventario[3]{sku,qty,aisle,reorder}: 
KB-99,50,4,falso 
MS-12,12,7,vero 
MN-44,8,2,vero 

Questo approccio "CSV-inside-YAML" rende i set di dati di grandi dimensioni incredibilmente leggibili e compatti.

Array misti e annidati

A volte i dati non sono uniformi. Se l'array contiene diversi tipi di dati (numeri mescolati con oggetti) o se contiene oggetti nidificati complessi, TOON ricorre a una sintassi in stile punto elenco utilizzando i trattini.

Puoi anche avere array all'interno di array. Nota come l'array interno dichiara anche la sua lunghezza:

Citazione: quando usarlo

Una delle cose più belle di TOON è che raramente hai bisogno di virgolette. Puoi scrivere Ciao 世界 ​​👋 senza racchiuderlo in "". Tuttavia, poiché TOON tenta di dedurre tipi (numeri, booleani), esistono regole specifiche per quando devi utilizzare le virgolette.

L'elenco delle "quotazioni obbligatorie".

È necessario racchiudere la stringa tra virgolette doppie "" se:

1. Sembra un numero o un valore booleano: Se desideri la stringa "123" o "true", virgolettala. Altrimenti diventano il numero "123" e il valore booleano "true".

2. Contiene delimitatori: Se la tua stringa ha una virgola , (o qualunque sia il tuo delimitatore attivo), virgolettala.

3. Ha bordi di spazi bianchi: Gli spazi iniziali o finali richiedono virgolette.

4. Contiene caratteri speciali: Caratteri come :, ", \, [, ], {, }.

5. È vuoto: Una stringa vuota è rappresentata come "".

Esempi:

Sequenze di fuga

Mantienilo semplice. TOON riconosce solo cinque sequenze di escape all'interno delle stringhe. Qualsiasi altra cosa non è valida.

• \\ (barra rovesciata)

• \" (virgolette doppie)

• \n (nuova riga)

• \r (Ritorno a capo)

• \t (Tabulazione)

Intestazioni e delimitatori avanzati

Cosa succede se i tuoi dati sono pieni di virgole? Non vuoi citare ogni singolo campo. TOON ti consente di modificare il delimitatore nell'intestazione dell'array.

Puoi utilizzare una Tab o una Pipe (|) posizionandola tra parentesi graffe.

Esempio di delimitatore di tubo:

Aggiungendo | nell'intestazione, il parser sa di cercare pipe anziché virgole, mantenendo pulita la sintassi.

Piegatura delle chiavi

Se si dispone di un annidamento profondo ma di un solo percorso di dati, non è necessario rientrare cinque volte. Puoi utilizzare la notazione punto (Key Folding) per appiattire la struttura.

Nidificazione standard:

utente: 
profilo: 
impostazioni: 
notifiche: 
e-mail: vero 
sms: falso 

Piegato (Pulizia):

utente.profilo.impostazioni.notificazioni: 
e-mail: vero 
sms: falso 

Riferimento rapido al tipo

TOON esegue la mappatura direttamente sui tipi JSON, ma gestisce con garbo i casi limite specifici di JavaScript per garantire un output valido.

• Numeri: memorizzati come decimali canonici. "1.0" diventa "1".

• Infinity / NaN: Questi diventano null (poiché JSON non li supporta).

• Date: Convertite in stringhe ISO tra virgolette.

• Non definito/Funzioni: Convertito in null.

• Oggetti vuoti: rappresentati come nulla (output vuoto).

• Array vuoti: rappresentati come key[0]:.

TOON è un formato che premia la precisione. Potrebbe volerci un po' di tempo per abituarsi a contare gli elementi dell'array, ma il risultato in termini di leggibilità e dimensione del file vale la pena. Buona programmazione!