Menghijrahkan konfigurasi JSON kepada TOML: perkara yang menukar dan perkara yang memerlukan manusia

Era setup.cfg dan settings.json akan tamat — konfigurasi penyatuan projek menjadi pyproject.toml dan blok JSON yang perlu dialihkan

Projek kadangkala menyatukan tetapan ke dalam satu fail TOML, tetapi repositori tidak dapat menyokong dakwaan garis besar bahawa "era sedang berakhir". Tugas praktikal adalah lebih sempit: alihkan objek berbentuk JSON ke dalam jadual TOML, periksa kerugian, kemudian sahkan bahawa aplikasi sasaran benar-benar mengenali kunci yang terhasil.

ToolAcre memerlukan objek akar untuk output TOML. Tatasusunan akar, rentetan, nombor, Boolean atau null ditolak kerana dokumen TOML ialah jadual. Semakan bentuk awal itu menghalang pembungkus yang dicipta daripada kelihatan seperti konfigurasi yang diluluskan aplikasi.

Penyatuan konfigurasi ialah pilihan projek, bukan penghujung universal bagi format lama

Penukar membuktikan mekanik konkrit: TOML mempunyai jadual, tatasusunan dan nilai skalar; penulisnya menukar objek bersarang menjadi struktur TOML yang sah. Ia juga tidak mempunyai null dan menggunakan sintaks yang berbeza daripada pendakap JSON. Tuntutan tentang keutamaan ekosistem atau keunggulan reka bentuk memerlukan sumber di luar fail pelaksanaan ini.

Komen ialah satu sebab penyelenggara mungkin lebih suka TOML yang diarang, namun input JSON tidak mengandungi satu pun untuk dibawa. Dokumen yang dijana ialah siri nilai permulaan. Penjelasan manusia dan organisasi khusus projek mesti ditambah selepas itu.

Perkara yang dibuktikan oleh penukar ini tentang TOML dan bukannya advokasi format umum

Rentetan, nombor terhingga, boolean, objek bersarang dan tatasusunan yang disokong oleh smol-toml menukar secara mekanikal. Tatasusunan objek boleh menjadi tatasusunan jadual; objek bersarang boleh menjadi pengepala jadual. Unicode dan baris baharu yang terlepas bertahan dalam perjalanan pergi dan balik yang diuji untuk nilai biasa.

Peraturan tatasusunan TOML boleh menolak bentuk yang tidak dapat diungkapkan oleh penulisnya, dan ralat itu menamakan kegagalan itu daripada memaksa secara senyap. Memanggil semua tatasusunan homogen terlebih dahulu akan meringkaskan tingkah laku yang diuji kebergantungan, yang malah membaca tatasusunan heterogen. Gunakan penukaran sebenar sebagai pintu masuk.

Perkara yang ditukar secara mekanikal, termasuk tatasusunan yang diterima oleh penulis TOML

Null tidak mempunyai perwakilan TOML. Sifat objek yang memegang null ditinggalkan dan disenaraikan dalam amaran. Nol di dalam tatasusunan menjadi rentetan kosong supaya indeks kemudiannya tidak beralih; pengganti itu juga dinamakan. Kedua-dua hasil tidak mengekalkan nilai asal.

Tentukan maksud null sebelum menerima mana-mana perubahan. Ini mungkin bermakna mewarisi lalai, mengosongkan medan secara eksplisit atau tiada nilai yang dibekalkan. Memadam kekunci atau menggantikan teks kosong boleh mengubah semantik aplikasi, jadi selesaikannya dengan model konfigurasi yang didokumenkan destinasi.

Di mana gaya memerlukan manusia — memilih antara pengepala [jadual], kekunci bertitik dan jadual sebaris, dan mengumpulkan kunci berkaitan supaya fail dibaca dengan baik

Pokok itu tidak menyatakan sama ada penyelenggara lebih suka `[tool.linter]`, kekunci bertitik atau jadual sebaris. Penyeri bersiri memilih sintaks yang sah, manakala manusia memilih kumpulan yang menjadikan pemilikan dan pilihan yang berkaitan jelas. Kekunci pengisihan boleh menjadikan output deterministik tetapi boleh memisahkan konsep yang dimiliki bersama.

Kekalkan perbezaan kecil dan tambah ulasan selepas nilai disahkan. Menukarkan TOML kembali kepada JSON kemudian tidak boleh memulihkan ulasan tersebut atau ejaan jadual yang dipilih. Gaya ialah maklumat yang diarang di luar model nilai biasa.

Contoh yang berjaya: konfigurasi JSON linter kepada TOML — menukar, menyelesaikan dua nilai nol dan mengumpulkan semula hasil di bawah pengepala [tool.linter]

Tukar `{"tool":{"linter":{"lineLength":100,"preview":null,"exclude":["dist",null]}}}`. Objek akar diterima. `preview` ditinggalkan; ahli tatasusunan null menjadi rentetan kosong; amaran menamakan kedua-dua laluan. Objek bersarang yang tinggal disirikan di bawah TOML jadual yang dipilih oleh penulis.

Sebelum menyimpan, tentukan sama ada pratonton harus palsu, tiada atau nilai terdokumentasi lain dan sama ada entri kecualikan kosong adalah sah. Kemudian kumpulkan semula dan ulas jadual untuk pembaca. Contoh menunjukkan sebab penukaran adalah mekanikal manakala migrasi adalah semantik.

Perkara ini tidak meliputi — sama ada alat sasaran benar-benar membaca TOML dan nama kunci khususnya, yang sahaja dokumentasinya boleh memberitahu anda

Fail TOML yang sah tidak membuktikan bahawa alat membaca TOML, mengecam bahagian atau mentafsir kekunci seperti pengguna JSON lama. Semak dokumentasi sasaran semasa dan jalankan pengesahan sendiri atau arahan larian kering. ToolAcre tidak pernah mengimport skema aplikasi.

Kurma juga patut dijaga dalam arah sebaliknya. TOML-nilai temporal asli menjadi rentetan apabila dibaca ke dalam JSON, jadi perjalanan pergi balik kemudian memetiknya. Rantaian penghijrahan yang melintasi kedua-dua arah tidak boleh dipanggil tanpa kerugian.

Bawa pulang: tukar dahulu, kemudian edit untuk kebolehbacaan — dan cara panel penukar Sintaks melakukan bahagian mekanikal dalam pelayar anda

Tukar dahulu untuk mendedahkan ketidakserasian mekanikal, kemudian edit untuk semantik dan kebolehbacaan. Simpan yang asal, semak setiap amaran dan uji dengan sasaran sebenar. Pengendalian null dan bentuk akar adalah sempadan yang keras; organisasi meja adalah keputusan reka bentuk manusia.

Penukar sintaks mengalih keluar kerja sintaks berulang tanpa mencipta pengetahuan aplikasi. Bahagian itu menjadikan output berguna: struktur yang dihasilkan mesin untuk semakan, diikuti dengan pilihan yang disengajakan apabila format atau alat tidak bersetuju.

Simpan nota penghijrahan untuk setiap amaran yang anda terima. Jika nol menjadi ketiadaan, nyatakan lalai destinasi yang menjadikan ketidakhadiran betul. Jika ahli tatasusunan null menjadi teks kosong, terangkan mengapa indeks itu penting dan mengapa teks kosong itu sah. Jika penulis menolak tatasusunan bercampur, reka bentuk semula nilai itu dan bukannya memaksanya secara peribadi. Keputusan ini adalah rekod penghijrahan yang tahan lama; TOML yang dihasilkan sahaja tidak dapat menjelaskannya kepada penyelenggara seterusnya.