A powerful and feature-rich JSON library for MQL5, designed to bring a modern development experience similar to Python/JS - MetaTrader 5のためのライブラリ

1.概要

MQL5 JSONライブラリは、MQL5環境内でJSONデータを解析、操作、シリアライズするために特別に設計された、強力で機能豊富なライブラリです。シンプルで直感的なドキュメント・オブジェクト・モデル（DOM）APIを提供し、MQL5でのJSON処理のエクスペリエンスをJavaScriptやPythonのような最新のプログラミング言語に匹敵するものにすることを目指しています。

このライブラリは、単純なEA設定の読み取りからシステム間の複雑なリアルタイムデータ交換まで、幅広いタスクを処理することができます。主な機能と特徴は以下の通りです：

• --- 解析と作成
• 文字列またはファイルからのロード: JSONテキストを操作可能なインメモリオブジェクトに確実にパースします( JsonParse , JsonFromFile )。
• スクラッチからのビルド：JsonNewObject や JsonNewArray などの簡潔な API を使用して、新しい JSON オブジェクトや配列をプログラムで簡単に作成できます。

• 柔軟なパーサー：様々なデータソースとの互換性を高めるために、コードコメントや末尾のカンマなど、JSON5の非標準的な機能をオプションでサポートしています。

• --- 操作とアクセス ---

• 直感的な DOM トラバーサル：Python 辞書や JavaScript オブジェクトを使用するように、キー ( node["key"] ) とインデックス ( node[0] ) を使用した直感的な構文でデータにアクセスできます。

• 安全な型変換：AsInt(defaultValue)やAsString(defaultValue)などのデフォルト値を持つ一連のメソッドを提供し、型の不一致や存在しないパスによるプログラムのクラッシュを心配することなく、ノードから目的の型のデータを安全に抽出できます。

• 動的な変更：JSON オブジェクトおよび配列の要素のキーと値のペアを自由に追加、更新、または削除できます（Set、Add、Remove）。

  --- 高度なクエリおよび処理 ---。

• 強力なクエリエンジン:JSON Pointer(RFC 6901, ダイレクトパスアクセス用) とJSONPath(複雑でファジーなクエリ用) のビルトインサポートにより、深くネストされた複雑な構造から、1つまたは複数のデータノードを一括または正確に効率的に抽出できます。

• 低メモリのストリーム解析：ギガバイトスケールの巨大なJSONファイルを処理するJsonStreamParserを提供します。ファイル全体をメモリにロードすることなく、イベントストリーム方式でトークンごとにファイルを読み込むため、究極のメモリ効率を実現します。

• ユーティリティ機能：ドキュメントクローン ( .Clone() ) やディープマージ ( JsonMerge ) などの高度な機能を提供し、「デフォルトコンフィギュレーション」と「ユーザーコンフィギュレーション」のマージなど、一般的な複雑なタスクを大幅に簡素化します。

  --- 堅牢性と安全性

• 自動メモリ管理：RAII (Resource Acquisition Is Initialization) デザインパターンを採用しています。JsonDocument は、すべてのノードのライフサイクルを管理します。開発者は手動でJSON要素を新規作成/削除する必要がなく、メモリリークのリスクを根本的に排除します。

• クロスドキュメント操作の安全性：異なる JsonDocument インスタンス間でノードを割り当てる場合、ライブラリは自動的に安全なディープコピー（クローン）を実行し、ダングリングポインタや偶発的なデータ破損を防ぎます。
• 詳細なエラー報告：解析に失敗した場合、JsonError オブジェクトは、エラーの行番号、列番号、コンテキストを含む詳細な情報を提供し、問題の迅速な診断を容易にします。

2.コア概念とメモリ管理

[!] 2.1 名前空間 - プロジェクトを統合する鍵 [!]最も重要なヒント：このライブラリのすべてのクラス (JsonDocument や JsonNode など) とグローバル関数 (JsonParse など) は、MQL5_Json というネームスペース内にカプセル化されています。

**Howto Use It Correctly:** - **In Header Files (.mqh)**：MQL5では、ヘッダーファイルの グローバル スコープで 名前空間を使用 することはできません。**したがって、完全修飾名**を使用する必要があります。これはマルチファイル・プロジェクトで 唯一信頼できる方法 です。不正解: `JsonDocument doc;` 正解: `MQL5_Json::JsonDocument doc;` - **メインプログラムファイル(.mq5)の 内部関数**：便宜上、関数の内部では`using namespace MQL5_Json;` を使用できますが、例の 汎用性を 確保する ため、本マニュアルでは すべてのコードで完全修飾名を使用 します。**もし`'JsonNode'- declarationwithout type`という コンパイルエラーに遭遇したら、**** それはほとんどの場合、型と 関数に`MQL5_Json::`接頭辞****を 付け忘れて いるからです。

[!] 2.2 メモリ管理モデル JsonDocumentはデータを所有 し、JsonNodeは単なるビュー です。

[MQL5 では、関数の引数として渡されるすべてのクラス・オブジェクト（JsonNode を含む）は参照渡し（& を使用）する必要が あります。）不正解: void myFunction(MQL5_Json::JsonNode node) 正解: void myFunction(MQL5_Json::JsonNode &node)