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

includes/Tools/xml_parser.h
123 строки6 KB
Zamar_Terrier
Офигенное обновление движка
31 июл 2026, 21:03
31 июл 2026, 21:031682686
/**
* @file xml_parser.h
* @brief Библиотека для парсинга и работы с XML-документами
* @details Предоставляет полный набор функций для создания, парсинга, сериализации и сохранения XML-документов. Поддерживает работу с атрибутами, дочерними узлами, поиском узлов по имени и иерархической структурой XML.
*/
#ifndef XML_PARSER_H
#define XML_PARSER_H
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <stdbool.h>

/**
* @brief Структура для хранения атрибута XML-элемента
* @details Содержит пару имя-значение для XML-атрибутов
*/
typedef struct {
   char* name;
   char* value;
} xml_attribute_t;

/**
* @brief Структура для хранения узла XML-документа
* @details Представляет элемент XML-документа с именем, значением, атрибутами и иерархией дочерних узлов
*/
typedef struct xml_node {
   char* name;
   char* value;
   struct xml_node* parent;
   struct xml_node* children;
   struct xml_node* next;
   xml_attribute_t* attributes;
   int attr_count;
   int child_count;
} xml_node_t;

/**
* @brief Создание нового XML-узла
* @param name Имя создаваемого узла (null-terminated строка)
* @return Указатель на вновь созданный узел, или NULL при ошибке
* @details Выделяет память для узла и инициализирует его базовыми полями
*/
xml_node_t* xml_create_node(const char* name);

/**
* @brief Освобождение памяти узла и всех его потомков
* @param node Указатель на узел для освобождения
* @details Рекурсивно освобождает память: узел, дочерние узлы, атрибуты и все связанные строки
*/
void xml_free_node(xml_node_t* node);

/**
* @brief Добавление атрибута к XML-узлу
* @param node Указатель на XML-узел
* @param name Имя атрибута (будет скопировано)
* @param value Значение атрибута (будет скопировано)
* @return 0 при успехе, -1 при ошибке
* @details Выделяет память для атрибута и добавляет его к списку атрибутов узла
*/
int xml_add_attribute(xml_node_t* node, const char* name, const char* value);

/**
* @brief Получение значения атрибута по имени
* @param node Указатель на XML-узел
* @param name Имя атрибута для поиска
* @return Указатель на значение атрибута, или NULL если атрибут не найден
* @details Выполняет линейный поиск атрибута в списке узла
*/
char* xml_get_attribute(xml_node_t* node, const char* name);

/**
* @brief Добавление дочернего узла к родительскому узлу
* @param parent Указатель на родительский узел
* @param child Указатель на дочерний узел (не должен быть NULL)
* @return 0 при успехе, -1 при ошибке
* @details Добавляет узел в конец списка дочерних узлов и устанавливает ссылку на родителя
*/
int xml_add_child(xml_node_t* parent, xml_node_t* child);

/**
* @brief Поиск узла по имени (в глубину)
* @param root Корневой узел для поиска
* @param name Имя искомого узла
* @return Указатель на первый найденный узел, или NULL если не найден
* @details Выполняет DFS-поиск по дереву XML-документа
*/
xml_node_t* xml_find_node(xml_node_t* root, const char* name);

/**
* @brief Парсинг XML-документа из строки
* @param str_point Указатель на указатель строки с XML-данными
* @param parent Родительский узел (для вложенных элементов)
* @return Корневой узел разобранного XML-документа, или NULL при ошибке
* @details Парсит XML-синтаксис, создает дерево узлов, обрабатывает атрибуты и вложенные элементы
*/
xml_node_t* xml_parse(const char **str_point, xml_node_t *parent);

/**
* @brief Сериализация XML-узла в строку
* @param node Указатель на узел для сериализации
* @return Новая строка с XML-представлением узла, или NULL при ошибке
* @details Рекурсивно генерирует XML-строку в формате <tag>content</tag>
*/
char* xml_serialize(xml_node_t* node);

/**
* @brief Чтение XML-документа из файла
* @param filename Путь к файлу с XML-документом
* @return Корневой узел разобранного XML-документа, или NULL при ошибке
* @details Читает весь файл в память и вызывает xml_parse
*/
xml_node_t* xml_read_file(const char* filename);

/**
* @brief Запись XML-документа в файл
* @param node Корневой узел для записи
* @param filename Путь к выходному файлу
* @return 0 при успехе, -1 при ошибке
* @details Сериализует узел в строку и записывает в файл
*/
int xml_write_file(xml_node_t* node, const char* filename);

#endif // XML_PARSER_H