A powerful and feature-rich JSON library for MQL5, designed to bring a modern development experience similar to Python/JS - MetaTrader 5용 라이브러리

1. 개요

MQL5 JSON 라이브러리는 MQL5 환경 내에서 JSON 데이터를 구문 분석, 조작 및 직렬화하기 위해 특별히 설계된 강력하고 풍부한 기능을 갖춘 라이브러리입니다. 이 라이브러리는 간단하고 직관적인 DOM(문서 객체 모델) API를 제공하며, MQL5의 JSON 처리 환경을 JavaScript 및 Python과 같은 최신 프로그래밍 언어와 비교할 수 있는 수준으로 만드는 것을 목표로 합니다.

이 라이브러리는 간단한 EA 구성 읽기부터 시스템 간의 복잡한 실시간 데이터 교환에 이르기까지 다양한 작업을 처리할 수 있습니다. 주요 기능 및 특징은 다음과 같습니다:

• --- 구문 분석 및 생성 ---
• 문자열 또는 파일에서 로드: JSON 텍스트를 조작 가능한 인메모리 객체로 안정적으로 구문 분석합니다(JsonParse , JsonFromFile).
• 처음부터 빌드: JsonNewObject 및 JsonNewArray와 같은 간결한 API를 사용해 프로그래밍 방식으로 새로운 JSON 객체와 배열을 쉽게 생성할 수 있습니다.

• 유연한 파서: 다양한 데이터 소스와의 호환성을 높이기 위해 코드 주석 및 후행 쉼표와 같은 JSON5의 일부 비표준 기능을 선택적으로 지원합니다.

• --- 조작 및 액세스 ---

• 직관적인 DOM 탐색: Python 사전이나 JavaScript 객체를 사용하는 것처럼 키( node["key"] )와 인덱스( node[0] )로 직관적인 구문을 사용해 데이터에 액세스할 수 있습니다.

• 안전한 유형 변환: 유형 불일치나 존재하지 않는 경로로 인한 프로그램 충돌을 걱정하지 않고 노드에서 원하는 유형의 데이터를 안전하게 추출할 수 있도록 AsInt(defaultValue), AsString(defaultValue)과 같은 기본값을 가진 일련의 메서드를 제공합니다.

• 동적 수정: JSON 객체와 배열의 요소에서 키-값 쌍을 자유롭게 추가, 업데이트 또는 삭제(설정, 추가, 제거)할 수 있습니다.

  --- 고급 쿼리 및 처리 ---

• 강력한 쿼리 엔진: JSON 포인터 (RFC 6901, 직접 경로 액세스용) 및 JSONPath (복잡하고 퍼지 쿼리용)를 기본 지원하여 깊게 중첩된 복잡한 구조에서 하나 이상의 데이터 노드를 대량으로 또는 정밀하게 효율적으로 추출할 수 있습니다.

• 저메모리 스트림 구문 분석: 기가바이트 규모의 대용량 JSON 파일을 처리하기 위한 JsonStreamParser를 제공합니다. 전체 파일을 메모리에 로드하지 않고 이벤트 스트림 방식으로 파일을 토큰 단위로 읽어 최고의 메모리 효율성을 달성합니다.

• 유틸리티 기능: '기본 구성'과 '사용자 구성'을 병합하는 것과 같은 일반적인 복잡한 작업을 크게 간소화하는 문서 복제(.Clone()) 및 심층 병합(.JsonMerge)과 같은 고급 기능을 제공합니다.

  --- 견고성 및 안전성 ---

• 자동 메모리 관리: RAII(자원 획득 초기화) 디자인 패턴을 채택합니다. JsonDocument는 모든 노드의 수명 주기를 관리합니다. 개발자는 JSON 요소를 수동으로 새로 만들거나 삭제할 필요가 없으므로 메모리 누수 위험이 근본적으로 제거됩니다.

• 문서 간 작업 안전: 서로 다른 JsonDocument 인스턴스 간에 노드를 할당할 때 라이브러리가 자동으로 안전한 딥 카피(복제)를 수행하여 포인터가 매달려 있거나 우발적인 데이터 손상을 방지합니다.
• 상세한 오류 보고: 구문 분석에 실패하면 JsonError 객체가 오류 줄 번호, 열 번호, 컨텍스트 등 자세한 정보를 제공하여 신속한 문제 진단을 용이하게 합니다.

2. 핵심 개념 및 메모리 관리

[!!] 2.1 네임스페이스 - 프로젝트 통합의 핵심 [!!] 가장 중요한 팁: 이 라이브러리의 모든 클래스(예: JsonDocument , JsonNode )와 전역 함수(예: JsonParse )는 MQL5_Json이라는 네임스페이스 안에 캡슐화되어 있습니다.

**올바르게 사용하는 방법:** - **헤더 파일(.mqh)**에서: MQL5는 헤더 파일의 전역 범위에서 '네임스페이스 사용 '을 허용하지 않습니다. **따라서 정규화된 이름을 사용해야 합니다**. 이것이 다중 파일 프로젝트에서 유일하게 신뢰할 수 있는 방법입니다. 잘못된: `JsonDocument doc;` 올바른: `MQL5_Json::JsonDocument doc;` - **주 프로그램 파일(.mq5) 의 내부 함수 **: 편의상 함수 내부에 `사용 네임스페이스 MQL5_Json;`을 사용할 수 있지만 예제의 일반성을 보장하기 위해 이 매뉴얼의 모든 코드에서는 정규화된 이름 방식을 사용합니다 . ''JsonNode' - 유형이 없는 선언'' 컴파일 오류가 발생하는 경우 **대부분 유형과 함수에 `MQL5_Json::` 접두사를 추가하는 것을 잊어버렸기 때문입니다** ** **그것은 거의 항상 발생합니다** **.

[!!] 2.2 메모리 관리 모델 JsonDocument는 데이터를 소유하고, JsonNode는 단지 뷰일 뿐입니다.

[!!] 2.3 MQL5의 객체 전달 MQL5에서는 함수 인수로 전달되는 모든 클래스 객체(JsonNode 포함) 는 반드시 참조로 전달(& 사용)해야 합니다. 잘못된: void myFunction(MQL5_Json::JsonNode node) 올바른: void myFunction(MQL5_Json::JsonNode &node)