A powerful and feature-rich JSON library for MQL5, designed to bring a modern development experience similar to Python/JS - bibliothèque pour MetaTrader 5

1. Vue d'ensemble

La bibliothèque JSON de MQL5 est une bibliothèque puissante et riche en fonctionnalités, conçue spécifiquement pour analyser, manipuler et sérialiser les données JSON dans l'environnement MQL5. Elle fournit une API DOM (Document Object Model) simple et intuitive, visant à rendre l'expérience de manipulation de JSON dans MQL5 comparable aux langages de programmation modernes tels que JavaScript et Python.

Cette bibliothèque est capable de gérer un large éventail de tâches, de la lecture de simples configurations d'EA à l'échange complexe de données en temps réel entre les systèmes. Ses principales fonctions et caractéristiques sont les suivantes

• --- Analyse et création ---
• Chargement à partir d'une chaîne ou d'un fichier: analyse de manière fiable un texte JSON en objets manipulables en mémoire ( JsonParse , JsonFromFile ).
• Construire à partir de zéro: Créez facilement de nouveaux objets et tableaux JSON par programme en utilisant des API concises telles que JsonNewObject et JsonNewArray .

• Analyseur flexible: Prise en charge facultative de certaines caractéristiques non standard de JSON5, telles que les commentaires de code et les virgules de fin, afin d'améliorer la compatibilité avec diverses sources de données.

• --- Manipulation et accès ---

• Traversée intuitive du DOM: Accédez aux données en utilisant une syntaxe intuitive avec des clés ( node["key"]) et des indices ( node[0]), comme si vous utilisiez un dictionnaire Python ou un objet JavaScript.

• Conversion sûre des types: Fournit une série de méthodes avec des valeurs par défaut, telles que AsInt(defaultValue) et AsString(defaultValue) , vous permettant d'extraire en toute sécurité des données du type souhaité à partir d'un nœud sans vous soucier des blocages de programme dus à des erreurs de type ou à des chemins inexistants.

• Modification dynamique: Ajoutez, mettez à jour ou supprimez librement des paires clé-valeur dans des objets JSON et des éléments dans des tableaux ( Set , Add , Remove ).

  --- Requête et traitement avancés ---

• Moteur de requête puissant: prise en charge intégrée du pointeur JSON (RFC 6901, pour un accès direct au chemin) et de JSONPath (pour les requêtes complexes et floues), permettant d'extraire efficacement un ou plusieurs nœuds de données de structures complexes profondément imbriquées, soit en masse, soit avec précision.

• Analyse de flux à faible mémoire: Fournit JsonStreamParser pour le traitement de fichiers JSON gigantesques à l'échelle du gigaoctet. Il lit le fichier jeton par jeton dans un flux d'événements sans charger l'intégralité du fichier en mémoire, ce qui permet d'optimiser l'utilisation de la mémoire.

• Fonctions utilitaires: Offre des fonctions avancées telles que le clonage de documents ( .Clone() ) et la fusion en profondeur ( JsonMerge ), qui simplifient grandement les tâches complexes courantes telles que la fusion de la "configuration par défaut" avec la "configuration de l'utilisateur".

  --- Robustesse et sécurité ---

• Gestion automatique de la mémoire: Adopte le modèle de conception RAII (Resource Acquisition Is Initialization). JsonDocument est responsable de la gestion du cycle de vie de tous ses nœuds. Les développeurs n'ont pas besoin de créer ou de supprimer manuellement des éléments JSON, ce qui élimine fondamentalement le risque de fuites de mémoire.

• Sécurité des opérations entre documents: Lors de l'affectation d'un nœud entre différentes instances de JsonDocument, la bibliothèque effectue automatiquement une copie profonde sûre (Clone), évitant ainsi les pointeurs pendants et la corruption accidentelle des données.
• Rapport d'erreur détaillé: En cas d'échec de l'analyse, l'objet JsonError fournit des informations détaillées, notamment le numéro de la ligne d'erreur, le numéro de la colonne et le contexte, ce qui permet de diagnostiquer rapidement le problème.

2. Concepts de base et gestion de la mémoire

[2.1 L'espace de noms - la clé de l'intégration de votre projet [ !!] Conseil le plus important: Toutes les classes de cette bibliothèque (par exemple, JsonDocument , JsonNode ) et les fonctions globales (par exemple, JsonParse ) sont encapsulées dans un espace de noms appelé MQL5_Json .

**Comment l ' utiliser correctement:** - **Dans les fichiers d'en-tête (.mqh)** : MQL5 n'autorise pas l'utilisation de l'espace de noms dans la portée globale des fichiers d' en-tête. **Par conséquent, vous devez utiliser des noms pleinement qualifiés**. C'est le seul moyen fiable dans les projets multi-fichiers. Incorrect : `JsonDocument doc;` Correct : `MQL5_Json::JsonDocument doc;` - **Fonctions internes dans les fichiers du programme principal (.mq5)** : Pour des raisons de commodité, vous pouvez utiliser `utiliser l'espace de noms MQL5_Json;` à l'intérieur des fonctions, mais pour assurer la généralité des exemples, tout le code de ce manuel utilisera l ' approche du nom pleinement qualifié. **Si vous rencontrez l' erreur de compilation``JsonNode' - déclaration sans type`,** ** c 'est presque toujours parce que vous avez oublié d ' ajouter le préfixe `MQL5_Json::`** **aux types et fonctions.**

[ !!] 2.2 Modèle de gestion de la mémoire JsonDocument possède les données ; JsonNode n'est qu'une vue.

[MQL5 exige que tous les objets de classe (y compris JsonNode ) passés en tant qu'arguments de fonction soient passés par référence (en utilisant &). Incorrect : void myFunction(MQL5_Json::JsonNode node) Correct : void myFunction(MQL5_Json::JsonNode &node