Home - chiba233/yumeDSL GitHub Wiki
yume-dsl-rich-text Wiki
Zero-dependency, O(n) rich-text DSL parser. 10 million nested layers, still finishes. Text in, token tree out — tag semantics, rendering, framework: all yours to define.
Live demo — Vue 3 + CodeMirror editor with real-time parseStructural +
parseSlice
visualization, handler registry toggle, and syntax highlighting.
在线演示 — Vue 3 + CodeMirror 编辑器，实时展示 parseStructural +
parseSlice
局部重解析、handler 开关、语法高亮。
Thanks to Claude and Codex for their tireless patience in iterating on the design and implementation with me.
感谢 Claude 和 Codex 在设计与实现过程中不厌其烦地陪我反复打磨方案。
Test Coverage (v1.2.6)
Overall: 98.35% statements, 92.38% branches, 96.66% functions across runtime source files (lines: 98.35%). Coverage
includes parsing, position tracking, traversal, serialization, stable IDs, zones, deprecations, deep nesting, dist smoke
checks, incremental parsing, and type checking. Run pnpm run test:coverage to regenerate; HTML report at
coverage/index.html.
English
Getting Started
| Page | Description |
|---|---|
| Getting Started | Install, first parse, and how to think about the parser |
| DSL Syntax | The three tag forms, pipe parameters, escape sequences |
Core API
| Page | Description |
|---|---|
| API Reference | createParser, parseRichText, parseStructural, printStructural |
| ParseOptions | Every option explained with scenarios |
| Token Structure | TextToken, TokenDraft, strong typing patterns |
Customization
| Page | Description |
|---|---|
| Custom Syntax | Swap $$ for any prefix, configure all tokens |
| Custom Tag Name Characters | Allow colons, digits, or any character in tag names |
Tag Handlers
| Page | Description |
|---|---|
| Handler Helpers | Bulk-register tags without boilerplate |
| Writing Tag Handlers | Manual handlers for complex logic |
| Handler Utilities | Every utility function in depth |
Advanced
| Page | Description |
|---|---|
| Stable Token IDs | Content-based IDs for UI keying |
| Token Traversal | walkTokens, mapTokens — visit and transform trees |
| Source Position Tracking | Offset/line/column tracking and substring position mapping |
| DslContext | The context object that ties everything together |
| Error Handling | Error codes, graceful degradation scenarios |
| Version Semantics Notes | Upgrade-sensitive behavior changes across versions |
Performance Notes
| Page | Description |
|---|---|
| Performance | Main benchmark page: 200 KB full-document parse, tracking overhead, parseSlice, deep-nesting stress |
| Incremental Parsing | Zone-based incremental structural cache for editor workflows |
| Linear-Time Complexity | Why Θ(n), what n means, empirical constants, and what controls the hidden constant factor |
Tutorials
| Page | Description |
|---|---|
| Tutorial: Building a Link Tag | From zero to a working $$link(url | text)$$ — step by step |
| Tutorial: Game Dialogue Tags | Build shake/color/wait tags for a visual novel typewriter |
| Tutorial: Safe UGC Chat | Whitelist inline tags, block dangerous forms, handle errors |
Integration & Reference
| Page | Description |
|---|---|
| Vue 3 Rendering | Drop-in recursive Vue 3 component |
| React Rendering | Drop-in recursive React component |
| Exports | Complete export table with links |
| Deprecated API | Migration guide for transitional APIs |
| Version Semantics Notes | Version-specific semantic or observable behavior changes |
| Contributing | How to contribute |
| Security | Security policy |
中文
入门
| 页面 | 说明 |
|---|---|
| 快速开始 | 安装、第一次解析、理解解析器的思路 |
| DSL 语法 | 三种标签形式、管道参数、转义序列 |
核心 API
| 页面 | 说明 |
|---|---|
| API 参考 | createParser、parseRichText、parseStructural、printStructural |
| ParseOptions 选项 | 每个选项的详细说明与使用场景 |
| Token 结构 | TextToken、TokenDraft、强类型模式 |
定制
| 页面 | 说明 |
|---|---|
| 自定义语法 | 把 $$ 换成任意前缀，配置所有符号 |
| 自定义标签名字符 | 允许冒号、数字或任意字符出现在标签名中 |
标签处理器
| 页面 | 说明 |
|---|---|
| 处理器辅助函数 | 批量注册标签，减少重复代码 |
| 编写标签处理器 | 复杂逻辑的手写处理器 |
| 处理器工具函数 | 每个工具函数的详细说明 |
进阶
| 页面 | 说明 |
|---|---|
| 稳定 Token ID | 基于内容的 ID，适用于 UI keying |
| Token 遍历 | walkTokens、mapTokens——遍历与变换 token 树 |
| 源码位置追踪 | offset/line/column 追踪与子串位置映射 |
| DslContext | 串联一切的上下文对象 |
| 错误处理 | 错误码、优雅降级场景 |
性能说明
| 页面 | 说明 |
|---|---|
| 性能 | 性能主页面：200 KB 全量基准、位置追踪开销、parseSlice 增量解析、深层嵌套压力测试 |
| 增量解析 | 基于 zone 的 structural 增量缓存，用于编辑器按键级更新 |
| 线性时间复杂度 | 为什么是 Θ(n)、n 的定义、经验常数、以及常数倍率由什么决定 |
实战教程
| 页面 | 说明 |
|---|---|
| 教程：从零实现 link 标签 | 从零到一个可用的 $$link(url | text)$$，逐步讲解 |
| 教程：游戏对话标签 | 为视觉小说打字机构建 shake/color/wait 标签 |
| 教程：安全 UGC 聊天 | 白名单 inline 标签、屏蔽危险形式、处理错误 |
集成与参考
| 页面 | 说明 |
|---|---|
| Vue 3 渲染 | 即插即用的递归 Vue 3 组件 |
| React 渲染 | 即插即用的递归 React 组件 |
| 导出一览 | 完整导出表与链接 |
| 版本语义说明 | 版本升级时需要关注的语义/行为差异 |
| 待弃用 API | 过渡 API 迁移指南 |
| 贡献指南 | 如何贡献 |
| 安全策略 | 安全策略 |