includes/Tools/json_parser.h - master - Zamar_Terrier/TigorEngine

includes/Tools/json_parser.h
183 строки9 KB
Zamar_Terrier
Офигенное обновление движка
31 июл 2026, 21:03
31 июл 2026, 21:031682686
/**
 * @file json_parser.h
 * @brief Библиотека парсинга и сериализации JSON-данных
 * @details Предоставляет полную реализацию парсера JSON, поддерживающую нулевые значения, булевы типы, числа, строки, массивы и объекты. Включает функции для создания, модификации, парсинга и освобождения JSON-структур.
 */

#ifndef JSON_PARSER_H
#define JSON_PARSER_H

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/**
 * @brief Типы данных JSON
 */
typedef enum {
    JSON_NULL,      ///< Нулевое значение
    JSON_BOOL,      ///< Булево значение (true/false)
    JSON_NUMBER,    ///< Числовое значение (целое или с плавающей точкой)
    JSON_STRING,    ///< Строковое значение
    JSON_ARRAY,     ///< Упорядоченный список значений
    JSON_OBJECT     ///< Коллекция пар ключ-значение
} json_type_t;

/**
 * @brief Переднее объявление структуры JSON-значения
 */
struct json_value;

/**
 * @brief Элемент JSON-массива
 */
typedef struct json_element {
    struct json_value* value;     ///< Указатель на JSON-значение
    struct json_element* next;    ///< Указатель на следующий элемент массива
} json_element_t;

/**
 * @brief Пара ключ-значение в JSON-объекте
 */
typedef struct json_pair {
    char* key;                    ///< Строка ключа
    struct json_value* value;     ///< Указатель на JSON-значение
    struct json_pair* next;       ///< Указатель на следующую пару ключ-значение
} json_pair_t;

/**
 * @brief Контейнер JSON-значения
 * @details Использует объединение для эффективного хранения различных типов JSON в одной структуре
 */
typedef struct json_value {
    json_type_t type;             ///< Тип JSON-значения
    union {
        int boolean;              ///< Булево значение
        double number;            ///< Числовое значение
        char* string;             ///< Строковое значение
        json_element_t* array;    ///< Массив значений
        json_pair_t* object;      ///< Объект с парами ключ-значение
    } data;                       ///< Объединение всех возможных типов значений
} json_value_t;

/**
 * @brief Создает нулевое JSON-значение
 * @return Указатель на вновь созданное нулевое значение, или NULL при ошибке
 */
json_value_t* json_null();

/**
 * @brief Создает булево JSON-значение
 * @param boolean Булево значение (0 для false, не-ноль для true)
 * @return Указатель на вновь созданное булево значение, или NULL при ошибке
 */
json_value_t* json_boolean(int boolean);

/**
 * @brief Создает числовое JSON-значение
 * @param number Числовое значение для хранения
 * @return Указатель на вновь созданное числовое значение, или NULL при ошибке
 */
json_value_t* json_number(double number);

/**
 * @brief Создает строковое JSON-значение
 * @param string Null-terminated строка для хранения (будет скопирована)
 * @return Указатель на вновь созданное строковое значение, или NULL при ошибке
 */
json_value_t* json_string(const char* string);

/**
 * @brief Создает пустой JSON-массив
 * @return Указатель на вновь созданный пустой массив, или NULL при ошибке
 */
json_value_t* json_array();

/**
 * @brief Создает пустой JSON-объект
 * @return Указатель на вновь созданный пустой объект, или NULL при ошибке
 */
json_value_t* json_object();

/**
 * @brief Итерирует по парам ключ-значение в JSON-объекте
 * @param item Переменная для хранения текущей пары во время итерации
 * @param root Корневой JSON-объект для итерации
 * @details Использование: for_each_json_object(pair, root) { ... }
 */
#define for_each_json_object(item, root) \
    for(json_pair_t *item = root->data.object; item != NULL; item = item->next)

/**
 * @brief Итерирует по элементам в JSON-массиве
 * @param item Переменная для хранения текущего элемента во время итерации
 * @param iterator Целочисленная переменная для отслеживания индекса
 * @param array Корневой JSON-массив для итерации
 * @details Использование: for_each_json_array(element, idx, array) { ... }
 */
#define for_each_json_array(item, iterator, array) \
    int iterator = 0; \
    for(json_element_t *item = array; item != NULL; item = item->next, iterator++)

/**
 * @brief Добавляет значение в JSON-массив
 * @param array Указатель на JSON-массив
 * @param value Указатель на JSON-значение для добавления
 * @return 0 при успехе, -1 при ошибке
 */
int json_array_add(json_value_t* array, json_value_t* value);

/**
 * @brief Получает значение по индексу в JSON-массиве
 * @param array Указатель на JSON-массив
 * @param index Индекс значения для получения (начинается с 0)
 * @return Указатель на JSON-значение по указанному индексу, или NULL если индекс вне границ
 */
json_value_t* json_array_get(json_value_t* array, int index);

/**
 * @brief Получает количество элементов в JSON-массиве
 * @param array Указатель на JSON-массив
 * @return Количество элементов в массиве
 */
int json_array_size(json_value_t* array);

/**
 * @brief Устанавливает пару ключ-значение в JSON-объекте
 * @param object Указатель на JSON-объект
 * @param key Null-terminated строка ключа
 * @param value Указатель на JSON-значение для ассоциации с ключом
 * @return 0 при успехе, -1 при ошибке
 */
int json_object_set(json_value_t* object, const char* key, json_value_t* value);

/**
 * @brief Получает значение по ключу из JSON-объекта
 * @param object Указатель на JSON-объект
 * @param key Null-terminated строка ключа для поиска
 * @return Указатель на JSON-значение, ассоциированное с ключом, или NULL если ключ не найден
 */
json_value_t* json_object_get(json_value_t* object, const char* key);

/**
 * @brief Парсит JSON-строку и создает JSON-структуру
 * @param json_str Null-terminated JSON-строка для парсинга
 * @return Указатель на корневую структуру JSON-значения, или NULL при ошибке парсинга
 */
json_value_t* json_parse(const char* json_str);

/**
 * @brief Сериализует JSON-структуру в строку
 * @param value Указатель на JSON-значение для сериализации
 * @return Новая выделенная null-terminated строка, содержащая JSON-представление, или NULL при ошибке
 * @note Вызывающая сторона ответственна за освобождение возвращенной строки
 */
char* json_stringify(const json_value_t* value);

/**
 * @brief Освобождает всю память, связанную с JSON-значением и его дочерними элементами
 * @param value Указатель на JSON-значение для освобождения
 */
void json_free(json_value_t* value);

#endif // JSON_PARSER_H