docparser-epub 0.1.0

# docparser-epub


EPUB2 / EPUB3 后端：`container.xml` → OPF（metadata / manifest / spine）→ 逐 spine 文档解析，
**每章保留结构化块**（标题 / 段落 / 列表 / 引用 / 代码 / 表格），而不是压平成一段文本。

## 安装


```bash
cargo add docparser-epub   # 或 cargo add docparser-sdk（含 core + pdf + office + epub）
```

## 用法


走统一引擎（推荐，`epub` 由扩展名 + ZIP magic 路由）：

```rust
use docparser_core::{DocumentEngine, Registry};

let mut reg = Registry::new();
docparser_core::plugins::text::register_defaults(&mut reg);
docparser_epub::register_defaults(&mut reg);
let doc = DocumentEngine::new(reg).parse("book.epub")?;
for page in &doc.pages {
    println!("{}: {} blocks", page.name.clone().unwrap_or_default(), page.blocks.len());
}
```

只想要书的结构化结果（元数据 + 分章块）：

```rust
let book = docparser_epub::read_epub("book.epub")?;
println!("{} / {:?} / {}", book.meta.title, book.meta.authors, book.meta.year);
for ch in &book.chapters {
    println!("[{}] {} 字", ch.title, ch.text.chars().count());
}
```

书库/缩略图场景只取封面与书名（不读正文）：

```rust
let (cover_href, title) = docparser_epub::epub_cover_href("book.epub");
```

## 结构解析规则


| 项 | 规则 |
| --- | --- |
| OPF 定位 | `META-INF/container.xml` → 首个 `rootfile@full-path` |
| 元数据 | `dc:title`（首个）/ `dc:creator`（全部）/ `dc:language` / `dc:publisher` / `dc:date` 中的四位年份 |
| 章节顺序 | `spine/itemref` 顺序即阅读顺序；`.ncx` 条目跳过 |
| 章节标题 | EPUB3 `nav`（`properties="nav"`）→ EPUB2 `toc.ncx` → 文档内首个标题 → `第N章` |
| 分章 | 单文档内多个标题时按层级自适应切节（h2 → h3 → h4；单节 > 8000 字才往深一层） |
| 封面 | `properties="cover-image"` → `<meta name="cover">` 指向的 manifest 条目 |
| 元数据出口 | `doc.meta.extra` 的 `epub.title` / `epub.authors` / `epub.language` / `epub.publisher` / `epub.year` / `epub.cover_href` |

## 已知边界


- **DRM 不解密**：带 `META-INF/encryption.xml` 的加密书会在读取正文时报 `corrupt`。
- 图片/字体/样式资源不解包，只记录封面路径。
- href 不做 percent-decoding（与 Python 参考实现一致）。
- 与 Python 的差异：Python 每章只给一段纯文本，这里保留块结构；空白处理沿用 HTML 插件的「只去首尾」。

## 许可


MIT OR Apache-2.0