lanyuanxiaoyao/PPTX
1
0
Fork 0
Code Activity
Files
16ca9d77cd9c114a7e45bb33441b07affca2406f
PPTX/openspec/specs/yaml-parsing/spec.md
lanyuanxiaoyao cd7988cbd5 feat: initial implementation of html2pptx with OpenSpec documentation 
Add core Python script (yaml2pptx.py) for converting YAML to PowerPoint:
- Element rendering: text, image, shape, table, chart
- Template system with placeholders
- PPTX generation with python-pptx

OpenSpec workflow setup:
- 3 archived changes: browser-preview, template-dir-cli, yaml-to-pptx
- 7 main specifications covering all core modules
- Config and documentation structure

30 files changed, 4984 insertions(+)
2026-03-02 14:28:25 +08:00

3.3 KiB
Raw Blame History

YAML Parsing

Purpose

YAML parsing 系统负责读取和验证演示文稿和模板的 YAML 文件。它支持 UTF-8 编码、验证颜色格式、验证文件结构，并提供清晰的错误消息帮助用户定位问题。

Requirements

Requirement: 系统必须能解析演示文稿 YAML 文件

系统 SHALL 能够解析包含 metadata 和 slides 的演示文稿 YAML 文件，并验证其结构的正确性。

Scenario: 解析有效的演示文稿 YAML

  • WHEN 提供一个包含 metadata 和 slides 字段的 YAML 文件
  • THEN 系统成功解析并返回 Python 字典结构

Scenario: 检测缺少必需字段

  • WHEN 提供的 YAML 文件缺少 slides 字段
  • THEN 系统抛出验证错误，明确指出缺少必需字段

Scenario: 处理无效的 YAML 语法

  • WHEN 提供的文件包含无效的 YAML 语法（如缩进错误）
  • THEN 系统抛出解析错误，包含行号和错误描述

Requirement: 系统必须验证颜色值格式

系统 SHALL 验证模板和演示文稿 YAML 文件中的颜色值为有效的十六进制格式。

Scenario: 验证有效的颜色值

  • WHEN 模板或演示文稿 YAML 文件中包含 color: "#4a90e2" 的颜色值
  • THEN 系统接受该颜色值

Scenario: 验证颜色值格式错误

  • WHEN 颜色值格式不正确（如 "blue" 或 "#xyz"）
  • THEN 系统抛出验证错误，提示使用 #RRGGBB 格式

Scenario: 支持短格式颜色值

  • WHEN 颜色值为短格式 "#fff"
  • THEN 系统自动扩展为 "#ffffff" 并接受

Requirement: 系统必须能解析模板 YAML 文件

系统 SHALL 能够解析包含 vars 定义和 elements 列表的模板 YAML 文件。

Scenario: 解析有效的模板文件

  • WHEN 提供一个包含 vars 和 elements 字段的模板 YAML 文件
  • THEN 系统成功解析并返回模板对象

Scenario: 验证变量定义的完整性

  • WHEN 模板 vars 中的变量缺少 name 字段
  • THEN 系统抛出验证错误，指出变量定义不完整

Scenario: 验证必需变量标记

  • WHEN 模板 vars 中定义了 required: true 的变量
  • THEN 系统记录该变量为必需变量，在渲染时必须提供值

Requirement: 系统必须支持 UTF-8 编码

系统 SHALL 以 UTF-8 编码读取所有 YAML 文件，支持中文等多字节字符。

Scenario: 解析包含中文的 YAML 文件

  • WHEN 提供包含中文字符的 YAML 文件
  • THEN 系统正确解析中文内容，不出现乱码

Scenario: 处理 BOM 标记

  • WHEN YAML 文件包含 UTF-8 BOM 标记
  • THEN 系统能够正确处理并解析文件内容

Requirement: 系统必须提供清晰的错误消息

系统 SHALL 在 YAML 解析失败时提供包含文件路径、行号、错误原因的详细错误消息。

Scenario: YAML 语法错误的错误消息

  • WHEN YAML 文件在第 10 行存在缩进错误
  • THEN 错误消息包含 "文件路径, 第 10 行: 缩进错误" 等信息

Scenario: 文件不存在的错误消息

  • WHEN 尝试加载不存在的 YAML 文件
  • THEN 错误消息明确指出文件路径不存在

Scenario: 权限不足的错误消息

  • WHEN YAML 文件存在但没有读取权限
  • THEN 错误消息提示权限不足，无法读取文件
View Git Blame Copy Permalink