Bagaimana tabel TOML menjadi objek JSON: [tabel], [[array]] dan tombol titik-titik

Dari mana asal sarangnya? — file TOML yang tampak datar dikonversi menjadi JSON yang sangat bersarang, dan header yang menyebabkannya

File TOML dapat tampak hampir datar karena tanda kurung memuat sarangnya. `[a.b.c]` membuka tabel perantara, jadi `d = 1` di bawahnya menjadi `{"a":{"b":{"c":{"d":1}}}}`. Tanda kurung kurawal JSON membuat hierarki terlihat yang TOML diekspresikan melalui jalur tabel aktif.

ToolAcre mendelegasikan penguraian sintaksis ke smol-toml dan kemudian menormalkan nilai yang tidak dapat dibawa oleh JSON. Ini bukan penulisan ulang berbasis garis. Tabel, kunci titik, dan larik tabel menjadi objek dan larik biasa sebelum serialisasi JSON, itulah sebabnya ejaan dan komentarnya tidak tersedia di keluaran.

Header [tabel] - bagaimana header membuka objek bersarang dan bagaimana [a.b.c] membuat objek perantara secara implisit

Header braket tunggal membuka tabel. `[owner]` mengarahkan tugas berikut ke `owner`; `[owner.contact]` membuat atau memasuki objek kontak bersarang. Objek perantara tidak perlu memiliki header terpisah. Keberadaannya mengikuti segmen jalur di header.

Penugasan sebelum header apa pun tetap berada di root. Tabel selanjutnya tidak memindahkannya secara surut. Saat meninjau JSON yang dikonversi, ikuti jalur properti lengkap, bukan jarak fisik antar baris: tabel TOML saat ini tetap aktif hingga header lain mengubahnya.

[[array tabel]] — mengapa header braket ganda berulang menambahkan objek ke array, dan urutan yang dipertahankannya

Header tanda kurung ganda menambahkan tabel ke array. Dua bagian `[[server]]` menjadi `server: [{...},{...}]` dalam urutan sumber. Bidang di bawah setiap header menjadi milik anggota array tersebut hingga header lain dimulai, sehingga konfigurasi berulang menjadi eksplisit di JSON.

Urutan di dalam array adalah data dan dipertahankan. Presentasi kunci objek nantinya dapat diurutkan ketika opsi dipilih, tetapi anggota array tidak pernah diurutkan ulang. Membingungkan keduanya akan mengubah prioritas server atau urutan plugin daripada sekadar memformat dokumen.

Kunci bertitik dan tabel sebaris — a.b = 1 dan { x = 1 } sebagai dua cara lagi untuk mengekspresikan sarang yang sama

Penugasan bertitik memberikan notasi jalur lain: `a.b.c = true` menghasilkan bentuk objek bertumpuk yang sama dengan header tabel terkait. Tabel sebaris seperti `point = { x = 1, y = 2 }` segera menjadi objek bertumpuk. Bentuk-bentuk ini dapat mendeskripsikan pohon serupa namun terlihat sangat berbeda bagi pengulas.

JSON hanya mencatat kunci dan nilai yang dihasilkan, bukan notasi TOML yang menulisnya. Oleh karena itu, mengonversi kembali tidak dapat mengembalikan pilihan awal di antara header, tombol bertitik, dan tabel sebaris. Penulis TOML memilih serialisasi validnya sendiri dari pohon.

Tipe yang terbawa dan tipe yang tidak — bilangan bulat, float, boolean, dan string dipetakan secara langsung; tanggal-waktu menjadi string dan JSON null tidak memiliki sumber TOML

String, bilangan bulat aman, float, boolean, array, dan tabel dipetakan secara langsung. Empat tipe temporal TOML tidak: offset tanggal-waktu, tanggal-waktu lokal, tanggal lokal dan waktu lokal menjadi string sumber yang mirip RFC 3339, dan peringatan memberi nama setiap jalur dan jenis. Penulis kemudian mengutip string tersebut daripada membuat ulang token datetime.

Bilangan bulat 64-bit yang ditandatangani TOML dapat melebihi rentang bilangan bulat aman JavaScript. smol-toml mengembalikan nilai seperti BigInt bila diperlukan; ToolAcre mengonversinya menjadi string desimal dan memperingatkan, bukan membulatkan angka. Tindakan ini mempertahankan ejaan dengan mengorbankan jenis JSON.

Contoh praktis: daftar pyproject.toml — [project], [project.optional-dependencies] dan [[tool.plugins]] dikonversi ke JSON dengan setiap level ditelusuri

Coba `name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]`, lalu dua tabel `[[tool.plugins]]` dengan nama berbeda. JSON menempatkan nama di root, proyek sarang dan opsional, dan menghasilkan array plugin di bawah alat.

Tambahkan `released = 1979-05-27` dan `huge = 9223372036854775807`. Yang pertama menjadi string `1979-05-27`; yang kedua menjadi string desimal. Kedua peringatan tersebut mengidentifikasi jalur yang diubah, membuat tipe non-JSON dapat ditinjau alih-alih mengizinkan paksaan Tanggal atau Nomor secara diam-diam.

Apa yang tidak tercakup di sini — mengonversi JSON kembali ke TOML idiomatis dengan pengelompokan header yang masuk akal, yang melibatkan pilihan gaya yang tidak ditentukan sepenuhnya oleh aturan

JSON-to-TOML didukung untuk objek root, tetapi tidak membuat ulang pilihan atau komentar penulis idiomatik. Kunci bernilai nol dihilangkan; null di dalam array menjadi string kosong untuk mempertahankan posisi. Array root, skalar, atau null ditolak karena dokumen TOML harus berupa tabel.

Perilaku tersebut mengoreksi implikasi garis besar bahwa konversi terbalik berada di luar cakupan. Konverter menulis TOML, namun kesetiaan gaya tidak dapat dijanjikan. Perbedaannya penting: serialisasi yang didukung tidak sama dengan memulihkan file sumber byte demi byte atau memilih tata letak yang disukai pengelola.

Penulisan JSON kembali ke TOML didukung, namun komentar, tipe tanggal-waktu, dan gaya penulis tidak dikembalikan

Baca header TOML sebagai jalur dan tanda kurung ganda sebagai operasi penambahan. Tampilan JSON berguna untuk menelusuri pohon yang dihasilkan, sementara peringatan mengekspos waktu dan bilangan bulat lebar yang melewati batas tipe. Jangan panggil operasi lossless ketika peringatan muncul.

Untuk migrasi konfigurasi, simpan yang asli di samping keluaran yang dikonversi. Verifikasi nilainya terlebih dahulu, lalu edit organisasi TOML untuk pembaca dan alat target. Konverter sintaks melakukan langkah parse-dan-tulis mekanis; ia tidak dapat memutuskan pengelompokan spesifik proyek, kunci yang diterima, atau apakah aplikasi mendukung file tersebut.

Perbandingan terakhir harus memisahkan tiga pertanyaan yang mudah dikaburkan. Pertama, apakah nilai-nilai yang diurai bertahan? Kedua, apakah tipe khusus TOML apa pun menjadi string JSON atau ada null yang hilang? Ketiga, apakah TOML yang baru diserialkan diatur sedemikian rupa sehingga pengelola dapat memahaminya? Dua yang pertama dapat diperiksa berdasarkan nilai dan peringatan; yang ketiga membutuhkan tinjauan manusia. Memisahkan pemeriksaan tersebut akan mencegah serialisasi yang valid secara teknis disebut sebagai migrasi yang setia ketika jenis atau struktur pembuatnya berubah.