De eerste keer dat TOML mij beet, was het niet de syntaxis Het was de bestelling Ik had een JSON instellingen object van een oude Node service, ik wilde het als een config.toml voor een Rust herschrijving, en ik deed wat iedereen de eerste keer doet: ik heb de tafels met de hand getypt Tien minuten later gooide de parser een fout die ik niet begreep, wijzend naar een lijn die er perfect uitzag Het probleem was drie toetsen zittend onder een [table] koptekst die erboven hoorde TOML heeft een regel die JSON niet heeft, en als je er eenmaal op struikelt vergeet je het nooit meer.
ik bouw Toolz.dev, en ik heb een lange plank van formaat converters daarheen verzonden, dus ik schreef de JSON naar TOML converter om die hele categorie van fouten te verwijderen Je plakt JSON, je krijgt TOML die opnieuw parseert naar dezelfde gegevens, en de bestelling wordt afgehandeld voor u Deze gids is het ding dat ik wou dat ik had gelezen die middag: wat TOML is, waar JSON en TOML het niet eens zijn, en hoe om te zetten tussen hen zonder iets te verliezen waar je om gaf.
tl;dr: TOML is een getypt configuratieformaat dat wordt gebruikt door Cargo, Poetry, Hugo en veel Rust and Go-tooling. Het converteren van JSON naar TOML is meestal mechanisch, maar drie dingen vereisen oordeel: tabelvolgorde (sleutels vóór subtabellen, altijd), hoe je arrays van objecten schrijft (arrays van tabellen versus inline tabellen) en wat er met JSON gebeurt
null, die TOML op geen enkele manier kan uitdrukken De JSON naar TOML converter maakt ze alle drie expliciet en draait volledig in uw browser.
Wat is TOML, en waarom zou ik JSON erin omzetten?
TOML staat voor Tom' s Obvious, Minimal Language Het leest als een oud INI-bestand, maar in tegenstelling tot INI heeft het een echte specificatie met getypte waarden, eersteklas data, en een gedefinieerde grammatica Die specificatie is de reden dat het gewonnen heeft: een config formaat dat een persoon in één oogopslag kan lezen, dat een machine elke keer op dezelfde manier parseert, zonder onduidelijkheid over de vraag of port = 8080 is een string of een getal Het is een getal, want TOML zegt het.
Je grijpt naar JSON naar TOML conversie wanneer een machine je JSON gaf en een tool wil TOML Dat gebeurt meer dan je zou denken Een API retourneert een instellingen blob als JSON en je hebt het nodig in pyproject.toml. Je hebt een oude config.json en je verplaatst het project naar een stapel met de tekst config.toml. Je hebt programmatisch wat gegevens gegenereerd, deze kwamen uit als JSON, want dat is wat JSON.stringify produceert, en de consument is Cargo of Hugo of een Go-dienst met behulp van een TOML-bibliotheek In elk geval zijn de gegevens identiek Alleen de serialisatie verschilt.
De omgekeerde richting bestaat ook, maar het is een andere klus Als je de andere kant op gaat, is de JSON-formatter het is de moeite waard om open te staan voor gezond verstand: controleer eerst de JSON, en de JSON naar YAML-converter behandelt het andere gangbare configuratieformaat Deze handleiding gaat over JSON die naar TOML gaat.
Hoe brengt de converter JSON in kaart op TOML?
Er zijn slechts een handvol vormen in JSON, en elk heeft een thuis in TOML. Het begrijpen van de mapping is het meest begrijpen van de tool.
EEN JSON object wordt een TOML table. Het object op het hoogste niveau is de hoofdtabel. Daarom dringt de converter erop aan dat de invoer een object is. Geneste objecten worden [table] headers met een stippelpad, dus { "database": { "pool": { "max": 10 } } } wordt een [database.pool] sectie met max = 10 inside it.
EEN JSON array van objecten wordt een TOML array van tabellen, geschreven met de dubbele haak [[name]] header, één blok per element Dit is het idiomatische TOML patroon voor een lijst van records: een lijst van servers, een lijst van afhankelijkheden, een lijst van build targets Elk element krijgt zijn eigen [[servers]] block.
Every scalair kaarten direct Een JSON string wordt een TOML basis string in dubbele aanhalingstekens, waarbij besturingstekens ontsnapt Een JSON getal wordt een TOML geheel getal als het een geheel getal is en een float anders Een JSON boolean wordt true of false. Dit zijn de gemakkelijke gevallen, en de converter heeft ze nooit verkeerd.
EEN JSON array van scalairen wordt een TOML inline array: ["admin", "editor"] blijft ["admin", "editor"]. Gemengde arrays en geneste arrays worden ook inline geschreven, omdat dat de enige plek is waar ze passen.
Waarom is de sleutelvolgorde zo belangrijk in TOML?
Dit is de regel die iedereen vangt, dus het is de moeite waard om duidelijk te vermelden In TOML, binnen elke tabel, moeten al die tabel' eigen sleutel/waarde paren verschijnen vóór een van de sub-tabel headers Als je een [server] header, dan wat toetsen, dan nog een sleutel die bij de root table hoort, de parser leest die verdwaalde sleutel als onderdeel van [server] in plaats daarvan. Het beste geval komt op de verkeerde plaats terecht; in het ergste geval kan het bestand niet worden ontleed.
JSON heeft zo'n regel niet In JSON is de sleutelvolgorde niet eens significant, en objecten en scalairen vermengen zich vrij in dezelfde beugel Dus een naïeve JSON-naar-TOML-conversie die het object in invoegvolgorde laat lopen en elke sleutel onderweg uitzendt, zal gebroken TOML produceren op het moment dat een scalair een genest object volgt.
De converter lost dit op door twee passages over elke tabel te maken, eerst zendt hij alle eenvoudige toetsen uit, de scalairen en inline arrays, dan pas zendt hij de sub-tabel en array-of-tables headers uit, waarbij hij in elke groep terugkomt, binnen elke groep blijft je sleutelvolgorde behouden, wat je wilt, maar de vereiste herschikking tussen de twee groepen gebeurt automatisch Je hoeft er nooit over na te denken, en je krijgt nooit de fout die ik heb gekregen.
Wanneer moeten arrays van objecten tabellen versus inline zijn?
Hier is de enige echte keuze. Een reeks objecten kan in TOML op twee manieren worden geschreven, en beide zijn geldig.
De eerste is een array van tabellen, de dubbele-beugel vorm Het is breedsprakig en leesbaar, één blok per record, en het is hoe de meeste TOML in het wild eruit ziet Als je een Cargo.toml met meerdere [[bin]] inzendingen, je hebt dit gezien.
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
De tweede is een inline tabel binnen een normale array, die elk object op één regel verpakt.
servers = [
{ name = "web", ip = "10.0.0.1" },
{ name = "api", ip = "10.0.0.2" },
]
Beide retour naar dezelfde gegevens Welke u wilt, hangt af van het doel en van de smaak Arrays van tabellen lezen beter voor records een mens zal bewerken, en ze zijn de conventie voor de meeste tooling config Inline tabellen zijn compacter en dichter bij de vorm van de originele JSON, die sommige mensen verkiezen als de lijst kort is of de objecten klein zijn De converter standaard naar arrays van tabellen en geeft u een schakelaar om te schakelen Als u het niet zeker weet, laat het dan op de standaard: het is hoe een TOML-bestand er meestal uitziet.
Wat gebeurt er met JSON null in TOML?
TOML heeft geen nul. Er is geen trefwoord, geen lege waarde, niets. Dit is een doelbewuste ontwerpbeslissing door het formaat, en het is de enige plek waar JSON tot TOML echt verliesgevend is.
De converter moet dus een keuze maken, en hij laat het je standaard maken, een sleutel waarvan de waarde is null wordt geschrapt, en het gereedschap vermeldt de weggevallen toetsen in een noot onder de uitvoer zodat niets stil verdwijnt Als je liever de sleutel wilt behouden, kun je overschakelen naar het schrijven van null als een lege string, die de sleutel behoudt ten koste van het veranderen van het type Geen van beide is perfect, omdat er geen perfect antwoord is. Het gaat erom dat de keuze zichtbaar is in plaats van begraven.
Nullen binnen arrays worden altijd weggelaten, met een waarschuwing, omdat een TOML array helemaal geen null kan bevatten Als uw JSON dat wel heeft [1, null, 3], de TOML zal dat zijn [1, 3] en de tool zal je vertellen dat het er een heeft verwijderd. Als deze nulletjes betekenis hebben, is dat een signaal om de gegevens opnieuw vorm te geven voordat ze worden geconverteerd in plaats van erna.
Waarom verloor mijn getal zijn decimaal, of kreeg het er een?
Deze verrast mensen die om types geven JSON onderscheidt zich niet 5 ten gevolge van 5.0. Beide parseren op dezelfde IEEE 754 dubbel, en tegen die tijd JSON.parse is gedaan er is geen spoor van de achterliggende nul Dus wanneer de converter het getal ziet 5, het kan niet weten dat je een vlotter bedoelde, en sindsdien 5 is een geheel getal, het schrijft een TOML-geheel getal.
TOML daarentegen onderscheidt wel gehele getallen van floats, en sommige tools geven om het verschil Als je een waarde nodig hebt die als float wordt getypt, is de oplossing om het een fractioneel deel in de bron te geven, namelijk 5.1 of 5.0 geschreven op een manier die overleeft, of om de enkele waarde na conversie te bewerken Het is een verandering van één teken en het is zeldzaam, maar het is de moeite waard om te weten waarom het gebeurt in plaats van aan te nemen dat de converter verkeerd is. 't Is niet verkeerd. JSON gooide de informatie eenvoudigweg weg voordat de converter deze ooit zag.
Het omgekeerde geval verschijnt met zeer grote of zeer kleine getallen, waarbij JavaScript's String() produceert exponentnotatie zoals 1e+21. TOML accepteert dat als een float, dus het converteert prima, maar de vorm van het getal kan er anders uitzien dan wat je hebt getypt. Nogmaals, de waarde is identiek; alleen de weergave is gewijzigd.
Hoe werken kale en geciteerde sleutels?
TOML laat een sleutel kaalschrijven als deze alleen uit letters, cijfers, onderstrepingstekens en streepjes bestaat Al het andere, een sleutel met een punt, een spatie, een schuine streep, een Unicode-teken, moet worden geciteerd De converter controleert elke toets en citeert alleen degene die deze nodig hebben, dus user-name blijft kaal en "user.name" krijgt aanhalingstekens om te stoppen dat de punt als tabelpad wordt gelezen, U hoeft hier niet over na te denken, maar als u aanhalingstekens rond een toets in de uitvoer ziet, daarom: de toets bevatte een teken dat anders van betekenis zou veranderen.
Een uitgewerkt voorbeeld
Hier is het voorbeeld dat het gereedschap laadt, zodat u elke regel tegelijk kunt zien. De 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" }
]
}
wordt TOML waarbij de hoofdscalairen op de eerste plaats komen, de geneste objecten op volgorde gestippelde tabellen worden en de reeks servers twee wordt [[servers]] blokken:
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"
Merk dat op title, version en enabled worden vóór elke header geschreven, roles blijft een inline array omdat het een array van strings is, en [database.pool] zit onder [database] als stippelpad Elke regel in deze gids is zichtbaar in negen regels uitvoer.
Welk gereedschap voor welke conversie?
TOML is één formaat in een gezin, en de juiste tool hangt af van waar je begint en eindigt. Hier is hoe ik erover denk.
| Je hebt | je wilt | goed doen |
|---|---|---|
| Json | TOML-configuratie | JSON naar TOML |
| Json | YAML-configuratie | json naar yaml |
| lijk heb- | Json | YAML naar JSON |
| Json | XML | JSON naar XML |
| Messy JSON | Leesbare JSON | JSON-formatter |
Het patroon is dat config formaten uitwisselbare weergaven zijn van dezelfde gegevens, en de converter die u wilt is genoemd naar de richting waarin u gaat TOML, YAML en JSON drukken allemaal geneste sleutel/waarde-gegevens uit; het verschil is welke uw doeltool leest.
Is het veilig om een config-bestand online te converteren?
Config-bestanden zijn precies het soort dingen waar je voorzichtig mee moet zijn als je ze in een website plakt, omdat ze vaak verbindingsreeksen, tokens en andere geheimen bevatten. De JSON naar TOML converter draait volledig in uw browser De JSON die u plakt wordt geparseerd in het geheugen op uw apparaat, de TOML wordt daar geproduceerd, en niets wordt naar een server gestuurd, naar een log geschreven, of opgeslagen U kunt dit zelf bekijken: open uw netwerktab, voer een conversie uit, en zie dat er geen verzoek uitGaat Het blijft ook werken zonder verbinding als de pagina eenmaal geladen is, wat het praktische bewijs is dat het werk lokaal is Als het u uitmaakt waar uw gegevens naartoe gaan, en met een config-bestand moet u, dit is de eigenschap die ertoe doet Het is hetzelfde principe achter elke tool op de site, en de reden dat ik er uitvoerig over schreef in de notitie op Gegevensprivacy in online tools.
Waar dit past in een echte workflow
Formaatconversie is zelden de hele taak Het is een stap Je haalt een instellingenobject uit een API, je converteert het, je laat het vallen in een project De waarde van een client-side converter is dat het zonder wrijving in die stroom gleuft: geen upload, geen account, niet wachten op een server, geen verwondering of je geheimen nu in iemand zitten' s logs Dat is dezelfde reden dat ik het geheel bewaar Toolz.dev stel de clientzijde in en het is een thema waar ik in de film op terugkom Productiviteitstools voor ontwikkelaar schrijf op, want de tools die je twintig keer per dag bereikt, zijn de tools waarbij een retour van twee seconden en een privacyvraag samenkomen.
TOML verdiende zijn plaats in die flow door op de beste manier saai te zijn Het parseert overal hetzelfde, het leest goed, en zijn ene scherpe rand, de bestelregel, is precies het soort ding dat een converter voor je moet neerzetten Plak je JSON, kies hoe je arrays en nulls wilt laten verwerken, en kopieer TOML dat gewoon werkt.
Veelgestelde vragen
Hoe converteer ik JSON naar TOML?
Plak uw JSON-object in de converter en klik op Converteren. De tool serialiseert objecten naar TOML-tabellen, arrays van objecten naar arrays van tabellen en elke andere waarde inline, en geeft u vervolgens standaard TOML om te kopiëren. De JSON op het hoogste niveau moet een object zijn, omdat een TOML-document altijd een tabel is.
Waar wordt TOML voor gebruikt?
TOML is een configuratiebestandsformaat dat is ontworpen om gemakkelijk te lezen en ondubbelzinnig te parseren Het is het configuratieformaat voor Rust' s Cargo (Cargo.toml), Python-verpakking (pyproject.toml), Hugo en veel Go and Rust-tools Mensen converteren JSON naar TOML om een machinaal gegenereerde configuratie te overhandigen aan een tool die TOML verwacht.
Wat gebeurt er met JSON nulwaarden in TOML?
TOML heeft geen null-type, dus een JSON null kan niet direct worden weergegeven Standaard laat deze converter null-toetsen vallen en voegt een notitie toe waarin ze worden vermeld; u kunt in plaats daarvan overschakelen naar het schrijven ervan als lege tekenreeksen. Nullen in arrays worden altijd verwijderd, omdat een TOML-array geen nul kan bevatten.
Wat is het verschil tussen een array van tabellen en een inline tabel?
Een array van tabellen maakt gebruik van herhaalde headers met dubbele haakjes, één blok per record, en is de idiomatische TOML-manier om een lijst met objecten te schrijven, zoals een lijst met servers of afhankelijkheden. Een inline-tabel verpakt een object op één regel, aangezien een set sleutels gelijk is aan waardeparen tussen haakjes. Deze tool is standaard bedoeld voor reeksen tabellen, maar laat u in plaats daarvan inline kiezen.
Waarom werd mijn JSON nummer 5.0 5 in TOML?
JSON behoudt het verschil tussen 5 en 5.0 niet, dus parseren leest beide als het getal 5. aangezien 5 een geheel getal is, schrijft de converter het als een geheel getal van TOML. Als u het als een float wilt typen, voegt u een fractioneel deel toe aan de bron of bewerkt u de enkele waarde na conversie.
Houdt de converter mijn sleutelvolgorde?
Ja. sleutels worden uitgezonden in de volgorde waarin ze in de JSON verschijnen, met één vereiste herschikking: binnen elke tabel worden gewone toetsen geschreven vóór elke subtabel of array-of-tables-headers. Dat is een TOML-syntaxisregel, geen herschikkingskeuze, en zonder deze zou het bestand niet parseren.
Is mijn json geüpload naar een server?
Nee. De volledige conversie gebeurt in uw browser met behulp van gewoon JavaScript Uw JSON, inclusief eventuele geheimen of inloggegevens in een configuratiebestand, wordt nooit verzonden, geregistreerd of opgeslagen, en de converter blijft zonder verbinding werken zodra de pagina is geladen.
Waarom staat er dat het hoogste niveau een object moet zijn?
Een TOML-document wordt gedefinieerd als een tabel, wat betekent dat het moet beginnen met een reeks sleutel/waarde-paren. Een kale JSON-array of scalair heeft geen tabel om op in te zetten. Wikkel het eerst in een object, bijvoorbeeld door uw array onder een benoemde sleutel te plaatsen, en het zal converteren.
