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

1. Visión General

La librería MQL5 JSON es una librería potente y rica en características diseñada específicamente para parsear, manipular y serializar datos JSON dentro del entorno MQL5. Proporciona un simple e intuitivo Modelo de Objetos de Documento (DOM) API, con el objetivo de hacer la experiencia de manejo de JSON en MQL5 comparable a los lenguajes de programación modernos como JavaScript y Python.

Esta biblioteca es capaz de manejar una amplia gama de tareas, desde la lectura de configuraciones simples de EA hasta el complejo intercambio de datos en tiempo real entre sistemas. Sus principales funciones y características incluyen:

• --- Análisis sintáctico y creación ---
• Carga desde cadena o archivo: Analiza de forma fiable texto JSON en objetos manipulables en memoria ( JsonParse , JsonFromFile ).
• Construir desde cero: Crea fácilmente nuevos objetos JSON y matrices mediante programación utilizando API concisas como JsonNewObject y JsonNewArray .

• Analizador sintáctico flexible: Soporta opcionalmente algunas características no estándar de JSON5, como comentarios de código y comas finales, para mejorar la compatibilidad con diversas fuentes de datos.

• --- Manipulación y acceso

• Recorrido intuitivo del DOM: Acceda a los datos utilizando una sintaxis intuitiva con claves ( node["key"] ) e índices ( node[0] ), igual que si utilizara un diccionario Python o un objeto JavaScript.

• Conversión de tipos segura: Proporciona una serie de métodos con valores por defecto, como AsInt(defaultValue) y AsString(defaultValue) , que permiten extraer de forma segura datos del tipo deseado de un nodo sin preocuparse de que el programa se bloquee debido a desajustes de tipo o rutas inexistentes.

• Modificación dinámica: Añadir, actualizar o eliminar libremente pares clave-valor en objetos JSON y elementos en arrays ( Set , Add , Remove ).

  --- Consulta y procesamiento avanzados

• Potente motor de consultas: soporte integrado para JSON Pointer (RFC 6901, para acceso directo a rutas) y JSONPath (para consultas complejas y difusas), lo que permite la extracción eficiente de uno o más nodos de datos de estructuras complejas y profundamente anidadas, ya sea en bloque o con precisión.

• Análisis de flujos de baja memoria: Proporciona JsonStreamParser para procesar archivos JSON enormes a escala de gigabytes. Lee el archivo token por token en forma de flujo de eventos sin cargar todo el archivo en memoria, logrando así la máxima eficiencia de memoria.

• Funciones de utilidad: Ofrece funciones avanzadas como la clonación de documentos ( .Clone() ) y la fusión profunda ( JsonMerge ), que simplifican enormemente tareas complejas comunes como la fusión de la "configuración por defecto" con la "configuración del usuario".

  --- Robustez y seguridad

• Gestión automática de memoria: Adopta el patrón de diseño RAII (Resource Acquisition Is Initialization). JsonDocument se encarga de gestionar el ciclo de vida de todos sus nodos. Los desarrolladores no necesitan crear/eliminar manualmente ningún elemento JSON, eliminando fundamentalmente el riesgo de fugas de memoria.

• Seguridad de operación entre documentos: Al asignar un nodo entre diferentes instancias de JsonDocument, la biblioteca realiza automáticamente una copia profunda segura (Clone), evitando punteros colgantes y corrupción accidental de datos.
• Informe detallado de errores: Cuando falla el análisis sintáctico, el objeto JsonError proporciona información detallada que incluye el número de línea de error, el número de columna y el contexto, lo que facilita el diagnóstico rápido del problema.

2. 2. Conceptos básicos y gestión de memoria

[!!] 2.1 Namespace - La clave para integrar su proyecto [!!] Consejo más importante: Todas las clases de esta librería (e.g., JsonDocument , JsonNode ) y funciones globales (e.g., JsonParse ) están encapsuladas dentro de un espacio de nombres llamado MQL5_Json .

**Cómo Usarlo Correctamente:** - **En Archivos de Cabecera (.mqh)**: MQL5 no permite `usar namespace` en el ámbito global de los archivos de cabecera. **Por lo tanto, debe utilizar nombres completamente cualificados**. Esta es la única forma fiable en proyectos con múltiples archivos. Incorrecto: `JsonDocument doc;` Correcto: `MQL5_Json::JsonDocument doc;` - **Inside Functions in Main Program Files (.mq5)**: Por conveniencia, puede usar `using namespace MQL5_Json;` dentro de las funciones, pero para asegurar la generalidad de los ejemplos, todo el código en este manual usará el enfoque de nombre completamente cualificado. **Si se encuentra con el error de compilación `'JsonNode' - declaración sin tipo`,** casi siempre se debe a que se ha olvidado añadir el prefijo `MQL5_Json::`** a los tipos y funciones.

[2.2 Modelo de Gestión de Memoria JsonDocument posee los datos; JsonNode es sólo una vista.

[2.3 Paso de Objetos en MQL5 MQL5 requiere que todos los objetos de clase (incluyendo JsonNode ) pasados como argumentos de función deben ser pasados por referencia (usando &). Incorrecto: void myFunction(MQL5_Json::JsonNode nodo) Correcto: void myFunction(MQL5_Json::JsonNode &nodo