Strumenti per sviluppatori · Convertitori di sintassi
Perché TOML esiste: gli obiettivi di progettazione alla base di Cargo.toml e pyproject.toml
· Sfondo
toml formati di dati flusso di lavoro dello sviluppatore
TOML è stato creato in 2013 come reazione sia all'austerità di JSON che all'ambiguità di YAML. Questo post spiega gli obiettivi di progettazione dichiarati, le scelte che hanno prodotto e perché Rust e Python lo hanno standardizzato per la configurazione del progetto.
Tre formati di configurazione in un unico repository: JSON per l'editor, YAML per CI, TOML per la build e la domanda sul perché esiste il terzo
Un repository può utilizzare JSON, YAML e TOML per diverse superfici di configurazione. ToolAcre non può spiegare la scelta di ogni progetto, ma la conversione rende concrete le differenze strutturali: TOML inizia come tabella radice, utilizza intestazioni e percorsi tratteggiati per l'annidamento e trasporta valori temporali non disponibili in JSON.
Carica l'esempio piuttosto che discutere in base all'apparenza. Le tabelle nidificate diventano oggetti, le tabelle con parentesi doppie diventano matrici e i commenti scompaiono quando i valori immettono JSON. Questi limiti osservati sono più attuabili di un’affermazione generica secondo cui una sintassi è intrinsecamente migliore.
Gli obiettivi di progettazione: semantica minima e ovvia, facile da leggere e un formato che si associa in modo inequivocabile a una tabella hash
Il parser fornito espone una semantica di tabella ovvia: le intestazioni sono percorsi, gli assegnamenti appartengono alla tabella attiva e i token scalari hanno tipi TOML definiti. Le stringhe non vengono digitate semplicemente perché il loro contenuto assomiglia a date; la sintassi temporale effettiva produce oggetti data che ToolAcre normalizza deliberatamente.
Il repository non fornisce informazioni sui creatori, sulle date o sulla filosofia dichiarata del formato, quindi questo articolo evita di presentare la storia ricordata come un fatto. Riporta il comportamento testato in smol-toml e il livello di normalizzazione del convertitore.
Proprietà di progettazione osservabili nel parser fornito, senza dichiarazioni di origine non originate
TOML non ha null e la radice del documento non può essere un array o uno scalare. Non fornisce ancore o alias in stile YAML in questa mappatura. I commenti esistono nel TOML creato ma non vengono conservati dal parser del valore e pertanto non possono sopravvivere alla conversione tramite JSON o YAML.
I valori semplici senza virgolette seguono la grammatica TOML anziché la selezione dello schema di YAML. Il parser accetta un valore digitato o segnala TOML non valido con informazioni sulla posizione. ToolAcre non aggiunge una modalità stringa implicita per assegnazioni non valide.
Ciò che il modello di valore supportato esclude o gestisce in modo diverso
Il modello include stringhe, interi con segno, float, booleani, quattro tipi temporali, matrici e tabelle. Gli array di tabelle esprimono record di oggetti ripetuti. I grandi numeri interi con segno oltre 2^53 diventano stringhe decimali durante la conversione, quindi JavaScript non li arrotonda automaticamente.
I valori temporali diventano il testo orientato all'origine per la data-ora di offset, la data-ora locale, la data locale o l'ora locale. L'avviso conserva la forma in prosa, ma JSON riceve solo una stringa. La conversione indietro quindi lo cita e perde il tipo TOML nativo.
Adozione: carico dai primi giorni di Rust, PEP 518 scegliendo pyproject.toml e la specifica 1.0.0 in 2021
L'adozione di Cargo e pyproject sono affermazioni storiche ed ecosistemiche che richiedono fonti non presenti nel repository del convertitore. Qui sono intenzionalmente omessi. Un percorso o un nome file non costituisce la prova di una cronologia, di un rilascio di specifiche o di una decisione sugli standard.
La domanda operativa è se lo strumento di destinazione legge TOML e quali tabelle si aspetta. Controlla la documentazione attuale di quello strumento. I convertitori di sintassi conoscono la sintassi e la mappatura dei valori, non i contratti di configurazione del gestore dei pacchetti.
La cronologia dell'adozione dell'ecosistema viene omessa senza le fonti del repository
L'annidamento profondo può essere più difficile da analizzare perché il contesto della tabella persiste su tutte le righe, mentre grandi array di tabelle distribuiscono un elenco logico su intestazioni ripetute. JSON rende esplicita la gerarchia completa ma aggiunge parentesi graffe e virgolette. Nessuna delle due rappresentazioni rimuove la complessità dalla configurazione sottostante.
Il parser limita la nidificazione a 100 e la lunghezza del codice sorgente a due milioni di caratteri. Questi sono limiti di rifiuto, non dichiarazioni sulla dimensione di configurazione ideale o limiti universali TOML.
Cosa non copre: scelta del parser TOML in ogni lingua e natura di sola lettura di alcune implementazioni della libreria standard
La scelta del parser in ogni lingua non rientra nell'ambito, così come le funzionalità di scrittura della libreria standard. ToolAcre utilizza smol-toml in modo dinamico e racchiude i suoi errori. Un'altra implementazione può formattare l'output valido in modo diverso o esporre un altro API rappresentando gli stessi dati.
Utilizza dispositivi cross-tool per valori temporali, numeri interi di grandi dimensioni, array e chiavi puntate quando l'interoperabilità è importante. Un file accettato qui non viene accettato automaticamente da ogni consumatore TOML.
Conclusione: TOML è convinto di essere un formato di configurazione e di come il pannello dei convertitori di sintassi ti consenta di vedere qualsiasi file JSON o YAML in quella forma
TOML è supponente in modi osservabili: radice della tabella, valori tipizzati espliciti, tipi temporali nativi e nessun valore nullo. La conversione espone tali scelte e le loro incompatibilità con obiettivi a forma di JSON senza bisogno di un mito sull'origine.
Utilizza il pannello per ispezionare un albero e identificare gli avvisi. Quindi torna allo schema di destinazione e crea il layout della tabella che gli umani manterranno. Il convertitore fornisce prove sui valori, non un verdetto sulla preferenza del formato.
La stessa disciplina si applica quando TOML è solo una vista intermedia. Conserva la fonte, confronta i valori normalizzati e annota ogni conversione temporale o con numeri interi larghi prima di giudicare la leggibilità. Un layout di tabella compatto può comunque nascondere un tipo modificato, mentre un array dettagliato di tabelle può essere semanticamente esatto. La scelta del formato dovrebbe seguire il contratto di configurazione e il flusso di lavoro di manutenzione, non la pulizia visiva di un campione generato.