TOML'dan JSON'a Dönüştürücü

TOML, yapılandırma dosyaları için tasarlanmış, okunması kolay bir biçimdir. Adı, açık ve minimal bir dil olma hedefinden gelir: her satır bir anahtar-değer çifti tanımlar, köşeli parantezli başlıklar bölümleri ayırır. INI dosyalarının tanıdık görünümünü, iyi tanımlanmış türler ve net kurallarla birleştirir.

Günümüzde iki büyük ekosistemin varsayılan yapılandırma biçimidir. Rust projelerinin kalbindeki Cargo.toml, bağımlılıkları ve derleme ayarlarını tutar. Python dünyasında pyproject.toml, paketleme ve araç yapılandırmasının standart adresi haline geldi; kod biçimlendiricilerden test araçlarına kadar birçok araç ayarlarını bu dosyadan okur. Hugo gibi statik site üreteçleri ve giderek artan sayıda geliştirici aracı da TOML'ı destekler.

Sorun, bu dosyaları programatik işlemek istediğinizde başlar. Her dilde olgun bir TOML ayrıştırıcısı bulunmayabilir; buna karşılık JSON'u okuyamayan araç yok gibidir. Bir CI betiğinin pyproject.toml içinden sürüm numarası çekmesi, bir gösterge panelinin Cargo.toml bağımlılıklarını listelemesi ya da sizin bir yapılandırmayı hızla incelemeniz gerektiğinde, dosyayı JSON'a çevirmek en kestirme yoldur.

TOML'dan JSON'a Dönüştürücü tam bu boşluğu doldurur: TOML dosyanızı yapıştırırsınız, aynı verinin JSON karşılığını anında alırsınız. Araç tarayıcıda çalıştığı için özel jetonlar veya iç sunucu adresleri içeren yapılandırmalarınız cihazınızdan çıkmaz.

TOML'ın her yapısının JSON'da net bir karşılığı vardır; dönüştürücü bu eşlemeyi kurallı biçimde uygular.

En çok soru yaratan yapı tablo dizileridir. TOML'da [[sunucu]] başlığını iki kez kullanmak, JSON tarafında sunucu anahtarı altında iki nesnelik bir dizi üretir. Noktalı anahtarlar da benzer biçimde açılır: veritabani.baglanti.port = 5432 satırı, üç seviye iç içe nesneye dönüşür.

Türler büyük ölçüde birebir taşınır: dizeler, tam sayılar, ondalıklar, mantıksal değerler ve diziler JSON'un yerleşik türlerine oturur. Tek istisna tarih-saat değerleridir; TOML bunları yerleşik tür olarak tanır, JSON'da ise doğal karşılıkları olmadığından ISO 8601 biçimli dizelere çevrilirler. Uygulamanız bu alanları tarih olarak işleyecekse dizeyi kendi tarafında ayrıştırması gerekir.

Çok satırlı TOML dizeleri, satır sonları \n kaçışıyla korunarak tek JSON dizesi olur. Altı çizgiyle gruplanmış sayılar, örneğin 1_000_000, düz sayıya çevrilir. Sonuç, kaynaktaki bilgiyi eksiksiz taşıyan, herhangi bir JSON aracının işleyebileceği standart bir belgedir.

Aracın kullanımı üç adımdan oluşur:

1. TOML içeriğinizi giriş alanına yapıştırın veya dosyanızı yükleyin.
2. Çıktı ayarlarını gözden geçirin; girintili JSON okunaklıdır, tek satır çıktı ise betiklere gömmek için uygundur.
3. Üretilen JSON'u kopyalayın ya da dosya olarak indirin.

Girdi geçerli TOML değilse dönüştürücü hatanın satırını ve nedenini bildirir. En sık karşılaşılan sorunlar şunlardır: aynı anahtarın iki kez tanımlanması, kapanmamış tırnak veya köşeli parantez ve tablo başlığının yanlış yerde açılması. TOML'da aynı tabloyu iki kez tanımlamak kurallara aykırıdır; ayrıştırıcı bunu hata olarak raporlar, sessizce birleştirmez.

Çıktıyı aldıktan sonraki adımlar genellikle şöyle ilerler: JSON'u bir betiğe veya API çağrısına gömmeden önce JSON biçimlendirici ile son bir kez doğrulayıp girintisini düzenleyebilirsiniz. Elinizdeki yapılandırma YAML biçimindeyse aynı işi YAML'dan JSON'a dönüştürücü görür; iki araç aynı mantıkla çalıştığı için ekipçe tutarlı bir akış kurmak kolaydır.

Ters yönde gitmek, yani elinizdeki JSON veriyi TOML yapılandırmasına çevirmek istediğinizde JSON'dan TOML'a dönüştürücü kullanılır. Bu, JSON üreten bir araçtan aldığınız ayarları pyproject.toml gibi bir dosyaya taşırken pratik bir kısayoldur.

Veri düzeyinde dönüşüm kayıpsızdır: tüm anahtarlar, değerler ve iç içe yapılar JSON'a eksiksiz taşınır. Yine de üç konuda beklentinizi doğru kurmak gerekir.

Birincisi yorumlar. TOML dosyaları diyez işaretiyle başlayan açıklamalara izin verir ve iyi yazılmış bir yapılandırmada bu yorumlar değerlidir. JSON yorum desteklemediği için bu satırlar çıktıya taşınamaz. Yorumlu özgün dosyayı kaynak olarak saklamak, JSON'u türetilmiş kopya olarak görmek en sağlıklı yaklaşımdır.

İkincisi tarih-saat türü. TOML'ın yerleşik tarih değerleri JSON'da ISO 8601 dizesine iner. Bilgi kaybolmaz ama tür bilgisi kaybolur: 2024-05-15T09:30:00+03:00 artık bir dizedir ve tarih karşılaştırması yapacak kodun onu ayrıştırması gerekir.

Üçüncüsü anahtar sırası ve stil. TOML'da tabloları istediğiniz sırayla, noktalı anahtar veya başlık stiliyle yazabilirsiniz; JSON çıktısı bu stil tercihlerini değil yalnızca yapıyı yansıtır. Aynı veriyi tanımlayan iki farklı TOML yazımı, birebir aynı JSON'u üretir. Bu çoğu zaman istediğiniz şeydir; ancak dosyayı geri TOML'a çevirdiğinizde özgün düzenin aynen geri gelmeyeceğini bilin.

Özetle: uygulamanızın okuyacağı veri açısından dönüşüm güvenlidir; insanlar için yazılmış ayrıntılar, yani yorumlar ve biçimsel düzen, JSON'un tasarımı gereği geride kalır.

Üç biçim de aynı temel yapıları taşıyabilir; seçim, dosyayı kimin yazıp kimin okuyacağına bağlıdır.

TOML, elle yazılan yapılandırma dosyalarında parlar. Sözdizimi bağışlayıcıdır, yorum destekler ve girinti hatası diye bir derdi yoktur; bölüm başlıkları uzun dosyalarda yönü kolay bulmanızı sağlar. Buna karşılık derin iç içe yapılarda başlıklar hantallaşır; beş seviye derinliğindeki bir yapı TOML'da JSON'dakinden daha zor okunur.

JSON, makineler arası veri alışverişinin standardıdır. Her dilde ayrıştırıcısı vardır, kuralları katıdır ve belirsizliğe yer bırakmaz. Yorum desteklememesi ve her anahtarın tırnaklanması, onu elle bakım yapılan yapılandırmalar için yorucu kılar; asıl gücü programların ürettiği ve tükettiği veridedir.

YAML, insan okunabilirliğinde en ileri noktadır ve Kubernetes ile CI dünyasının dilidir; ancak girintiye duyarlılığı ve esnek tür çıkarımı, kalabalık ekiplerde sürpriz hatalara açıktır.

Pratik kural şudur: proje yapılandırması elle yazılıyorsa TOML veya YAML seçin; veri bir programdan diğerine akıyorsa JSON kullanın. Bu araç seti de tam bu geçişler için vardır: TOML'dan JSON'a Dönüştürücü yapılandırmayı veri hattına bağlar, ters yönlü dönüştürücü JSON çıktısını tekrar yapılandırmaya çevirir. Biçim seçimini dogma değil, bağlama göre verilmiş bir karar olarak görmek en sağlıklısıdır.