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 - это мощная и многофункциональная библиотека, разработанная специально для разбора, манипулирования и сериализации JSON-данных в среде MQL5. Она предоставляет простой и интуитивно понятный API Document Object Model (DOM), стремясь сделать работу с JSON в MQL5 сравнимой с современными языками программирования, такими как JavaScript и Python.

Эта библиотека способна решать широкий спектр задач, от чтения простых конфигураций советников до сложного обмена данными между системами в режиме реального времени. Ее основные функции и возможности включают:

• --- Парсинг и создание ---
• Загрузка из строки или файла: надежно разбирает текст JSON в объекты, которыми можно манипулировать в памяти ( JsonParse , JsonFromFile ).
• Создание с нуля: Легко создавайте новые JSON-объекты и массивы программно, используя такие лаконичные API, как JsonNewObject и JsonNewArray.

• Гибкий парсер: Опционально поддерживает некоторые нестандартные особенности JSON5, такие как комментарии к коду и запятые в конце строки, для улучшения совместимости с различными источниками данных.

• --- Манипулирование и доступ ---

• Интуитивно понятный обход DOM: Доступ к данным с помощью интуитивно понятного синтаксиса с ключами ( node["key"] ) и индексами ( node[0] ), как при использовании словаря Python или объекта JavaScript.

• Безопасное преобразование типов: Предоставляет ряд методов со значениями по умолчанию, таких как AsInt(defaultValue) и AsString(defaultValue), позволяющих безопасно извлекать данные нужного типа из узла, не опасаясь сбоев программы из-за несоответствия типов или несуществующих путей.

• Динамическая модификация: Свободное добавление, обновление или удаление пар ключ-значение в объектах JSON и элементов в массивах (Set, Add, Remove).

  --- Расширенные возможности запросов и обработки ---.

• Мощный механизм запросов: встроенная поддержка JSON Pointer (RFC 6901, для прямого доступа к пути) и JSONPath (для сложных и нечетких запросов), позволяющая эффективно извлекать один или несколько узлов данных из глубоко вложенных сложных структур, как в массовом порядке, так и с высокой точностью.

• Парсинг потоков с малым количеством памяти: Предоставляет JsonStreamParser для обработки гигабайтных, огромных файлов JSON. Он считывает файл токен за токеном в потоке событий, не загружая весь файл в память, что позволяет достичь максимальной эффективности использования памяти.

• Утилитарные функции: Предлагает расширенные функции, такие как клонирование документов ( .Clone() ) и глубокое слияние ( JsonMerge ), которые значительно упрощают обычные сложные задачи, такие как слияние "конфигурации по умолчанию" с "конфигурацией пользователя".

  --- Надежность и безопасность ---.

• Автоматическое управление памятью: Применяется паттерн проектирования RAII (Resource Acquisition Is Initialization). JsonDocument отвечает за управление жизненным циклом всех своих узлов. Разработчикам не нужно вручную добавлять/удалять какие-либо элементы JSON, что в корне исключает риск утечки памяти.

• Безопасность кросс-документных операций: При назначении узла между различными экземплярами JsonDocument библиотека автоматически выполняет безопасное глубокое копирование (Clone), предотвращая висячие указатели и случайное повреждение данных.
• Подробный отчет об ошибках: При сбое парсинга объект JsonError предоставляет подробную информацию, включая номер строки ошибки, номер столбца и контекст, что способствует быстрой диагностике проблемы.

2. Основные понятия и управление памятью

[!!!] 2.1 Пространство имен - ключ к интеграции вашего проекта [!!!] Самый важный совет: Все классы этой библиотеки (например, JsonDocument , JsonNode ) и глобальные функции (например, JsonParse ) инкапсулированы в пространстве имен MQL5_Json .

**Как правильно его использовать:** - **В заголовочных файлах (.mqh)**: MQL5 не позволяет использовать ``пространство имен`` в глобальной области видимости заголовочных файлов. **Поэтому вы должны использовать полностью квалифицированные имена**. Это единственный надежный способ в многофайловых проектах. Неправильно: `JsonDocument doc;` Правильно: `MQL5_Json::JsonDocument doc;` - **Внутренние функции в основных файлах программы (.mq5)**: Для удобства внутри функций можно использовать `использование пространства имен MQL5_Json;`, но для обеспечения общности примеров во всем коде в этом руководстве будет использоваться подход с использованием полного квалифицированного имени. **Если вы столкнулись с ошибкой компиляции`'JsonNode'' - объявление без типа`,** **то почти всегда это связано с тем, что вы забыли добавить префикс `MQL5_Json::`` к типам и функциям** **.

[!!!] 2.2 Модель управления памятью JsonDocument владеет данными; JsonNode - это просто представление.

[!!] 2.3 Передача объектов в MQL5 MQL5 требует, чтобы все объекты класса (включая JsonNode), передаваемые в качестве аргументов функции , передавались по ссылке (с использованием &). Неправильно: void myFunction(MQL5_Json::JsonNode node) Правильно: void myFunction(MQL5_Json::JsonNode &node