A powerful and feature-rich JSON library for MQL5, designed to bring a modern development experience similar to Python/JS - MetaTrader 5용 라이브러리

1. Overview

The MQL5 JSON Library is a powerful,feature-rich library designed specifically for parsing, manipulating, and serializing JSON data within the MQL5 environment. It provides a simple and intuitive Document Object Model (DOM) API, aiming to make the JSON handling experience in MQL5 comparable to modern programming languages like JavaScript and Python.

This library is capable of handling a wide range of tasks, from reading simple EA configurations to complex real-time data exchange between systems. Its main functions and features include:

• --- Parsing and Creation ---
• Load from String or File: Reliably parses JSON text into manipulable in-memory objects ( JsonParse , JsonFromFile ).
• Build from Scratch: Easily create new JSON objects and arrays programmatically using concise APIs like JsonNewObject and JsonNewArray .

• Flexible Parser: Optionally supports some non-standard features of JSON5, such as code comments and trailing commas, to enhance compatibility with various data sources.

• --- Manipulation and Access ---

• Intuitive DOM Traversal: Access data using intuitive syntax with keys ( node["key"] ) and indices ( node[0] ), just like using a Python dictionary or a JavaScript object.

• Safe Type Conversion: Provides a series of methods with default values, such as AsInt(defaultValue) and AsString(defaultValue) , allowing you to safely extract data of the desired type from a node without worrying about program crashes due to type mismatches or non-existent paths.

• Dynamic Modification: Freely add, update, or delete key-value pairs in JSON objects and elements in arrays ( Set , Add , Remove ).

  --- Advanced Querying and Processing ---

• Powerful Query Engine: Built-in support for JSON Pointer (RFC 6901, for direct path access) and JSONPath (for complex and fuzzy queries), enabling efficient extraction of one or more data nodes from deeply nested, complex structures, either in bulk or with precision.

• Low-Memory Stream Parsing: Provides JsonStreamParser for processing gigabyte-scale, huge JSON files. It reads the file token by token in an event stream manner without loading the entire file into memory, thus achieving ultimate memory efficiency.

• Utility Functions: Offers advanced features like document cloning ( .Clone() ) and deep merging ( JsonMerge ), which greatly simplify common complex tasks such as merging "default configuration" with "user configuration".

  --- Robustness and Safety ---

• Automatic Memory Management: Adopts the RAII (Resource Acquisition Is Initialization) design pattern. JsonDocument is responsible for managing the lifecycle of all its nodes. Developers do not need to manually new / delete any JSON elements, fundamentally eliminating the risk of memory leaks.

• Cross-Document Operation Safety: When assigning a node between different JsonDocument instances, the library automatically performs a safe deep copy (Clone), preventing dangling pointers and accidental data corruption.
• Detailed Error Reporting: When parsing fails, the JsonError object provides detailed information including the error line number, column number, and context, facilitating rapid problem diagnosis.

2. Core Concepts & Memory Management

[!!] 2.1 Namespace - The Key to Integrating Your Project [!!] Most Important Tip: All classes in this library (e.g., JsonDocument , JsonNode ) and global functions (e.g., JsonParse ) are encapsulated within a namespace called MQL5_Json .

**How to Use It Correctly:** - **In Header Files (.mqh)**: MQL5 does not allow `using namespace` in the global scope of header files. **Therefore, you must use fully qualified names**. This is the only reliable way in multi-file projects. Incorrect: `JsonDocument doc;` Correct: `MQL5_Json::JsonDocument doc;` - **Inside Functions in Main Program Files (.mq5)**: For convenience, you can use `using namespace MQL5_Json;` inside functions, but to ensure the generality of the examples, all code in this manual will use the fully qualified name approach. **If you encounter the `'JsonNode' - declaration without type` compilation error,** **it is almost always because you forgot to add the `MQL5_Json::` prefix** **to the types and functions.**

[!!] 2.2 Memory Management Model JsonDocument owns the data; JsonNode is just a view.

[!!] 2.3 Object Passing in MQL5 MQL5 requires that all class objects (including JsonNode ) passed as function arguments must be passed by reference (using &). Incorrect: void myFunction(MQL5_Json::JsonNode node) Correct: void myFunction(MQL5_Json::JsonNode &node