A powerful and feature-rich JSON library for MQL5, designed to bring a modern development experience similar to Python/JS - MetaTrader 5 için kütüphane

1. Genel Bakış

MQL5 JSON Kütüphanesi, MQL5 ortamında JSON verilerini ayrıştırmak, işlemek ve serileştirmek için özel olarak tasarlanmış güçlü, zengin özelliklere sahip bir kütüphanedir. MQL5'teki JSON işleme deneyimini JavaScript ve Python gibi modern programlama dilleriyle karşılaştırılabilir hale getirmeyi amaçlayan basit ve sezgisel bir Belge Nesne Modeli (DOM) API'si sağlar.

Bu kütüphane, basit EA konfigürasyonlarının okunmasından sistemler arasında karmaşık gerçek zamanlı veri alışverişine kadar çok çeşitli görevleri yerine getirebilir. Ana işlevleri ve özellikleri şunlardır:

• --- Ayrıştırma ve Oluşturma ---
• Dizeden veya Dosyadan Yükle: JSON metnini güvenilir bir şekilde işlenebilir bellek içi nesnelere ayrıştırır ( JsonParse , JsonFromFile ).
• Sıfırdan Oluştur un: JsonNewObject ve JsonNewArray gibi özlü API'leri kullanarak programlı olarak kolayca yeni JSON nesneleri ve dizileri oluşturun.

• Esnek Ayrıştırıcı: İsteğe bağlı olarak, çeşitli veri kaynaklarıyla uyumluluğu artırmak için kod yorumları ve sondaki virgüller gibi JSON5'in bazı standart dışı özelliklerini destekler.

• --- Manipülasyon ve Erişim ---

• Sezgisel DOM Çaprazlama: Python sözlüğü veya JavaScript nesnesi kullanır gibi, anahtarlar ( node["key"] ) ve indeksler ( node[0] ) ile sezgisel sözdizimi kullanarak verilere erişin.

• Güvenli Tip Dönüşümü: AsInt(defaultValue) ve AsString(defaultValue) gibi varsayılan değerlere sahip bir dizi yöntem sağlayarak, tür uyuşmazlıkları veya var olmayan yollar nedeniyle program çökmeleri konusunda endişelenmeden bir düğümden istenen türdeki verileri güvenli bir şekilde çıkarmanıza olanak tanır.

• Dinamik Değişiklik: JSON nesnelerindeki anahtar-değer çiftlerini ve dizilerdeki öğeleri serbestçe ekleyin, güncelleyin veya silin ( Set , Add , Remove ).

  --- Gelişmiş Sorgulama ve İşleme ---

• Güçlü Sorgu Motoru: JSON Pointer (RFC 6901, doğrudan yol erişimi için) ve JSONPath (karmaşık ve bulanık sorgular için) için yerleşik destek, derin iç içe geçmiş, karmaşık yapılardan bir veya daha fazla veri düğümünün toplu olarak veya hassas bir şekilde verimli bir şekilde çıkarılmasını sağlar.

• Düşük Bellekli Akış Ayrıştırma: Gigabayt ölçekli, devasa JSON dosyalarını işlemek için JsonStreamParser sağlar. Dosyanın tamamını belleğe yüklemeden olay akışı tarzında dosyayı belirteç belirte okur, böylece en üst düzeyde bellek verimliliği elde eder.

• Yardımcı İşlevler: Belge klonlama (.Clone()) ve derin birleştirme ( JsonMerge) gibi gelişmiş özellikler sunarak "varsayılan yapılandırma" ile "kullanıcı yapılandırmasını" birleştirme gibi yaygın karmaşık görevleri büyük ölçüde basitleştirir.

  --- Sağlamlık ve Güvenlik ---

• Otomatik Bellek Yönetimi: RAII (Resource Acquisition Is Initialization) tasarım modelini benimser. JsonDocument, tüm düğümlerinin yaşam döngüsünü yönetmekten sorumludur. Geliştiricilerin herhangi bir JSON öğesini manuel olarak yenilemesine / silmesine gerek yoktur, bu da bellek sızıntısı riskini temelde ortadan kaldırır.

• Belgeler Arası İşlem Güvenliği: Farklı JsonDocument örnekleri arasında bir düğüm atarken, kütüphane otomatik olarak güvenli bir derin kopyalama (Clone) gerçekleştirerek sarkan işaretçileri ve kazara veri bozulmasını önler.
• Detaylı Hata Raporlama: Ayrıştırma başarısız olduğunda, JsonError nesnesi hata satır numarası, sütun numarası ve bağlam dahil olmak üzere ayrıntılı bilgi sağlayarak hızlı sorun teşhisini kolaylaştırır.

2. Temel Kavramlar ve Bellek Yönetimi

[!!] 2.1 İsim Alanı - Projenizi Entegre Etmenin Anahtarı [!!] En Önemli İpucu: Bu kütüphanedeki tüm sınıflar (örn. JsonDocument , JsonNode ) ve global fonksiyonlar (örn. JsonParse ) MQL5_Json adlı bir isim alanı içinde kapsüllenmiştir.

**Nasıl Doğru Kullanılır:** - **Başlık Dosyalarında (.mqh)**: MQL5, başlık dosyalarının genel kapsamında `isim alanı kullanımına` izin vermez. **Bu nedenle, tam nitelikli adlar kullanmalısınız**. Bu, çok dosyalı projelerde tek güvenilir yoldur. Yanlış: `JsonDocument doc;` Doğru: `MQL5_Json::JsonDocument doc;` - **Ana Program Dosyalarındaki (.mq5)** İç Fonksiyonlar: Kolaylık sağlamak için, işlevlerin içinde `using namespace MQL5_Json;` kullanabilirsiniz, ancak örneklerin genelliğini sağlamak için, bu kılavuzdaki tüm kodlar tam nitelikli ad yaklaşımını kullanacaktır . **Eğer `'JsonNode' - türsüz bildirim` derleme hatasıyla karşılaşırsanız,** ** bunun nedeni neredeyse her zaman türlere ve fonksiyonlara `MQL5_Json::` ön ekini** ** eklemeyi unutmuş olmanızdır.**

[!!] 2.2 Bellek Yönetim Modeli JsonDocument verilerin sahibidir; JsonNode sadece bir görünümdür.

[!!] 2.3 MQL5'te Nesne Geçişi MQL5, fonksiyon argümanı olarak geçirilen tüm sınıf nesnelerinin (JsonNode dahil ) referansla (& kullanılarak) geçirilmesini gerektirir. Yanlış: void myFunction(MQL5_Json::JsonNode node) Doğru: void myFunction(MQL5_Json::JsonNode &node