# xml2cppobject

**Repository Path**: PatchLion_admin/xml2cppobject

## Basic Information

- **Project Name**: xml2cppobject
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xml2cppobject

一个基于 pugixml 的轻量级 C++ 库，用于将 XML 数据映射到 C++ 对象。

## 功能特性

- **简单映射**：使用宏定义 XML 属性和子元素为 C++ 类成员
- **代码生成**：Python 脚本自动从 XML 文件生成 C++ 类
- **Pimpl 模式**：公共接口与私有实现的清晰分离
- **C++17**：现代 C++ 标准支持
- **跨平台**：支持 Windows、Linux 和 macOS

## 项目结构

```
xml2cppobject/
├── CMakeLists.txt              # 根目录 CMake 配置
├── generate_classes.py         # Python 代码生成脚本
├── xml2cppobject/              # 核心库
│   ├── CMakeLists.txt
│   ├── xmlobjectbase.h         # 宏和基类头文件
│   └── xmlobjectbase.cpp       # 实现
├── tests/                      # 测试示例
│   ├── CMakeLists.txt
│   ├── test_school.cpp         # 学校场景测试
│   ├── test_school.xml         # 学校场景 XML
│   ├── test_keyword.cpp        # C++ 关键字规避测试
│   └── test_keyword.xml        # 关键字测试 XML
└── pugixml/                    # 第三方 XML 解析器（子模块）
```

## 构建

### 环境要求

- CMake 3.10+
- C++17 编译器
- Python 3.x（用于代码生成）

### 构建步骤

```bash
# 克隆仓库
git clone <仓库地址>
cd xml2cppobject

# 初始化子模块
git submodule update --init --recursive

# 构建
cmake -B build
cmake --build build
```

### 构建选项

| 选项 | 默认值 | 说明 |
|--------|---------|-------------|
| `BUILD_TESTS` | ON | 构建测试程序 |

```bash
# 不构建测试
cmake -B build -DBUILD_TESTS=OFF
```

## 使用方法

### 手动定义类

#### 1. 创建 XML 文件

```xml
<?xml version="1.0" encoding="UTF-8"?>
<School name="我的学校" address="123 街道">
    <Teacher id="T001" name="张老师" subject="数学"/>
    <Class id="C101" name="十年级">
        <Student id="S001" name="小明" score="95"/>
    </Class>
</School>
```

#### 2. 定义 C++ 类(通过generate_classes.py生成，见后面章节)

```cpp
#include "xmlobjectbase.h"

class Teacher : public XmlObjectBase
{
public:
    Teacher() : XmlObjectBase() {}
    Teacher(xml_node node) : XmlObjectBase(node) {}

    DEFINE_ATTR(id);
    DEFINE_ATTR(name);
    DEFINE_ATTR(subject);
};

class Student : public XmlObjectBase
{
public:
    Student() : XmlObjectBase() {}
    Student(xml_node node) : XmlObjectBase(node) {}

    DEFINE_ATTR(id);
    DEFINE_ATTR(name);
    DEFINE_ATTR(score);
};

class Class : public XmlObjectBase
{
public:
    Class() : XmlObjectBase() {}
    Class(xml_node node) : XmlObjectBase(node) {}

    DEFINE_ATTR(id);
    DEFINE_ATTR(name);

    DEFINE_CHILD(Student, Student, student);
};

class School : public XmlObjectBase
{
public:
    School() : XmlObjectBase() {}
    School(xml_node node) : XmlObjectBase(node) {}

    DEFINE_ATTR(name);
    DEFINE_ATTR(address);

    DEFINE_CHILD(Teacher, Teacher, teacher);
    DEFINE_CHILD(Class, Class, cls);
};
```

#### 3. 在代码中使用

```cpp
#include "school.h"
#include <iostream>

int main()
{
    XmlRoot root;
    if (!root.loadRootXml("school.xml")) {
        std::cerr << "加载 XML 失败！" << std::endl;
        return -1;
    }

    // 从 root 创建 School 对象
    auto school = root.object<School>("School");

    // 访问属性
    std::cout << "学校：" << school->_name().value() << std::endl;

    // 遍历子元素
    for (size_t i = 0; i < school->teacherCount(); ++i) {
        auto teacher = school->teacher(i);
        std::cout << "老师：" << teacher->_name().value() << std::endl;
    }

    return 0;
}
```

### 自动代码生成

使用 `generate_classes.py` 从 XML 自动生成 C++ 类：

```bash
python generate_classes.py <xml路径> <类前缀> <输出目录>
```

**参数说明：**
- `xml路径`：XML 文件路径
- `类前缀`：生成类名的前缀（如 "Abc" 将生成 AbcSchool）
- `输出目录`：生成的头文件输出目录

**示例：**

```bash
# 生成带 "Test" 前缀的类
python generate_classes.py tests/test_school.xml "Test" build/tests/generated
```

这将在 `build/tests/generated/test_school.h` 中生成以下类：
- `TestSchool`
- `TestTeacher`
- `TestClass`
- `TestStudent`

### C++ 关键字规避

代码生成器自动处理 C++ 关键字，通过添加 `_` 后缀：

- 属性名 `class` 变为 `_class_`
- 元素名 `public` 变为 `public_`
- 类名 `Class`（首字母大写）不是关键字，保持不变

支持的关键字包括所有 C++20 保留字：`class`、`struct`、`public`、`private`、`const`、`virtual`、`int`、`for`、`while` 等。

## 宏参考

### DEFINE_ATTR(attrname)

定义 XML 属性的 getter 和 setter 方法。

**生成的方法：**
- `xml_attribute _attrname() const` - 获取属性
- `void set_attrname(xml_attribute attr)` - 设置属性

### DEFINE_CHILD(classtype, nodename, membername)

定义访问子元素的方法。

**生成的方法：**
- `classtype* object<classtype>(const char* name, size_t index)` - 按索引获取子元素
- `std::vector<classtype*> objects<classtype>(const char* name)` - 获取所有子元素
- `size_t membernameCount() const` - 获取子元素数量
- `classtype* membername(size_t index)` - 按索引获取（便捷方法）
- `std::vector<classtype*> membernameAll()` - 获取所有子元素（便捷方法）

## 类参考

### XmlObjectBase

所有 XML 映射对象的基类。

**方法：**
- `node()` - 获取底层 xml_node
- `attributeKeys()` - 获取所有属性名
- `childKeys()` - 获取所有子元素名（去重）
- `attribute(name)` - 按名称获取属性
- `processEachAttribute(func)` - 遍历所有属性

### XmlRoot

加载 XML 文档的根类。

**方法：**
- `loadRootXml(path)` - 从文件加载 XML
- `writeToFile(path)` - 将 XML 写入文件
- `node()` - 获取文档元素

## 许可证

本项目使用：
- **pugixml**：MIT 许可证（见 pugixml/LICENSE.md）
- **xml2cppobject**：MIT 许可证

## 依赖

- [pugixml](https://github.com/zeux/pugixml) - 轻量、简单、快速的 C++ XML 解析器