La prima volta che TOML mi ha morso, non era la sintassi Era l'ordinamento Avevo un oggetto JSON settings da un vecchio servizio Node, lo volevo come un config.toml per una riscrittura di Rust, e ho fatto quello che fanno tutti la prima volta: ho digitato a mano i tavoli Dieci minuti dopo il parser stava lanciando un errore che non capivo, indicando una linea che sembrava perfettamente a posto Il problema erano tre tasti seduti sotto a [table] intestazione che apparteneva sopra di essa TOML ha una regola che JSON non ha, e una volta che ci si inciampa non lo si dimentica mai.
io costruisco Toolz.dev, e ho spedito lì un lungo scaffale di convertitori di formato, quindi ho scritto il convertitore da JSON a TOML per rimuovere tutta quella categoria di errore Incolli JSON, ottieni TOML che si ri-analizza sugli stessi dati e l'ordine viene gestito per te Questa guida è la cosa che vorrei aver letto quel pomeriggio: cos'è TOML, dove JSON e TOML non sono d'accordo e come convertire tra loro senza perdere nulla di cui ti importasse.
tl; dr: TOML è un formato di configurazione digitato utilizzato da Cargo, Poetry, Hugo e molti strumenti Rust and Go. Convertire JSON in TOML è per lo più meccanico, ma tre cose necessitano di giudizio: l'ordinamento delle tabelle (chiavi prima delle sottotabelle, sempre), il modo in cui si scrivono array di oggetti (array di tabelle contro tabelle in linea) e cosa succede a JSON
null, che TOML non ha modo di esprimere Il Convertitore da JSON a TOML rende tutti e tre espliciti e viene eseguito interamente nel browser.
Cos'è TOML, e perché dovrei convertirci JSON?
TOML sta per Tom's Obvious, Minimal Language Si legge come un vecchio file INI, ma a differenza di INI ha una specifica reale con valori digitati, date di prima classe e una grammatica definita Quella specifica è la ragione per cui ha vinto: un formato di configurazione che una persona può leggere a colpo d'occhio, che una macchina analizza ogni volta allo stesso modo, senza ambiguità sul fatto che port = 8080 è una stringa o un numero È un numero, perché TOML lo dice.
Si raggiunge per la conversione da JSON a TOML quando una macchina ti ha dato JSON e uno strumento vuole TOML Che succede più di quanto si potrebbe pensare Un'API restituisce un blob impostazioni come JSON e ne hai bisogno in pyproject.toml. Hai un vecchio config.json e stai spostando il progetto in uno stack che recita config.toml. Hai generato alcuni dati a livello di programmazione, sono usciti come JSON perché questo è ciò che JSON.stringify produce, e il consumatore è Cargo o Hugo o un servizio Go utilizzando una libreria TOML In ogni caso i dati sono identici Solo la serializzazione differisce.
Esiste anche la direzione opposta, ma è un lavoro diverso Se stai andando dall'altra parte, il Formattatore JSON vale la pena aprire per controllare la sanità mentale prima il JSON e il Convertitore JSON a YAML copre l'altro formato di configurazione comune Questa guida riguarda JSON che entra in TOML.
Come fa il convertitore a mappare JSON su TOML?
Ci sono solo una manciata di forme in JSON, e ognuno ha una casa in TOML Comprendere la mappatura è la maggior parte della comprensione dello strumento.
UN JSON oggetto diventa un TOML tavolo. L'oggetto di primo livello è la tabella radice, motivo per cui il convertitore insiste che l'input sia un oggetto Gli oggetti nidificati diventano [table] intestazioni con un percorso tratteggiato, quindi { "database": { "pool": { "max": 10 } } } diventa un [database.pool] sezione con max = 10 dentro di esso.
UN JSON schiera di oggetti diventa un TOML array di tabelle, scritto con la doppia parentesi [[name]] header, un blocco per elemento Questo è il modello TOML idiomatico per un elenco di record: un elenco di server, un elenco di dipendenze, un elenco di build target Ogni elemento ottiene il proprio [[servers]] blocco.
Ogni scalare mappa direttamente Una stringa JSON diventa una stringa di base TOML tra virgolette doppie, con i caratteri di controllo sfuggiti Un numero JSON diventa un numero intero TOML se è un numero intero e un float altrimenti Un booleano JSON diventa true oppure false. Questi sono i casi facili, e il convertitore non li sbaglia mai.
UN JSON array di scalari diventa un array in linea TOML: ["admin", "editor"] soggiorni ["admin", "editor"]. Anche gli array misti e gli array nidificati vengono scritti in linea, perché è l'unico posto in cui si adattano.
Perché l'ordinamento delle chiavi è così importante in TOML?
Questa è la regola che cattura tutti, quindi vale la pena di affermare chiaramente In TOML, all'interno di qualsiasi tabella, tutte quelle coppie chiave/valore di table's devono apparire prima di qualsiasi delle sue intestazioni di sotto-tabella Se si scrive un [server] intestazione, poi alcuni tasti, poi un altro tasto che appartiene alla tabella radice, il parser legge quel tasto vagante come parte di [server] invece. Nel caso migliore finisce nel posto sbagliato; nel caso peggiore il file non riesce ad analizzare.
JSON non ha una regola del genere In JSON, l'ordine delle chiavi non è nemmeno significativo e oggetti e scalari si mescolano liberamente all'interno delle stesse parentesi graffe Quindi un'ingenua conversione da JSON a TOML che cammina sull'oggetto in ordine di inserimento ed emette ogni chiave man mano che procede produrrà TOML rotto nel momento in cui uno scalare segue un oggetto annidato.
Il convertitore risolve questo facendo due passaggi su ogni tabella Prima emette tutte le chiavi semplici, gli scalari e gli array in linea Solo allora emette le intestazioni della sotto-tabella e dell'array di tabelle, ricorrendo in ciascuna Il tuo ordine chiave è conservato all'interno di ogni gruppo, che è quello che vuoi, ma il riarrangiamento richiesto tra i due gruppi avviene automaticamente Non devi mai pensarci, e non ricevi mai l'errore che ho ricevuto.
Quando gli array di oggetti dovrebbero essere tabelle rispetto a inline?
Ecco l'unica scelta genuina Una matrice di oggetti può essere scritta in due modi in TOML, ed entrambi sono validi.
Il primo è un array di tabelle, la forma a doppia parentesi È prolisso e leggibile, un blocco per record, ed è come appare la maggior parte del TOML in natura Se hai visto un Cargo.toml con diversi [[bin]] voci, avete visto questo.
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
Il secondo è un tabella inline all'interno di un normale array, che racchiude ogni oggetto su una riga.
servers = [
{ name = "web", ip = "10.0.0.1" },
{ name = "api", ip = "10.0.0.2" },
]
Entrambi girano-viaggio agli stessi dati Quale vuoi dipende dal target e dal gusto Gli array di tabelle leggono meglio per i record che un essere umano modificherà, e sono la convenzione per la maggior parte della configurazione degli strumenti Le tabelle in linea sono più compatte e più vicine alla forma del JSON originale, che alcune persone preferiscono quando l'elenco è breve o gli oggetti sono minuscoli Il convertitore è predefinito per array di tabelle e ti dà un interruttore per cambiare Se non sei sicuro, lascialo sul predefinito: è come appare solitamente un file TOML.
Cosa succede a JSON null in TOML?
TOML non ha null Non c'è parola chiave, nessun valore vuoto, niente Questa è una decisione di progettazione deliberata dal formato, ed è l'unico posto in cui JSON a TOML è genuinamente lossy.
Quindi il convertitore deve fare una scelta e ti consente di farlo. Per impostazione predefinita, una chiave il cui valore è null viene eliminato, e lo strumento elenca i tasti eliminati in una nota sotto l'output quindi nulla scompare silenziosamente, se preferisci tenere il tasto, puoi passare alla scrittura null come stringa vuota, che preserva il tasto a costo di cambiarne il tipo Nessuno dei due è perfetto, perché non c'è una risposta perfetta Ciò che conta è che la scelta sia visibile piuttosto che sepolta.
I nulli all'interno degli array vengono sempre eliminati, con un avviso, perché un array TOML non può contenere affatto null Se il tuo JSON ha [1, null, 3], il TOML sarà [1, 3] e lo strumento ti dirà che ne ha rimosso uno. Se questi nulli hanno un significato, questo è un segnale per rimodellare i dati prima della conversione anziché dopo.
Perché il mio numero ha perso il decimale, o ne ha guadagnato uno?
Questo sorprende le persone che si preoccupano dei tipi JSON non distingue 5 a 5.0. Entrambi si analizzano sullo stesso doppio IEEE 754 e per il tempo JSON.parse è fatto non c'è traccia dello zero finale Quindi quando il convertitore vede il numero 5, non ha modo di sapere che intendevi un carro, e da allora 5 è un numero intero che scrive un numero intero TOML.
TOML, d'altra parte, distingue gli interi dai float e alcuni strumenti si preoccupano della differenza. Se hai bisogno di un valore digitato come float, la correzione è dargli una parte frazionaria nel source, 5.1 oppure 5.0 scritto in un modo che sopravvive, o per modificare il singolo valore dopo la conversione È un cambiamento di un carattere ed è raro, ma vale la pena sapere perché accade piuttosto che dare per scontato che il convertitore sia sbagliato Non è sbagliato JSON ha semplicemente buttato via le informazioni prima che il convertitore le vedesse mai.
Il caso inverso si presenta con numeri molto grandi o molto piccoli, dove JavaScript' s String() produce notazione esponenziale come 1e+21. TOML lo accetta come float, quindi si converte bene, ma la forma del numero potrebbe apparire diversa da quella digitata Ancora una volta, il valore è identico; è cambiato solo il rendering.
Come funzionano le chiavi nude e quotate?
TOML lascia che una chiave sia scritta nuda se è fatta solo di lettere, cifre, trattini bassi e trattini, qualsiasi altra cosa, una chiave con un punto, uno spazio, una barra, un carattere Unicode, deve essere citata Il convertitore controlla ogni chiave e cita solo quelle che ne hanno bisogno, quindi user-name rimane spoglio e "user.name" ottiene virgolette per impedire che il punto venga letto come un percorso della tabella Non devi pensare a questo, ma se vedi virgolette attorno a una chiave nell'output, ecco perché: la chiave conteneva un carattere che altrimenti ne avrebbe cambiato il significato.
Un esempio lavorato
Ecco il campione caricato dallo strumento, in modo da poter vedere ogni regola contemporaneamente Il 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" }
]
}
diventa TOML dove gli scalari root vengono prima, gli oggetti nidificati diventano tabelle tratteggiate in ordine e l'array di server diventa due [[servers]] blocchi:
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"
Notate che title, version e enabled sono scritti prima di qualsiasi intestazione, roles rimane un array in linea perché è un array di stringhe e [database.pool] si siede sotto [database] come percorso tratteggiato Ogni regola in questa guida è visibile in nove linee di output.
Quale strumento per quale conversione?
TOML è un formato in una famiglia, e lo strumento giusto dipende da dove si sta iniziando e finendo Ecco come ci penso.
| Hai | VUOI | maneggiare |
|---|---|---|
| json | Configurazione TOML | JSON a TOML |
| json | Configurazione YAML | JSON a Yaml |
| igname | json | YAML a JSON |
| json | XML | JSON a XML |
| Messy JSON | Leggibile JSON | Formattatore JSON |
Il modello è che i formati di configurazione sono viste intercambiabili degli stessi dati e il convertitore che desideri prende il nome dalla direzione in cui stai andando TOML, YAML e JSON esprimono tutti dati chiave/valore nidificati; la differenza è quale legge il tuo strumento di destinazione.
È sicuro convertire un file di configurazione online?
I file di configurazione sono esattamente il tipo di cose che dovresti fare attenzione a incollare in un sito web, perché spesso contengono stringhe di connessione, token e altri segreti Il Convertitore da JSON a TOML funziona interamente nel tuo browser Il JSON che incolli viene analizzato in memoria sul tuo dispositivo, il TOML viene prodotto lì e non viene inviato nulla a un server, scritto su un registro o archiviato Puoi guardarlo tu stesso: apri la scheda di rete, esegui una conversione e vedi che nessuna richiesta viene eseguita Continua inoltre a funzionare senza connessione una volta caricata la pagina, che è la prova pratica che il lavoro è locale Se ti interessa dove vanno i tuoi dati e con un file di configurazione dovresti, questa è la proprietà che conta È lo stesso principio dietro ogni strumento sul sito e il motivo per cui ne ho scritto a lungo nella nota su Privacy dei dati negli strumenti online.
Dove questo si inserisce in un flusso di lavoro reale
La conversione del formato è raramente l'intero compito È un passo Tiri fuori un oggetto delle impostazioni da un'API, lo converti, lo lasci cadere in un progetto Il valore di un convertitore lato client è che si inserisce in quel flusso senza attriti: nessun caricamento, nessun account, nessuna attesa su un server, nessuna domanda se i tuoi segreti sono ora in qualcuno's registri Questo è lo stesso motivo per cui mantengo il tutto Toolz.dev imposta il lato client ed è un tema a cui torno nel Strumenti di produttività per sviluppatori scrivi, perché gli strumenti che raggiungi per venti volte al giorno sono quelli in cui si sommano un viaggio di andata e ritorno di due secondi e una domanda sulla privacy.
TOML si è guadagnato il suo posto in quel flusso essendo noioso nel modo migliore Analizza lo stesso ovunque, legge bene, e il suo unico bordo tagliente, la regola di ordinazione, è esattamente il genere di cose che un convertitore dovrebbe archiviare per te Incolla il tuo JSON, scegli come vuoi che array e nulli siano gestiti e copia TOML che funzioni e basta.
Domande frequenti
Come faccio a convertire JSON in TOML?
Incolla il tuo oggetto JSON nel convertitore e fai clic su Converti Lo strumento serializza gli oggetti su tabelle TOML, gli array di oggetti su array di tabelle e ogni altro valore in linea, quindi ti fornisce TOML standard da copiare Il JSON di livello superiore deve essere un oggetto, perché un documento TOML è sempre una tabella.
A cosa serve TOML?
TOML è un formato di file di configurazione progettato per essere facile da leggere e inequivocabile da analizzare È il formato di configurazione per Rust's Cargo (Cargo.toml), packaging Python (pyproject.toml), Hugo e molti strumenti Go e Rust Le persone convertono JSON in TOML per consegnare una configurazione generata dalla macchina a uno strumento che si aspetta TOML.
Cosa succede ai valori nulli JSON in TOML?
TOML non ha alcun tipo null, quindi un null JSON non può essere rappresentato direttamente Per impostazione predefinita questo convertitore elimina i tasti null e aggiunge una nota che li elenca; puoi invece passare a scriverli come stringhe vuote I null all'interno degli array vengono sempre eliminati, perché un array TOML non può contenere null.
Qual è la differenza tra un array di tabelle e una tabella in linea?
Un array di tabelle utilizza intestazioni ripetute a doppia parentesi, un blocco per record ed è il modo TOML idiomatico per scrivere un elenco di oggetti come un elenco di server o dipendenze Una tabella in linea racchiude un oggetto su una riga come un insieme di chiavi uguale a coppie di valori tra parentesi graffe Questo strumento è predefinito per gli array di tabelle ma consente di scegliere invece in linea.
Perché il mio numero JSON 5.0 è diventato 5 in TOML?
JSON non conserva la differenza tra 5 e 5.0, quindi l'analisi si legge sia come numero 5. poiché 5 è un numero intero, il convertitore lo scrive come un numero intero TOML Se ne hai bisogno digitato come float, aggiungi una parte frazionaria nella sorgente o modifica il singolo valore dopo la conversione.
Il convertitore mantiene il mio ordine chiave?
Sì. Le chiavi vengono emesse nell'ordine in cui appaiono nel JSON, con un riarrangiamento richiesto: all'interno di ogni tabella, le chiavi semplici vengono scritte prima di qualsiasi intestazione di sottotabella o array di tabelle. Questa è una regola di sintassi TOML, non una scelta di riordino, e senza di essa il file non si analizzerebbe.
Il mio JSON è stato caricato su un server?
No. L'intera conversione avviene nel browser utilizzando JavaScript semplice Il tuo JSON, inclusi eventuali segreti o credenziali in un file di configurazione, non viene mai trasmesso, registrato o archiviato e il convertitore continua a funzionare senza connessione una volta caricata la pagina.
Perché dice che il livello superiore deve essere un oggetto?
Un documento TOML è definito come una tabella, il che significa che deve partire da un insieme di coppie chiave/valore Un array o uno scalare JSON spoglio non ha una tabella su cui mapparlo Avvolgilo prima in un oggetto, ad esempio mettendo il tuo array sotto una chiave denominata, e si convertirà.
