# cfgparser

**Repository Path**: lyworkspace/cfgparser

## Basic Information

- **Project Name**: cfgparser
- **Description**: 持久化的配置文件管理工作，方便应用程序进行配置文件的加载与配置，提供便利的接口，避免用于管理配置文件的时间开销，只需要通过路径进来管理和配置参数
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-25
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cfgparser 库使用说明

`cfgparser` 提供了一个轻量级的配置存储与序列化方案，支持键值对的增删改查、二进制序列化、跨平台默认存储路径等能力。本说明简要介绍如何在项目中集成、使用以及测试该库。

## 功能概览

- **Preferences 接口**：存储不同类型的数据，包括整数、浮点数、字符串、数组、`std::vector`、智能指针等。
- **序列化 / 反序列化**：`serialize()` 返回 `std::vector<uint8_t>`，便于保存到文件或网络；`deserialize()` 支持从二进制缓冲区加载。
- **CFGParser 扩展**：在 `Preferences` 基础上新增文件路径概念，提供 `load()`、`save()`、`save_as()` 等文件操作方法。
- **可配置行为**：通过 `CFGParserOptions` 启用构造时自动加载、析构时自动保存等便捷特性。
- **默认路径工具**：`cfgparser_storage_path` 命名空间包含跨平台的配置 / 数据 / 日志路径推导与目录创建工具函数。

## 集成方式

1. 在 CMake 项目中引入 `lib/cfgparser` 子目录：
	```cmake
	add_subdirectory(lib/cfgparser)
	target_link_libraries(your_target PRIVATE cfgparser_lib)
	```
2. 头文件路径：`cfgparser.h`、`cfgparser_prefs.h`、`cfgparser_storage_path.h` 等位于 `lib/cfgparser/include/`。
3. 库默认以静态库形式构建，可根据需要在顶层 CMake 中调整编译选项。

## API 快速上手

### 创建解析器并保存 / 加载

```cpp
#include "cfgparser.h"

cfgparser::CFGParser parser("/path/to/config.bin");
parser.set("username", "alice");
parser.set("volume", 75);
parser.save();          // 保存到指定文件

cfgparser::CFGParser loader("/path/to/config.bin");
if (loader.load()) {
	 std::string username = loader.get("username", std::string{"<missing>"});
	 int volume = loader.get("volume", 0);
}
```

### 配置解析器行为

```cpp
cfgparser::CFGParserOptions options;
options.auto_load_on_construction = true;      // 构造时若文件存在则自动 load()
options.auto_save_on_destruction = true;       // 析构前若存在未保存改动则自动 save()
options.create_if_not_exists = true;           // 若文件缺失则自动创建一个空配置
options.backup_on_load = true;                 // 在 load() 前备份现有文件
options.backup_suffix = ".bak";               // 备份文件后缀，可按需修改

cfgparser::CFGParser auto_parser("/path/to/config.bin", options);
auto_parser.set("theme", "dark");
// 离开作用域时，如果数据被修改过，自动保存到文件

// 运行期间也可以更新配置：
cfgparser::CFGParserOptions new_options = auto_parser.get_options();
new_options.auto_save_on_destruction = false;
auto_parser.set_options(new_options);
```

### 使用序列化缓冲区

```cpp
// 序列化到内存
const std::vector<uint8_t> buffer = parser.serialize();
// 传输或保存 buffer...

// 从缓冲区还原
cfgparser::CFGParser temp("/tmp/unused.bin");
temp.deserialize(buffer.data(), buffer.size());
```

### 管理数组与向量

```cpp
std::vector<uint8_t> data = {0xDE, 0xAD, 0xBE, 0xEF};
parser.set("binary", data); // 支持 vector

auto loaded = parser.get("binary", std::vector<uint8_t>{});
```

更多类型支持可参考 `cfgparser_prefs.h` 中的注释与模板函数。

## 构建说明

- 顶层工程默认使用 C++23（可在 CMake 顶层修改）。
- `lib/cfgparser` 子模块内部要求 C++17 及以上（已在其 CMakeLists.txt 中设置）。
- 默认 **不** 构建测试可执行文件，减少依赖。

常规构建流程：
```bash
cmake -S . -B build
cmake --build build
```

## 测试指南

`cfgparser` 自带一个演示/测试程序 `cfgparser_demo`，位于 `lib/cfgparser/tests/cfgparser_demo.cpp`。它演示了 set/get/remove/save/save_as/load、线程安全读写以及自动保存/自动加载等完整流程。

### 启用测试并运行

1. 在配置阶段打开测试选项：
	```bash
	cmake -S . -B build -DPREVIZ_BUILD_TESTS=ON
	cmake --build build
	```
2. 运行测试：
	```bash
	cd build
	ctest --output-on-failure
	```
	或直接执行：
	```bash
	./lib/cfgparser/cfgparser_demo
	```

测试程序会在临时目录（例如 `/tmp/cfgparser_demo`）下生成配置文件，并在流程结束后清理。

## 命令行工具

`cfgparser` 模块内置了一个命令行工具 `cfgparser_cli`，方便直接查看或修改二进制配置文件。

### 快速体验

完成常规构建后，可在构建目录中找到可执行文件：

```bash
cmake --build build
./build/lib/cfgparser/cfgparser_cli --help
```

常见用法：

- 列出所有键值对：
	```bash
	./build/lib/cfgparser/cfgparser_cli list
	```
- 获取键值（可指定格式 `auto/string/int/float/hex`）：
	```bash
	./build/lib/cfgparser/cfgparser_cli get camera.fps int
	```
- 设置或删除键：
	```bash
	./build/lib/cfgparser/cfgparser_cli set camera.mode AUTO
	./build/lib/cfgparser/cfgparser_cli remove camera.mode
	```

默认情况下，工具会尝试操作 `~/.config/<app_name>/config.bin`。可以通过 `-c` 或 `--config` 指定其它路径：

```bash
./build/lib/cfgparser/cfgparser_cli --config ./config/mspecam.bin list
```

### 集成到自定义程序

如果希望在自己应用的命令行中复用该工具逻辑，可链接 `cfgparser_lib` 并直接调用 `cfgparser::cli::run`：

```cpp
#include "cfgparser_cli.h"

int main(int argc, char *argv[])
{
		// 可在调用前设置默认配置路径等自定义逻辑
		return cfgparser::cli::run(argc, argv);
}
```

在 CMake 中确保你的目标链接 `cfgparser_lib` 并包含头文件路径：

```cmake
target_link_libraries(your_cli_target PRIVATE cfgparser_lib)
target_include_directories(your_cli_target PRIVATE lib/cfgparser/include)
```

若需扩展自定义命令，可参考 `lib/cfgparser/tools/cfgparser_cli_app.cpp`，在调用前调整参数解析或在 `run` 函数内添加新分支。

## 常见问题

- **无法加载配置文件**：确认文件存在且 `deserialize` 返回 `true`。如果结构变化，可重新生成配置文件。
- **序列化大小不匹配**：检查 `serialize_data_size()` 与实际 `serialize()` 结果，确保缓冲区写入完整。
- **跨平台路径**：使用 `cfgparser::get_default_config_path()` 等工具函数获取合适的目录，并调用 `create_directory()` 创建。

## 目录结构概览

```
lib/cfgparser/
├── include/
│   ├── cfgparser.h
│   ├── cfgparser_prefs.h
│   └── cfgparser_storage_path.h
├── src/
│   ├── cfgparser.cpp
│   └── cfgparser_storage_path.cpp
├── tests/
│   └── cfgparser_demo.cpp
├── CMakeLists.txt
└── README.md (本文件)
```

如需扩展功能（例如自定义序列化格式、更多类型支持、与 GUI/网络集成等），可以在 `Preferences` 基类上进一步派生。欢迎根据项目需求添加单元测试或文档说明。