Sebab TOML wujud: matlamat reka bentuk di sebalik Cargo.toml dan pyproject.toml

Tiga format konfigurasi dalam satu repositori — JSON untuk editor, YAML untuk CI, TOML untuk binaan dan persoalan mengapa yang ketiga wujud

Repositori boleh menggunakan JSON, YAML dan TOML untuk permukaan konfigurasi yang berbeza. ToolAcre tidak dapat menerangkan setiap pilihan projek, tetapi penukaran menjadikan perbezaan struktur konkrit: TOML bermula sebagai jadual akar, menggunakan pengepala dan laluan bertitik untuk bersarang dan membawa nilai temporal yang tidak tersedia dalam JSON.

Muatkan contoh daripada berhujah dari rupa. Jadual bersarang menjadi objek, jadual kurungan dua menjadi tatasusunan dan ulasan hilang apabila nilai memasuki JSON. Sempadan yang diperhatikan itu lebih boleh diambil tindakan daripada dakwaan generik bahawa satu sintaks sememangnya lebih baik.

Matlamat reka bentuk — semantik yang minimum, jelas, mudah dibaca dan format yang memetakan dengan jelas kepada jadual cincang

Penghurai yang dihantar mendedahkan semantik jadual yang jelas: pengepala ialah laluan, tugasan tergolong dalam jadual aktif dan token skalar telah menentukan jenis TOML. Rentetan tidak ditaip semata-mata kerana kandungannya kelihatan seperti tarikh; sintaks temporal sebenar menghasilkan objek tarikh yang ToolAcre dinormalisasi dengan sengaja.

Repositori tidak mendapatkan sumber pencipta format, tarikh atau falsafah yang dinyatakan, jadi artikel ini mengelak daripada membentangkan sejarah yang diingati sebagai fakta. Ia melaporkan tingkah laku yang diuji dalam smol-toml dan lapisan normalisasi penukar itu sendiri.

Sifat reka bentuk yang boleh diperhatikan dalam penghurai yang dihantar, tanpa tuntutan asal tidak bersumber

TOML tidak mempunyai null dan akar dokumennya tidak boleh menjadi tatasusunan atau skalar. Ia tidak menyediakan sauh atau alias gaya YAML dalam pemetaan ini. Komen wujud dalam TOML yang dikarang tetapi tidak dikekalkan oleh penghurai nilai dan oleh itu tidak dapat bertahan dalam penukaran melalui JSON atau YAML.

Nilai kosong yang tidak disebut mengikut tatabahasa TOML dan bukannya pemilihan skema YAML. Penghurai sama ada menerima nilai yang ditaip atau melaporkan TOML yang tidak sah dengan maklumat kedudukan. ToolAcre tidak menambah mod rentetan tersirat untuk tugasan yang salah bentuk.

Perkara yang dikecualikan atau dikendalikan oleh model nilai yang disokong secara berbeza

Model ini termasuk rentetan, integer bertanda, terapung, boolean, empat jenis temporal, tatasusunan dan jadual. Tatasusunan jadual menyatakan rekod objek berulang. Integer bertanda besar yang melebihi 2^53 menjadi rentetan perpuluhan pada penukaran supaya JavaScript tidak membundarkannya secara senyap.

Nilai sementara menjadi teks berorientasikan sumber untuk mengimbangi tarikh-masa, tarikh-masa tempatan, tarikh tempatan atau masa tempatan. Amaran itu mengekalkan jenis dalam prosa, tetapi JSON sahaja menerima rentetan. Oleh itu, menukar kembali memetiknya dan kehilangan jenis TOML asli.

Penerimaan — Kargo dari zaman terawal Rust, PEP 518 memilih pyproject.toml dan spesifikasi 1.0.0 dalam 2021

Penggunaan kargo dan projek pyprojek adalah tuntutan sejarah dan ekosistem yang memerlukan sumber yang tidak terdapat dalam repositori penukar. Mereka sengaja ditinggalkan di sini. Laluan atau nama fail bukan bukti untuk kronologi, keluaran spesifikasi atau keputusan standard.

Soalan operasi ialah sama ada alat sasaran membaca TOML dan jadual yang dijangkakan. Semak dokumentasi semasa alat itu. Penukar sintaks mengetahui sintaks dan pemetaan nilai, bukan kontrak konfigurasi pengurus pakej.

Sejarah penggunaan ekosistem ditinggalkan tanpa sumber repositori

Bersarang dalam boleh menjadi lebih sukar untuk diimbas kerana konteks jadual berterusan merentas baris, manakala tatasusunan besar jadual merebak satu senarai logik merentas pengepala berulang. JSON menjadikan hierarki lengkap jelas tetapi menambah pendakap dan petikan. Perwakilan tidak menghilangkan kerumitan daripada konfigurasi asas.

Hadapan parser bersarang pada 100 dan panjang sumber pada dua juta aksara. Itu adalah sempadan penolakan, bukan pernyataan tentang saiz konfigurasi ideal atau had TOML universal.

Perkara ini tidak meliputi — TOML pilihan penghurai dalam setiap bahasa dan sifat baca sahaja beberapa pelaksanaan perpustakaan standard

Pilihan penghurai dalam setiap bahasa adalah di luar skop, begitu juga dengan keupayaan menulis perpustakaan standard. ToolAcre menggunakan smol-toml secara dinamik dan membungkus ralatnya. Pelaksanaan lain boleh memformat output yang sah secara berbeza atau mendedahkan API lain sambil mewakili data yang sama.

Gunakan lekapan rentas alat untuk nilai temporal, integer besar, tatasusunan dan kekunci bertitik apabila saling kendali penting. Fail yang diterima di sini tidak diterima secara automatik oleh setiap pengguna TOML.

Bawa pulang: TOML berpendapat tentang format konfigurasi — dan cara panel penukar Sintaks membolehkan anda melihat mana-mana fail JSON atau YAML dalam bentuk itu

TOML diberi pendapat dalam cara yang boleh diperhatikan: punca jadual, nilai taip eksplisit, jenis temporal asli dan tiada nol. Penukaran mendedahkan pilihan tersebut dan ketidakserasiannya dengan sasaran berbentuk JSON tanpa memerlukan mitos asal usul.

Gunakan panel untuk memeriksa pokok dan mengenal pasti amaran. Kemudian kembali ke skema destinasi dan tulis susun atur jadual yang akan dikekalkan oleh manusia. Penukar membekalkan bukti tentang nilai, bukan keputusan tentang pilihan format.

Disiplin yang sama terpakai apabila TOML hanyalah pandangan pertengahan. Kekalkan sumber, bandingkan nilai ternormal dan perhatikan setiap penukaran temporal atau integer lebar sebelum menilai kebolehbacaan. Susun atur jadual padat masih boleh menyembunyikan jenis yang diubah, manakala tatasusunan jadual yang bertele-tele boleh tepat dari segi semantik. Pilihan format hendaklah mengikut kontrak konfigurasi dan aliran kerja penyelenggaraan, bukan kekemasan visual satu sampel yang dijana.