# ConfigPlus

**Repository Path**: KillBugX/config-plus

## Basic Information

- **Project Name**: ConfigPlus
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ConfigPlus

基于表格的配置表导出工具。Python 实现在仓库 `src/` 目录下，包名为 **config_plus**：从多种数据源读入二维矩阵、解析表头与宏、校验字段类型与数据，再通过 **Jinja2** 模板或内置序列化生成 JSON、Lua、C#、YAML、BSON 等产物。

---

## 功能概览

- **数据源**：支持 **`.csv`**（UTF-8，含 BOM）、**`.xls`**、**`.xlsx`**、**`.xlsm`**（活动工作表）、**`.json`**（根为二维数组，或 `{"rows": [[...], ...]}`）、**`.xml`**（`//row` 下 `cell`/`c`/`td` 等单元格）。
- 支持表内 **宏**（如 `#name`、`#index`）与预置索引宏（与原先逻辑一致：`index unique id`）。
- 对字段 **元数据**（类型名、列名等）与已知类型的 **单元格取值** 做校验。
- 按 **模板集**（`--special`）选择 `resources/templates/special/<名称>/` 下的 Jinja2 模板并渲染输出。
- 可通过 **当前工作目录** 下的 `config_plus/templates/<special>/` **覆盖** 内置模板或 `config.json`。

---

## 环境要求

- Python **3.10+**
- 依赖见 `src/pyproject.toml`（`openpyxl`、`Jinja2`、`pyyaml`、`msgpack`、`xlrd` 等；导出 **BSON** 时需额外 `pip install pymongo` 或 `pip install -e ".[formats-bson]"`）

---

## 安装

在仓库中进入 **`src` 目录**（`pyproject.toml` 所在位置）执行：

```bash
cd src
pip install -e "."
```

开发依赖（含 pytest）：

```bash
pip install -e ".[dev]"
```

安装后可在命令行使用入口 **`config_plus`**，或通过模块方式运行：

```bash
python -m config_plus --help
```

---

## 命令行参数

| 参数 | 说明 |
|------|------|
| `-i` / `--input` | 输入文件路径（必填），扩展名决定解析方式，见上文「数据源」 |
| `-o` / `--output` | 输出目录（必填，不存在会自动创建） |
| `-s` / `--special` | 模板集名称（必填），见下文「模板集」 |
| `-n` / `--name` | 覆盖导出文件主文件名（不含扩展名）；若表内未指定 `#name` 且未指定本参数，则使用 Excel 文件名（不含扩展名） |
| `-t` / `--tag` | 预留字段，当前导出流程中未参与逻辑 |
| `-O` / `--option` | 可重复；每次传入 `键=值`，注入模板上下文 `root.macros.options`，供模板读取（如 C#/Lua 命名空间等） |

**`-O` 示例：**

```bash
-O csharp_namespace=Cfg -O lua_modelname=Cfg
```

---

## 模板集（`--special`）

内置模板位于包内：`config_plus/resources/templates/special/<special>/`，并与 `config_plus/resources/templates/core/` 中的公共片段组合使用。

| special | 典型输出 | 说明 |
|---------|----------|------|
| `json` | `*.json` | 通用 JSON 数据与索引结构 |
| `lua` | `*.lua` | 单文件 Lua 模块（含数据与索引及访问函数） |
| `lua2` | `*.data.lua`、`*.code.lua` | 数据与代码拆分为两个文件（由该目录下 `config.json` 配置） |
| `unity-litjson` | `*.cs`、`*.json` | Unity C#（LitJson）包装类 + 配套 JSON |
| `unity-json.net` | `*.cs`、`*.json` | Unity C#（Newtonsoft.Json）包装类 + 配套 JSON |
| `data-yaml` | `*.yaml` | 与内置 `json` 模板**同一数据结构**（`data` + `index`），由程序写出 YAML，不经 Jinja |
| `data-xml` | `*.xml` | 同上结构的 XML 表示 |
| `data-msgpack` / `data-binary` | `*.bin` | **MessagePack** 二进制（`data-binary` 为别名） |
| `data-bson` | `*.bson` | **MongoDB BSON**（需安装 `pymongo`） |

每个模板集目录下可有 **`config.json`**，用于声明生成哪些文件、扩展名、主模板文件名、文件名风格（`pascal` / `camel` / `snake`）等。若未找到配置文件，则使用默认的单文件导出规则（与原先默认行为一致）。

---

## 导出文件名与选项

- **表内宏** `#name <名称>` 会作为配置表逻辑名，并参与默认导出主文件名（若存在）。
- **`-n`** 可在未由表内命名时覆盖默认主文件名。
- 模板中常用的 **`root.macros.options`** 键示例：
  - **C#**：`csharp_namespace`（命名空间，模板内一般有默认值 `Table`）
  - **Lua**：`lua_modelname`（模块/配置名相关，模板内一般有默认值 `Cfg`）

---

## 自定义模板（覆盖内置）

在**运行命令时的当前工作目录**下放置：

```text
config_plus/templates/<special>/
  config.json          # 可选，与内置格式相同
  main.tera.j2         # 以及其它 *.tera.j2 片段
```

加载顺序为：**先**尝试当前目录下的 `config_plus/templates/<special>/`，再使用包内 `resources/templates/special/<special>/` 与 `core`。同名模板以前者优先，便于项目内覆盖而不改源码。

---

## 使用案例

以下均在 **`src` 目录**下执行（或保证已安装 `config_plus` 且工作目录符合你对「自定义模板路径」的预期）。

### 1. 导出 JSON

```bash
python -m config_plus -s json -o ./out_json -i ./path/to/config.xlsx
```

### 2. Unity（LitJson）+ 指定命名空间

```bash
python -m config_plus -s unity-litjson -o ./out_cs -i ./path/to/config.xlsx -O csharp_namespace=MyGame.Cfg
```

### 3. Lua 单文件

```bash
python -m config_plus -s lua -o ./out_lua -i ./path/to/config.xlsx -O lua_modelname=Cfg
```

### 4. Lua2（数据 + 代码两个文件）

```bash
python -m config_plus -s lua2 -o ./out_lua2 -i ./path/to/config.xlsx
```

### 5. 使用已安装的入口命令

```bash
config_plus -s json -o ./out -i ./path/to/config.xlsx
```

---

## Excel 表结构（约定）

解析规则与原先工具一致，简要说明如下：

1. 从首列出现 **`#`** 的行开始视为表头起点（否则从第 0 行起算）。
2. 表头共 **5 行**：第 1 行为宏行（如 `#name actor`）；其后 **4 行**依次为标签、类型、字段名、注释（列从第 1 列起为字段列）。
3. 列级忽略：标签格为 `-` 的列跳过。
4. 数据行：首列为 `-` 的行忽略；全空行忽略。
5. 类型校验：对内置映射的类型（如 `int`、`bool`、`json`、`array` 等）按正则校验单元格字符串；未映射类型仅校验标识符格式，由模板决定具体语义。

---

## 开发与测试

在 `src` 目录：

```bash
pip install -e ".[dev]"
pytest -q
```

测试数据可放在 `src/tests/fixtures/`（例如 `actor.xlsx`）。

---

## 持续集成

示例文件位于 `src/gitlab-ci.yml` 与 `src/Jenkinsfile`（路径相对于仓库根目录 `ConfigPlus`）。若仓库根目录即为 `src`，请将其中 `pip install -e "src/.[dev]"` 等路径按实际目录调整。

---

## 许可证与贡献

如需贡献代码，请使用分支开发与 Pull Request；具体许可证以仓库声明为准（若尚未添加 LICENSE，可由维护者补充）。