Mengapa TOML ada: tujuan desain di balik Cargo.toml dan pyproject.toml

Tiga format konfigurasi dalam satu repositori — JSON untuk editor, YAML untuk CI, TOML untuk build, dan pertanyaan mengapa repositori ketiga ada

Repositori dapat menggunakan JSON, YAML dan TOML untuk permukaan konfigurasi yang berbeda. ToolAcre tidak dapat menjelaskan setiap pilihan proyek, namun konversi membuat perbedaan struktural menjadi nyata: TOML dimulai sebagai tabel akar, menggunakan header dan jalur titik-titik untuk bersarang, dan membawa nilai temporal tidak tersedia di JSON.

Memuat contoh daripada berdebat berdasarkan penampilan. Tabel bertumpuk menjadi objek, tabel kurung ganda menjadi array, dan komentar hilang ketika nilai memasukkan JSON. Batasan yang diamati tersebut lebih dapat ditindaklanjuti dibandingkan klaim umum bahwa satu sintaksis secara inheren lebih baik.

Tujuan desain — semantik yang minimal dan jelas, mudah dibaca, dan format yang dipetakan secara jelas ke tabel hash

Parser yang dikirim memperlihatkan semantik tabel yang jelas: header adalah jalur, tugas milik tabel aktif, dan token skalar telah menentukan tipe TOML. String tidak diketik hanya karena isinya terlihat seperti tanggal; sintaks temporal aktual menghasilkan objek tanggal yang ToolAcre sengaja dinormalisasi.

Repositori ini tidak mencantumkan sumber pembuat format, tanggal, atau filosofi yang disebutkan, sehingga artikel ini menghindari penyajian sejarah yang diingat sebagai fakta. Ini melaporkan perilaku yang diuji di smol-toml dan lapisan normalisasi konverter itu sendiri.

Properti desain yang dapat diamati dalam parser yang dikirimkan, tanpa klaim asal tanpa sumber

TOML tidak memiliki null, dan root dokumennya tidak boleh berupa array atau skalar. Ia tidak menyediakan jangkar atau alias bergaya YAML dalam pemetaan ini. Komentar ada di TOML yang ditulis tetapi tidak disimpan oleh pengurai nilai dan oleh karena itu tidak dapat bertahan dalam konversi melalui JSON atau YAML.

Nilai kosong yang tidak dikutip mengikuti tata bahasa TOML, bukan pemilihan skema YAML. Parser menerima nilai yang diketik atau melaporkan TOML yang tidak valid dengan informasi posisi. ToolAcre tidak menambahkan mode string implisit untuk tugas yang formatnya salah.

Apa yang dikecualikan atau ditangani secara berbeda oleh model nilai yang didukung

Model ini mencakup string, bilangan bulat bertanda, float, boolean, empat jenis temporal, array, dan tabel. Array tabel mengekspresikan rekaman objek yang berulang. Bilangan bulat bertanda besar di luar 2^53 menjadi string desimal pada konversi sehingga JavaScript tidak membulatkannya secara diam-diam.

Nilai temporal menjadi teks berorientasi sumber untuk offset tanggal-waktu, tanggal-waktu lokal, tanggal lokal atau waktu lokal. Peringatan mempertahankan jenisnya dalam bentuk prosa, tetapi JSON hanya menerima sebuah string. Oleh karena itu, mengonversi kembali mengutipnya dan kehilangan tipe TOML asli.

Adopsi — Kargo dari masa awal Rust, PEP 518 memilih pyproject.toml, dan spesifikasi 1.0.0 di 2021

Adopsi kargo dan proyek py adalah klaim historis dan ekosistem yang memerlukan sumber yang tidak ada dalam repositori konverter. Mereka sengaja dihilangkan di sini. Jalur atau nama file bukan merupakan bukti kronologi, rilis spesifikasi, atau keputusan standar.

Pertanyaan operasionalnya adalah apakah alat target membaca TOML dan tabel mana yang diharapkan. Periksa dokumentasi terkini alat tersebut. Konverter sintaksis mengetahui pemetaan sintaksis dan nilai, bukan kontrak konfigurasi manajer paket.

Riwayat adopsi ekosistem dihilangkan tanpa sumber repositori

Penyusunan yang dalam bisa lebih sulit untuk dipindai karena konteks tabel tetap ada di seluruh baris, sementara susunan tabel yang besar menyebarkan satu daftar logis ke seluruh header yang berulang. JSON membuat hierarki lengkap menjadi eksplisit tetapi menambahkan tanda kurung kurawal dan tanda kutip. Tidak ada representasi yang menghilangkan kompleksitas dari konfigurasi yang mendasarinya.

Batas parser bertumpu pada 100 dan panjang sumber pada dua juta karakter. Itu adalah batasan penolakan, bukan pernyataan tentang ukuran konfigurasi ideal atau batasan TOML universal.

Apa yang tidak tercakup di sini — TOML pilihan parser di setiap bahasa, dan sifat hanya baca dari beberapa implementasi perpustakaan standar

Pilihan parser di setiap bahasa berada di luar cakupan, begitu pula kemampuan menulis perpustakaan standar. ToolAcre menggunakan smol-toml secara dinamis dan menggabungkan kesalahannya. Implementasi lain dapat memformat keluaran valid secara berbeda atau mengekspos API lain sambil mewakili data yang sama.

Gunakan perlengkapan lintas alat untuk nilai temporal, bilangan bulat besar, array, dan kunci titik ketika interoperabilitas penting. File yang diterima di sini tidak secara otomatis diterima oleh setiap konsumen TOML.

Kesimpulan: TOML dianggap sebagai format konfigurasi — dan bagaimana panel Konverter Sintaks memungkinkan Anda melihat file JSON atau YAML dalam bentuk tersebut

TOML dikemukakan dengan cara yang dapat diamati: akar tabel, nilai yang diketik secara eksplisit, jenis temporal asli, dan tanpa nol. Konversi mengungkap pilihan-pilihan tersebut dan ketidaksesuaiannya dengan target berbentuk JSON tanpa memerlukan mitos asal usul.

Gunakan panel untuk memeriksa pohon dan mengidentifikasi peringatan. Kemudian kembali ke skema tujuan dan buat tata letak tabel yang akan dipertahankan manusia. Konverter memberikan bukti tentang nilai, bukan keputusan tentang preferensi format.

Disiplin yang sama berlaku ketika TOML hanyalah pandangan perantara. Pertahankan sumbernya, bandingkan nilai yang dinormalisasi, dan catat setiap konversi temporal atau bilangan bulat lebar sebelum menilai keterbacaan. Tata letak tabel yang ringkas masih bisa menyembunyikan tipe yang diubah, sementara susunan tabel yang panjang bisa sama persis secara semantik. Pilihan format harus mengikuti kontrak konfigurasi dan alur kerja pemeliharaan, bukan kerapian visual dari satu sampel yang dihasilkan.