A powerful and feature-rich JSON library for MQL5, designed to bring a modern development experience similar to Python/JS - Bibliothek für den MetaTrader 5

1. Überblick

Die MQL5 JSON Library ist eine leistungsstarke, funktionsreiche Bibliothek, die speziell für das Parsen, Manipulieren und Serialisieren von JSON-Daten innerhalb der MQL5-Umgebung entwickelt wurde. Sie bietet ein einfaches und intuitives Document Object Model (DOM) API, mit dem Ziel, die JSON-Verarbeitung in MQL5 mit modernen Programmiersprachen wie JavaScript und Python vergleichbar zu machen.

Diese Bibliothek ist in der Lage, eine breite Palette von Aufgaben zu bewältigen, vom Lesen einfacher EA-Konfigurationen bis zum komplexen Echtzeit-Datenaustausch zwischen Systemen. Zu den wichtigsten Funktionen und Eigenschaften gehören:

• --- Parsing und Erstellung ---
• Laden aus String oder Datei: parst zuverlässig JSON-Text in manipulierbare In-Memory-Objekte ( JsonParse , JsonFromFile ).
• Von Grund auf neu erstellen: Einfache programmatische Erstellung neuer JSON-Objekte und -Arrays mithilfe prägnanter APIs wie JsonNewObject und JsonNewArray .

• Flexibler Parser: Unterstützt optional einige nicht standardisierte Merkmale von JSON5, wie z. B. Codekommentare und abschließende Kommas, um die Kompatibilität mit verschiedenen Datenquellen zu verbessern.

• --- Manipulation und Zugriff ---

• Intuitives DOM-Traversal: Der Zugriff auf Daten erfolgt über eine intuitive Syntax mit Schlüsseln ( node["key"] ) und Indizes ( node[0] ), genau wie bei der Verwendung eines Python-Wörterbuchs oder eines JavaScript-Objekts.

• Sichere Typkonvertierung: Bietet eine Reihe von Methoden mit Standardwerten, wie AsInt(defaultValue) und AsString(defaultValue) , mit denen Sie sicher Daten des gewünschten Typs aus einem Knoten extrahieren können, ohne sich Sorgen über Programmabstürze aufgrund von Typübereinstimmungen oder nicht vorhandenen Pfaden zu machen.

• Dynamische Modifikation: Freies Hinzufügen, Aktualisieren oder Löschen von Schlüssel-Wert-Paaren in JSON-Objekten und Elementen in Arrays ( Set , Add , Remove ).

  --- Erweiterte Abfrage und Verarbeitung ---

• Leistungsstarke Abfrage-Engine: Eingebaute Unterstützung für JSON Pointer (RFC 6901, für direkten Pfadzugriff) und JSONPath (für komplexe und unscharfe Abfragen), die eine effiziente Extraktion von einem oder mehreren Datenknoten aus tief verschachtelten, komplexen Strukturen ermöglicht, entweder in Massen oder mit Präzision.

• Stream-Parsing mit geringem Speicherbedarf: Bietet JsonStreamParser für die Verarbeitung riesiger JSON-Dateien im Gigabyte-Bereich. Er liest die Datei Token für Token in einer Art Ereignisstrom, ohne die gesamte Datei in den Speicher zu laden, wodurch eine ultimative Speichereffizienz erreicht wird.

• Dienstprogramm-Funktionen: Bietet fortschrittliche Funktionen wie das Klonen von Dokumenten ( .Clone() ) und Deep Merging ( JsonMerge ), die häufige komplexe Aufgaben wie das Zusammenführen der "Standardkonfiguration" mit der "Benutzerkonfiguration" erheblich vereinfachen.

  --- Robustheit und Sicherheit ---

• Automatische Speicherverwaltung: Übernimmt das RAII (Resource Acquisition Is Initialization) Entwurfsmuster. JsonDocument ist für die Verwaltung des Lebenszyklus aller seiner Knoten verantwortlich. Die Entwickler müssen keine JSON-Elemente manuell neu anlegen oder löschen, wodurch das Risiko von Speicherlecks grundsätzlich ausgeschlossen wird.

• Dokumentübergreifende Operationssicherheit: Bei der Zuweisung eines Knotens zwischen verschiedenen JsonDocument-Instanzen führt die Bibliothek automatisch eine sichere Tiefenkopie (Clone) durch und verhindert so "Dangling Pointers" und versehentliche Datenkorruption.
• Detaillierte Fehlerberichterstattung: Wenn das Parsen fehlschlägt, liefert das JsonError-Objekt detaillierte Informationen, einschließlich der Fehlerzeilennummer, der Spaltennummer und des Kontexts, was eine schnelle Problemdiagnose ermöglicht.

2. Kernkonzepte & Speicherverwaltung

[!!] 2.1 Namespace - Der Schlüssel zur Integration Ihres Projekts [!!] Wichtigster Tipp: Alle Klassen in dieser Bibliothek (z.B. JsonDocument , JsonNode ) und globale Funktionen (z.B. JsonParse ) sind in einem Namespace namens MQL5_Json gekapselt.

**Korrekte Verwendung:** - **In Header-Dateien (.mqh)**: MQL5 erlaubt die Verwendung von Namespace im globalen Bereich von Header-Dateien nicht. **Daher müssen Sie voll qualifizierte Namen verwenden**. Dies ist der einzige zuverlässige Weg in Projekten mit mehreren Dateien. Falsch: `JsonDocument doc;` Richtig: `MQL5_Json::JsonDocument doc;` - **Inside Funktionen in Hauptprogrammdateien (.mq5)**: Der Einfachheit halber können Sie innerhalb von Funktionen den `Namensraum MQL5_Json;` verwenden, aber um die Allgemeinheit der Beispiele zu gewährleisten, wird der gesamte Code in diesem Handbuch den Ansatz des voll qualifizierten Namens verwenden. **Wenn Sie auf den Kompilierungsfehler "JsonNode - Deklaration ohne Typ" stoßen, **ist dies fast immer darauf zurückzuführen, dass Sie vergessen haben , den Typen und Funktionen das Präfix "MQL5_Json::`" hinzuzufügen.

[!!] 2.2 Speicherverwaltungsmodell JsonDocument ist Eigentümer der Daten; JsonNode ist nur eine Ansicht.

[!!] 2.3 Objektübergabe in MQL5 MQL5 verlangt, dass alle Klassenobjekte (einschließlich JsonNode ), die als Funktionsargumente übergeben werden , per Referenz (mit &) übergeben werden müssen. Falsch: void myFunction(MQL5_Json::JsonNode node) Richtig: void myFunction(MQL5_Json::JsonNode &node