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

1. Visão geral

A biblioteca MQL5 JSON é uma biblioteca poderosa e rica em recursos, projetada especificamente para analisar, manipular e serializar dados JSON no ambiente MQL5. Ela fornece uma API simples e intuitiva do Modelo de Objeto de Documento (DOM), com o objetivo de tornar a experiência de manipulação de JSON em MQL5 comparável a linguagens de programação modernas como JavaScript e Python.

Essa biblioteca é capaz de lidar com uma ampla gama de tarefas, desde a leitura de configurações simples de EA até a complexa troca de dados em tempo real entre sistemas. Suas principais funções e recursos incluem:

• --- Análise e criação ---
• Carregar de cadeia de caracteres ou arquivo: analisa de forma confiável o texto JSON em objetos manipuláveis na memória ( JsonParse , JsonFromFile ).
• Criação a partir do zero: Crie facilmente novos objetos e matrizes JSON de forma programática usando APIs concisas como JsonNewObject e JsonNewArray.

• Parser flexível: Opcionalmente, oferece suporte a alguns recursos não padrão do JSON5, como comentários de código e vírgulas finais, para aumentar a compatibilidade com várias fontes de dados.

• --- Manipulação e acesso ---

• Travessia intuitiva do DOM: Acesse os dados usando uma sintaxe intuitiva com chaves ( node["key"]) e índices ( node[0]), como se estivesse usando um dicionário Python ou um objeto JavaScript.

• Conversão segura de tipos: Fornece uma série de métodos com valores padrão, como AsInt(defaultValue) e AsString(defaultValue) , permitindo que você extraia com segurança os dados do tipo desejado de um nó sem se preocupar com falhas no programa devido a incompatibilidades de tipos ou caminhos inexistentes.

• Modificação dinâmica: Adicione, atualize ou exclua livremente pares de valores-chave em objetos JSON e elementos em matrizes (Set, Add, Remove).

  --- Consulta e processamento avançados ---

• Mecanismo de consulta avançado: suporte integrado para JSON Pointer (RFC 6901, para acesso direto ao caminho) e JSONPath (para consultas complexas e difusas), permitindo a extração eficiente de um ou mais nós de dados de estruturas complexas e profundamente aninhadas, seja em massa ou com precisão.

• Análise de fluxo de baixa memória: Fornece o JsonStreamParser para processar arquivos JSON enormes e em escala de gigabytes. Ele lê o arquivo token por token em uma maneira de fluxo de eventos sem carregar o arquivo inteiro na memória, obtendo assim a máxima eficiência de memória.

• Funções utilitárias: Oferece recursos avançados, como clonagem de documentos ( .Clone() ) e fusão profunda ( JsonMerge ), que simplificam bastante as tarefas complexas comuns, como a fusão da "configuração padrão" com a "configuração do usuário".

  --- Robustez e segurança ---

• Gerenciamento automático de memória: Adota o padrão de design RAII (Resource Acquisition Is Initialization). O JsonDocument é responsável por gerenciar o ciclo de vida de todos os seus nós. Os desenvolvedores não precisam criar/excluir manualmente nenhum elemento JSON, eliminando fundamentalmente o risco de vazamentos de memória.

• Segurança de operação entre documentos: Ao atribuir um nó entre diferentes instâncias de JsonDocument, a biblioteca executa automaticamente uma cópia profunda segura (Clone), evitando ponteiros pendentes e corrupção acidental de dados.
• Relatório detalhado de erros: Quando a análise falha, o objeto JsonError fornece informações detalhadas, incluindo o número da linha de erro, o número da coluna e o contexto, facilitando o diagnóstico rápido do problema.

2. Conceitos básicos e gerenciamento de memória

[2.1 Namespace - A chave para a integração do seu projeto [!!!] Dica mais importante: Todas as classes desta biblioteca (por exemplo, JsonDocument , JsonNode ) e as funções globais (por exemplo, JsonParse ) são encapsuladas em um namespace chamado MQL5_Json .

**Como usá-lo corretamente:** - **Em arquivos de cabeçalho (.mqh)**: A MQL5 não permite o " uso de namespace" no escopo global de arquivos de cabeçalho. **Portanto, você deve usar nomes totalmente qualificados**. Essa é a única maneira confiável em projetos com vários arquivos. Incorreto: `JsonDocument doc;` Correto: `MQL5_Json::JsonDocument doc;` - **Funções internas em arquivos de programas principais (.mq5)**: Por conveniência, você pode usar `using namespace MQL5_Json;` dentro de funções, mas para garantir a generalidade dos exemplos, todo o código neste manual usará a abordagem de nome totalmente qualificado. **Se você encontrar o erro de compilação `'JsonNode' - declaration without type` **, é quase sempre porque você esqueceu de adicionar o prefixo `MQL5_Json::` ** aos tipos e funções** **.

[!!!] 2.2 Modelo de gerenciamento de memória O JsonDocument é o proprietário dos dados; o JsonNode é apenas uma visualização.

[!!!] 2.3 Passagem de objetos em MQL5 A MQL5 exige que todos os objetos de classe (incluindo JsonNode) passados como argumentos de função sejam passados por referência (usando &). Incorreto: void myFunction(MQL5_Json::JsonNode node) Correto: void myFunction(MQL5_Json::JsonNode &node