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

1. Panoramica

La MQL5 JSON Library è una libreria potente e ricca di funzionalità, progettata specificamente per analizzare, manipolare e serializzare i dati JSON nell'ambiente MQL5. Fornisce un'API DOM (Document Object Model) semplice e intuitiva, con l'obiettivo di rendere l'esperienza di gestione di JSON in MQL5 paragonabile ai moderni linguaggi di programmazione come JavaScript e Python.

Questa libreria è in grado di gestire un'ampia gamma di compiti, dalla lettura di semplici configurazioni EA a complessi scambi di dati in tempo reale tra sistemi. Le sue funzioni e caratteristiche principali includono:

• --- Parsing e creazione ---
• Caricamento da stringa o file: analizza in modo affidabile il testo JSON in oggetti manipolabili in memoria ( JsonParse , JsonFromFile ).
• Creare da zero: Creare facilmente nuovi oggetti e array JSON in modo programmatico utilizzando API concise come JsonNewObject e JsonNewArray.

• Parser flessibile: Supporta facoltativamente alcune caratteristiche non standard di JSON5, come i commenti al codice e le virgole, per migliorare la compatibilità con diverse fonti di dati.

• --- Manipolazione e accesso ---

• Traversata DOM intuitiva: Accesso ai dati utilizzando una sintassi intuitiva con chiavi ( node["key"] ) e indici ( node[0] ), proprio come se si utilizzasse un dizionario Python o un oggetto JavaScript.

• Conversione sicura dei tipi: Fornisce una serie di metodi con valori predefiniti, come AsInt(defaultValue) e AsString(defaultValue), che consentono di estrarre in modo sicuro i dati del tipo desiderato da un nodo, senza preoccuparsi di arresti anomali del programma a causa di errori di tipo o di percorsi inesistenti.

• Modifica dinamica: Aggiungere, aggiornare o cancellare liberamente coppie chiave-valore in oggetti JSON ed elementi in array ( Set , Add , Remove ).

  --- Interrogazione ed elaborazione avanzate

• Potente motore di interrogazione: supporto integrato per JSON Pointer (RFC 6901, per l'accesso diretto al percorso) e JSONPath (per query complesse e confuse), che consente di estrarre in modo efficiente uno o più nodi di dati da strutture complesse e profondamente annidate, sia in blocco che con precisione.

• Parsing di flussi a bassa memoria: Fornisce JsonStreamParser per l'elaborazione di file JSON di dimensioni gigantesche. Legge il file token per token in un flusso di eventi senza caricare l'intero file in memoria, ottenendo così la massima efficienza di memoria.

• Funzioni di utilità: Offre funzioni avanzate come la clonazione dei documenti ( .Clone() ) e la fusione profonda ( JsonMerge ), che semplificano notevolmente compiti complessi comuni come la fusione della "configurazione predefinita" con la "configurazione utente".

  --- Robustezza e sicurezza

• Gestione automatica della memoria: Adotta il modello di progettazione RAII (Resource Acquisition Is Initialization). JsonDocument è responsabile della gestione del ciclo di vita di tutti i suoi nodi. Gli sviluppatori non hanno bisogno di creare/eliminare manualmente alcun elemento JSON, eliminando così il rischio di perdite di memoria.

• Sicurezza delle operazioni tra documenti: Quando si assegna un nodo tra diverse istanze di JsonDocument, la libreria esegue automaticamente una copia profonda sicura (Clone), evitando puntatori penzolanti e corruzione accidentale dei dati.
• Segnalazione dettagliata degli errori: Quando il parsing fallisce, l'oggetto JsonError fornisce informazioni dettagliate, tra cui il numero di riga, il numero di colonna e il contesto dell'errore, facilitando una rapida diagnosi del problema.

2. Concetti fondamentali e gestione della memoria

[2.1 Namespace - La chiave per integrare il progetto [!!!] Il consiglio più importante: Tutte le classi di questa libreria (ad esempio, JsonDocument , JsonNode ) e le funzioni globali (ad esempio, JsonParse ) sono incapsulate in uno spazio dei nomi chiamato MQL5_Json .

**Come usarlo correttamente:** - **Nei file di intestazione (.mqh)**: MQL5 non consente l'uso del "namespace" nell ' ambito globale dei file di intestazione. **Pertanto, è necessario utilizzare nomi completamente qualificati**. Questo è l 'unico modo affidabile in progetti con più file. Errato: `JsonDocument doc;` Corretto: `MQL5_Json::JsonDocument doc;` - **Funzioni interne ai file di programma principali (.mq5)**: Per comodità, si può usare `using namespace MQL5_Json;` all'interno delle funzioni, ma per garantire la generalità degli esempi, tutto il codice di questo manuale userà l' approccio del nome pienamente qualificato. **Se si incontra l' errore di compilazione `'JsonNode' - dichiarazione senza tipo',** ** è quasi sempre perché ci si è dimenticati di aggiungere il prefisso `MQL5_Json::`** **ai tipi e alle funzioni.

[!!!] 2.2 Modello di gestione della memoria JsonDocument possiede i dati; JsonNode è solo una vista.

[2.3 Passaggio di oggetti in MQL5 MQL5 richiede che tutti gli oggetti di classe (incluso JsonNode) passati come argomenti di funzione siano passati per riferimento (usando &). Errato: void myFunction(MQL5_Json::JsonNode node) Corretto: void myFunction(MQL5_Json::JsonNode &node