Memigrasikan konfigurasi JSON ke TOML: apa yang diubah dan apa yang dibutuhkan manusia

Era setup.cfg dan settings.json telah berakhir — sebuah proyek yang menggabungkan konfigurasi menjadi pyproject.toml dan blok JSON yang perlu dipindahkan

Proyek terkadang menggabungkan pengaturan ke dalam satu file TOML, namun repositori tidak dapat mendukung klaim garis besar bahwa “era telah berakhir.” Tugas praktisnya lebih sempit: pindahkan objek berbentuk JSON ke dalam tabel TOML, periksa kerugian, lalu verifikasi bahwa aplikasi target benar-benar mengenali kunci yang dihasilkan.

ToolAcre memerlukan objek root untuk keluaran TOML. Array root, string, angka, Boolean, atau null ditolak karena dokumen TOML adalah tabel. Pemeriksaan bentuk awal tersebut mencegah pembungkus yang ditemukan terlihat seperti konfigurasi yang disetujui aplikasi.

Konsolidasi konfigurasi adalah pilihan proyek, bukan tujuan universal dari format lama

Konverter membuktikan mekanika konkret: TOML memiliki tabel, array, dan nilai skalar; penulisnya mengubah objek bersarang menjadi struktur TOML yang valid. Ia juga tidak memiliki null dan menggunakan sintaks yang berbeda dari kurung kurawal JSON. Klaim mengenai preferensi ekosistem atau keunggulan desain memerlukan sumber di luar file implementasi ini.

Komentar adalah salah satu alasan pengelola lebih memilih TOML yang ditulis, namun masukan JSON tidak berisi apa pun untuk diteruskan. Dokumen yang dihasilkan adalah serialisasi nilai awal. Penjelasan manusia dan organisasi spesifik proyek harus ditambahkan setelahnya.

Apa yang dibuktikan oleh konverter ini tentang TOML daripada advokasi format umum

String, bilangan terbatas, boolean, objek bersarang, dan array yang didukung oleh smol-toml dikonversi secara mekanis. Array objek bisa menjadi array tabel; objek bersarang bisa menjadi header tabel. Unicode dan escape baris baru bertahan dalam pengujian bolak-balik untuk nilai biasa.

TOML aturan array dapat menolak bentuk yang tidak dapat diungkapkan oleh penulisnya, dan nama kesalahan yang gagal daripada memaksa secara diam-diam. Memanggil semua array menjadi homogen terlebih dahulu akan menyederhanakan perilaku pengujian ketergantungan, yang bahkan membaca array heterogen. Gunakan konversi aktual sebagai gerbangnya.

Yang dikonversi secara mekanis, termasuk array yang diterima penulis TOML

Null tidak memiliki representasi TOML. Properti objek yang berisi null dihilangkan dan dicantumkan dalam peringatan. Null di dalam array menjadi string kosong sehingga indeks selanjutnya tidak bergeser; pengganti itu juga disebutkan namanya. Tidak ada hasil yang mempertahankan nilai aslinya.

Putuskan apa arti null sebelum menerima perubahan apa pun. Ini mungkin berarti mewarisi default, menghapus bidang secara eksplisit, atau tidak ada nilai yang diberikan. Menghapus kunci atau mengganti teks kosong dapat mengubah semantik aplikasi, jadi selesaikan dengan model konfigurasi tujuan yang terdokumentasi.

Jika gaya memerlukan bantuan manusia — memilih antara header [tabel], tombol bertitik, dan tabel sebaris, serta mengelompokkan kunci terkait sehingga file dapat dibaca dengan baik

Pohon tersebut tidak menyatakan apakah pengelola lebih memilih `[tool.linter]`, kunci bertitik, atau tabel sebaris. Serializer memilih sintaks yang valid, sementara manusia memilih pengelompokan yang memperjelas kepemilikan dan opsi terkait. Kunci pengurutan dapat membuat keluaran bersifat deterministik tetapi dapat memisahkan konsep-konsep yang dimiliki bersama.

Pertahankan perbedaan kecil dan tambahkan komentar setelah nilai diverifikasi. Mengonversi TOML kembali ke JSON nanti tidak dapat memulihkan komentar atau ejaan tabel yang dipilih. Gaya adalah informasi yang ditulis di luar model nilai biasa.

Contoh praktis: konfigurasi JSON linter ke TOML — mengonversi, menyelesaikan dua nilai null, dan mengelompokkan ulang hasilnya di bawah header [tool.linter]

Konversi `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`. Objek root diterima. `preview` dihilangkan; anggota array null menjadi string kosong; peringatan menyebutkan kedua jalur. Objek bersarang yang tersisa diserialkan di bawah tabel TOML yang dipilih oleh penulis.

Sebelum menyimpan, putuskan apakah pratinjau harus salah, tidak ada, atau nilai terdokumentasi lainnya, dan apakah entri kecualikan yang kosong valid. Kemudian kelompokkan kembali dan beri komentar pada tabel tersebut untuk pembaca. Contoh ini menunjukkan mengapa konversi bersifat mekanis sedangkan migrasi bersifat semantik.

Apa yang tidak tercakup dalam hal ini — apakah alat target benar-benar membaca TOML, dan nama kunci spesifiknya, yang hanya dapat diketahui oleh dokumentasinya kepada Anda

File TOML yang valid tidak membuktikan bahwa alat membaca TOML, mengenali bagian tersebut, atau menafsirkan kunci seperti konsumen JSON yang lama. Periksa dokumentasi target saat ini dan jalankan perintah validasi atau uji coba sendiri. ToolAcre tidak pernah mengimpor skema aplikasi.

Kurma juga patut mendapat perawatan dalam arah sebaliknya. TOML-nilai temporal asli menjadi string saat dibaca ke JSON, jadi perjalanan pulang pergi kemudian mengutipnya. Rantai migrasi yang melintasi kedua arah tidak bisa disebut lossless.

Kesimpulan: konversi terlebih dahulu, lalu edit agar mudah dibaca — dan bagaimana panel konverter Sintaks melakukan bagian mekanis di browser Anda

Konversikan terlebih dahulu untuk mengungkap ketidakcocokan mekanis, lalu edit untuk semantik dan keterbacaan. Simpan yang asli, tinjau setiap peringatan dan uji dengan target sebenarnya. Penanganan nol dan bentuk akar adalah batasan yang sulit; organisasi tabel adalah keputusan desain manusia.

Konverter sintaks menghilangkan pekerjaan sintaksis yang berulang tanpa menciptakan pengetahuan aplikasi. Pembagian tersebut membuat keluarannya berguna: struktur yang dihasilkan mesin untuk ditinjau, diikuti dengan pilihan yang disengaja jika format atau alatnya tidak sesuai.

Simpan catatan migrasi untuk setiap peringatan yang Anda terima. Jika null menjadi tidak ada, nyatakan default tujuan yang membuat ketidakhadiran menjadi benar. Jika anggota array null menjadi teks kosong, jelaskan mengapa indeks penting dan mengapa teks kosong valid. Jika penulis menolak array campuran, desain ulang nilai tersebut alih-alih memaksakannya secara pribadi. Keputusan-keputusan ini merupakan catatan migrasi yang tahan lama; TOML yang dihasilkan saja tidak dapat menjelaskannya kepada pengelola berikutnya.