Come le tabelle TOML diventano oggetti JSON: [tabella], [[array]] e chiavi puntate

Da dove viene la nidificazione? - un file TOML dall'aspetto piatto convertito in JSON profondamente annidato e le intestazioni che lo hanno causato

Un file TOML può apparire quasi piatto perché le parentesi portano l'annidamento. `[a.b.c]` apre le tabelle intermedie, quindi `d = 1` sotto diventa `{"a":{"b":{"c":{"d":1}}}}`. Le parentesi graffe JSON rendono visibile una gerarchia che TOML esprime attraverso il percorso della tabella attiva.

ToolAcre delega l'analisi della sintassi a smol-toml e quindi normalizza i valori che JSON non può trasportare. Questa non è una riscrittura basata su righe. Tabelle, chiavi puntate e matrici di tabelle diventano oggetti e matrici ordinari prima della serializzazione JSON, motivo per cui l'ortografia e i commenti non sono disponibili nell'output.

intestazioni [tabella]: come un'intestazione apre un oggetto nidificato e come [a.b.c] crea implicitamente oggetti intermedi

Un'intestazione a parentesi singola apre una tabella. `[owner]` indirizza le seguenti assegnazioni in `owner`; `[owner.contact]` crea o inserisce l'oggetto contatto nidificato. Non è necessario che gli oggetti intermedi abbiano intestazioni separate. La loro esistenza deriva dai segmenti del percorso nell'intestazione.

Le assegnazioni prima di qualsiasi intestazione rimangono alla radice. Le tabelle successive non li spostano retroattivamente. Durante la revisione di JSON convertito, segui il percorso completo della proprietà anziché la distanza fisica tra le righe: la tabella corrente di TOML rimane attiva finché un'altra intestazione non la modifica.

[[array di tabelle]]: perché un'intestazione ripetuta con doppie parentesi accoda oggetti a un array e l'ordine che preserva

Un'intestazione con doppia parentesi accoda una tabella a un array. Due sezioni `[[server]]` diventano `server: [{...},{...}]` nell'ordine di origine. I campi sotto ciascuna intestazione appartengono a quel membro dell'array finché non inizia un'altra intestazione, rendendo esplicita la configurazione ripetuta in JSON.

L'ordine all'interno dell'array è costituito dai dati e viene preservato. La presentazione della chiave oggetto può essere successivamente ordinata quando l'opzione è selezionata, ma i membri dell'array non vengono mai riordinati. Confondere i due cambierebbe la priorità del server o la sequenza del plugin piuttosto che limitarsi a formattare un documento.

Chiavi puntate e tabelle in linea: a.b = 1 e { x = 1 } come altri due modi per esprimere lo stesso annidamento

Le assegnazioni punteggiate forniscono un'altra notazione di percorso: `a.b.c = true` produce la stessa forma di oggetto nidificato delle corrispondenti intestazioni di tabella. Le tabelle in linea come `point = { x = 1, y = 2 }` diventano immediatamente oggetti nidificati. Questi moduli possono descrivere alberi simili pur apparendo molto diversi a un revisore.

JSON registra solo le chiavi e i valori risultanti, non la notazione TOML che li ha creati. La riconversione quindi non può ripristinare la scelta originale tra intestazioni, chiavi puntate e tabelle in linea. Il writer TOML sceglie la propria serializzazione valida dall'albero.

Tipi che vengono trasferiti e tipi che non lo fanno: numeri interi, numeri in virgola mobile, booleani e stringhe vengono mappati direttamente; date-ora diventano stringhe e JSON null non ha TOML sorgente

Stringhe, numeri interi sicuri, numeri in virgola mobile, valori booleani, matrici e tabelle vengono mappati direttamente. I quattro tipi temporali di TOML non: data-ora di offset, data-ora locale, data locale e ora locale diventano le stringhe di origine simili a RFC 3339 e un avviso nomina ciascun percorso e tipo. Lo scrittore successivamente cita quelle stringhe invece di ricreare i token datetime.

Gli interi a bit con segno 64 di TOML possono superare l'intervallo di numeri interi sicuri di JavaScript. smol-toml restituisce valori come BigInt quando necessario; ToolAcre li converte in stringhe decimali e avvisa anziché arrotondare le cifre. Ciò preserva l'ortografia a costo di modificare il tipo JSON.

Esempio realizzato: un elenco pyproject.toml — [progetto], [project.optional-dipendenze] e un elenco [[tool.plugins]] convertito in JSON con ogni livello tracciato

Prova `name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]`, quindi due tabelle `[[tool.plugins]]` con nomi distinti. JSON posiziona il nome alla radice, nidifica progetto e facoltativo e produce un array di plugin sotto lo strumento.

Aggiungi `released = 1979-05-27` e `huge = 9223372036854775807`. La prima diventa la stringa `1979-05-27`; la seconda diventa una stringa decimale. Entrambi gli avvisi identificano i percorsi modificati, rendendo revisionabili i tipi nonJSON invece di consentire la coercizione silenziosa di data o numero.

Ciò che questo non copre: riconvertire JSON nell'idiomatico TOML con un raggruppamento di intestazioni sensato, che implica scelte di stile che nessuna regola determina completamente

JSON-to-TOML è supportato per un oggetto root, ma non ricrea scelte o commenti idiomatici dell'autore. Le chiavi con valore null vengono omesse; null all'interno di un array diventa una stringa vuota per preservare le posizioni. Un array root, scalare o null viene rifiutato perché un documento TOML deve essere una tabella.

Questo comportamento corregge l’implicazione dello schema secondo cui la conversione inversa è fuori dall’ambito. Il convertitore scrive TOML, ma la fedeltà allo stile va oltre le sue promesse. La distinzione è importante: la serializzazione supportata non equivale a ripristinare il file sorgente byte per byte o scegliere il layout che un manutentore preferirebbe.

La riscrittura di JSON in TOML è supportata, ma i commenti, i tipi di data/ora e lo stile autoriale non vengono restituiti

Leggi le intestazioni TOML come percorsi e le doppie parentesi come operazioni di aggiunta. La vista JSON è utile per tracciare l'albero risultante, mentre gli avvisi espongono date/ora e numeri interi estesi che superano un limite di tipo. Non definire l'operazione senza perdite quando viene visualizzato uno degli avvisi.

Per la migrazione della configurazione, mantieni l'originale accanto all'output convertito. Verifica prima i valori, quindi modifica l'organizzazione TOML per i lettori e lo strumento di destinazione. I convertitori di sintassi eseguono la fase meccanica di analisi e scrittura; non può decidere il raggruppamento specifico del progetto, le chiavi accettate o se l'applicazione supporta quel file.

Un confronto finale dovrebbe separare tre domande che sono facili da confondere insieme. Innanzitutto, i valori analizzati sono sopravvissuti? In secondo luogo, qualsiasi tipo TOML-only è diventato una stringa JSON o qualsiasi tipo null è scomparso? Terzo, il nuovo TOML serializzato è organizzato in modo che il manutentore possa comprenderlo? I primi due possono essere confrontati con valori e avvisi; il terzo necessita di una revisione umana. Mantenere questi controlli separati impedisce che una serializzazione tecnicamente valida venga definita migrazione fedele quando i suoi tipi o la struttura autoriale sono cambiati.