Bagaimana TOML jadual menjadi JSON objek: [jadual], [[array]] dan kekunci bertitik

Dari mana datangnya sarang? — fail TOML yang kelihatan rata ditukar kepada JSON bersarang dalam dan pengepala yang menyebabkannya

Fail TOML boleh kelihatan hampir rata kerana kurungan membawa sarang. `[a.b.c]` membuka jadual perantaraan, jadi `d = 1` di bawahnya menjadi `{"a":{"b":{"c":{"d":1}}}}`. Pendakap JSON menjadikan hierarki kelihatan yang TOML menyatakan melalui laluan jadual aktif.

ToolAcre mewakilkan penghuraian sintaks kepada smol-toml dan kemudian menormalkan nilai JSON tidak boleh dibawa. Ini bukan penulisan semula berasaskan baris. Jadual, kekunci bertitik dan tatasusunan jadual menjadi objek dan tatasusunan biasa sebelum JSON bersiri, itulah sebabnya ejaan dan ulasannya tidak tersedia dalam output.

pengepala [jadual] — cara pengepala membuka objek bersarang dan cara [a.b.c] mencipta objek perantaraan secara tersirat

Pengepala kurungan tunggal membuka jadual. `[owner]` mengarahkan mengikut tugasan ke dalam `owner`; `[owner.contact]` mencipta atau memasukkan objek kenalan bersarang. Objek perantaraan tidak perlu mempunyai pengepala berasingan. Kewujudan mereka berikutan daripada segmen laluan dalam pengepala.

Tugasan sebelum sebarang pengepala kekal di akar. Jadual kemudian tidak mengalihkannya secara retroaktif. Apabila menyemak JSON yang ditukar, ikut laluan sifat penuh dan bukannya jarak fizikal antara baris: jadual semasa TOML kekal aktif sehingga pengepala lain mengubahnya.

[[array daripada tables]] — mengapa pengepala dua kurungan berulang menambahkan objek pada tatasusunan dan susunan yang dikekalkannya

Pengepala kurungan dua menambahkan jadual pada tatasusunan. Dua bahagian `[[server]]` menjadi `server: [{...},{...}]` dalam susunan sumber. Medan di bawah setiap pengepala adalah milik ahli tatasusunan itu sehingga pengepala lain bermula, menjadikan konfigurasi berulang jelas dalam JSON.

Susunan di dalam tatasusunan ialah data dan dikekalkan. Persembahan kunci objek kemudian boleh diisih apabila pilihan dipilih, tetapi ahli tatasusunan tidak pernah disusun semula. Mengelirukan kedua-duanya akan mengubah keutamaan pelayan atau urutan pemalam dan bukannya sahaja memformat dokumen.

Kekunci bertitik dan jadual sebaris — a.b = 1 dan { x = 1 } sebagai dua lagi cara untuk menyatakan sarang yang sama

Tugasan bertitik memberikan tatatanda laluan lain: `a.b.c = true` menghasilkan bentuk objek bersarang yang sama seperti pengepala jadual yang sepadan. Jadual sebaris seperti `point = { x = 1, y = 2 }` menjadi objek bersarang serta-merta. Borang ini boleh menerangkan pokok yang serupa sambil kelihatan sangat berbeza dengan pengulas.

JSON sahaja merekodkan kunci dan nilai yang terhasil, bukan yang TOML notasi mengarangnya. Oleh itu, penukaran semula tidak boleh memulihkan pilihan asal antara pengepala, kekunci bertitik dan jadual sebaris. Penulis TOML memilih pensiriannya sendiri yang sah daripada pokok.

Jenis yang dibawa dan jenis yang tidak — integer, apungan, boolean dan rentetan dipetakan secara langsung; tarikh-masa menjadi rentetan dan JSON null tidak mempunyai sumber TOML

Rentetan, integer selamat, terapung, boolean, tatasusunan dan jadual dipetakan secara langsung. Empat jenis temporal TOML tidak: mengimbangi tarikh-masa, tarikh-masa tempatan, tarikh tempatan dan masa tempatan menjadi rentetan sumber seperti RFC 3339 dan amaran menamakan setiap laluan dan jenis. Penulis kemudiannya memetik rentetan tersebut daripada mencipta semula token datetime.

TOML yang ditandatangani 64-bit integer boleh melebihi JavaScript's selamat integer julat. smol-toml mengembalikan nilai seperti BigInt apabila diperlukan; ToolAcre menukarkannya kepada rentetan perpuluhan dan memberi amaran daripada membulatkan digit. Ini mengekalkan ejaan dengan kos menukar jenis JSON.

Contoh yang berfungsi: senarai pyproject.toml — [projek], [project.optional-dependencies] dan [[tool.plugins]] ditukar kepada JSON dengan setiap peringkat dikesan

Cuba `name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]`, kemudian dua `[[tool.plugins]]` jadual dengan nama yang berbeza. JSON meletakkan nama pada akar, projek sarang dan pilihan, dan menghasilkan tatasusunan pemalam di bawah alat.

Tambahkan `released = 1979-05-27` dan `huge = 9223372036854775807`. Yang pertama menjadi rentetan `1979-05-27`; yang kedua menjadi rentetan perpuluhan. Kedua-dua amaran mengenal pasti laluan yang diubah, menjadikan jenis bukan JSON boleh disemak dan bukannya membenarkan paksaan Tarikh atau Nombor senyap.

Perkara yang tidak dilindungi ini — menukarkan JSON kembali kepada TOML idiomatik dengan pengumpulan pengepala yang wajar, yang melibatkan pilihan gaya yang tidak ditentukan oleh peraturan sepenuhnya

JSON-to-TOML disokong untuk objek akar, tetapi ia tidak mencipta semula pilihan atau ulasan pengarang idiomatik. Kekunci bernilai nol ditinggalkan; null di dalam tatasusunan menjadi rentetan kosong untuk mengekalkan kedudukan. Tatasusunan akar, skalar atau null ditolak kerana dokumen TOML mestilah jadual.

Tingkah laku itu membetulkan implikasi garis besar bahawa penukaran terbalik adalah di luar skop. Penukar menulis TOML, namun kesetiaan gaya adalah di luar janjinya. Perbezaannya penting: penyirian yang disokong tidak sama seperti memulihkan bait fail sumber untuk bait atau memilih reka letak yang lebih disukai oleh penyelenggara.

Menulis JSON kembali ke TOML disokong, tetapi ulasan, jenis tarikh dan gaya pengarang tidak dikembalikan

Baca pengepala TOML sebagai laluan dan kurungan berganda sebagai operasi tambah. Pandangan JSON berharga untuk mengesan pepohon yang terhasil, manakala amaran mendedahkan masa tarikh dan integer lebar yang melintasi sempadan jenis. Jangan panggil operasi tanpa kerugian apabila amaran muncul.

Untuk pemindahan konfigurasi, simpan yang asal di sebelah output yang ditukar. Sahkan nilai dahulu, kemudian edit organisasi TOML untuk pembaca dan alat sasaran. Penukar sintaks melakukan langkah parse-and-write mekanikal; ia tidak boleh memutuskan kumpulan khusus projek, kunci yang diterima atau sama ada aplikasi menyokong fail tersebut.

Perbandingan akhir harus memisahkan tiga soalan yang mudah dikaburkan bersama. Pertama, adakah nilai yang dihuraikan itu bertahan? Kedua, adakah mana-mana jenis TOML sahaja menjadi rentetan JSON atau mana-mana null hilang? Ketiga, adakah TOML yang baru bersiri disusun mengikut cara yang boleh difahami oleh penyelenggara? Dua yang pertama boleh disemak terhadap nilai dan amaran; yang ketiga memerlukan semakan manusia. Menyimpan semakan itu berasingan menghalang siri yang sah secara teknikal daripada dipanggil migrasi setia apabila jenis atau struktur kepengajarannya berubah.