# gf-highlight **Repository Path**: MoganLab/gf-highlight ## Basic Information - **Project Name**: gf-highlight - **Description**: Goldfish Scheme 实现的代码高亮 - **Primary Language**: Scheme - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-19 - **Last Updated**: 2026-11-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # gf-highlight gf-highlight 是 [Goldfish Scheme](https://gitee.com/LiiiLabs/goldfish) 的语法高亮引擎,为终端工具(如 `gf cat`)提供结构化文本与代码的着色能力。 引擎的架构与概念借鉴自 KDE 的 [syntax-highlighting](https://github.com/KDE/syntax-highlighting)(Kate 编辑器的高亮引擎):以"上下文栈 + 规则匹配"为核心的状态机模型,将语法分析与颜色主题完全解耦。本仓库将其核心思想用纯 Scheme(R7RS,无正则依赖)重新实现。 ## 目录 1. [特性](#特性) 2. [架构](#架构) 3. [核心概念](#核心概念) 4. [仓库布局](#仓库布局) 5. [使用](#使用) 6. [开发](#开发) 7. [许可](#许可) ## 特性 - **逐行状态机高亮**:与 Kate 引擎一致,只保存每行末尾的上下文栈状态,天然支持跨行结构(多行注释、未闭合字符串),并为增量高亮留出空间。 - **无正则的规则引擎**:实现了 DetectChar、Detect2Chars、AnyChar、StringDetect、WordDetect、keyword、Int、Float、Decimal、Hex、DetectSpaces、DetectIdentifier 等规则类型的纯 Scheme 匹配,语义对齐 Kate 的 Highlight Definition XML 格式。 - **语法与颜色解耦**:解析结果只携带抽象样式名(Keyword、String、Comment……),由主题(theme)在渲染时映射为具体颜色。 - **多语言语法定义**:语法定义采用 JSON 格式(见 `highlight/resources/syntax/` 下各文件),运行时解析加载,内置开箱即用的 Scheme、JSON、C++、C、Lua 与 Markdown 语法,并支持 Markdown 代码块按子语言规则嵌套高亮。 - **24 位真彩色 ANSI 渲染**:`tui-render` 模块将高亮结果渲染为真彩色 ANSI 转义序列,并保证 UTF-8 多字节字符不被转义码打断。 ## 架构 ``` ┌─────────────────────── highlight(域) ─────────────────┐ │ resources/ 数据文件(语法定义 JSON、主题) │ │ definition 语法定义模型 + JSON 解析 + 内置 Scheme 定义 │ │ rule 规则类型与匹配器(无正则) │ │ highlighter 逐行状态机引擎(上下文栈) │ │ theme 主题模型 + Breeze Dark 内置配色 │ │ tui-render spans → ANSI 24 位真彩色字符串 │ │ (渲染前合并相邻同样式 span,保护多字节字符) │ └──────────────────────────┬────────────────────────────────┘ │ depends-on ▼ ┌────────────────────── cat(域,工具) ────────────────────┐ │ goldcat gf cat 子命令:读文件 → 高亮 → 输出 │ └───────────────────────────────────────────────────────────┘ ``` 两个域通过 `gfproject.json` 声明依赖关系:`highlight` ← `cat`。 ## 核心概念 引擎模型是一个下推自动机(栈式状态机),与 Kate 一致: - **context(上下文)**:解析器的一个状态。栈顶上下文的规则按声明顺序逐条尝试,首条命中者生效。 - **context 切换**:规则命中后可 `#stay`(停留)、push 新上下文、或 `#pop`(支持 `#pop!Target` 形式)。 - **lineEndContext**:行尾触发的切换。单行注释上下文在行尾 `#pop`,多行注释 `#stay` 跨行。 - **fallthroughContext**:上下文内所有规则都不匹配首字符时的跳转目标。 - **rule(规则)**:匹配器 + 命中后的样式(attribute)与上下文切换;支持 lookAhead(不消耗字符)、firstNonSpace、column 约束。 - **itemData(样式名)**:规则与上下文引用的抽象样式(Keyword、String、Comment 等),是语法与主题之间的桥梁。 - **theme(主题)**:将样式名映射为颜色与字形(bold/italic/underline),默认内置 Breeze Dark。 以 Scheme 单行注释为例: ``` (define x 1) ; 注释 └─ ';' 命中 DetectChar → push "comment" 上下文(标 Comment) comment 上下文无规则命中时逐字符消耗,标 Comment 行尾触发 lineEndContext #pop,回到 Level0 ``` ## 仓库布局 ``` highlight/resources/syntax/scheme.json Scheme 语法定义(JSON,派生自 KDE scheme.xml) highlight/resources/syntax/json.json JSON 语法定义(JSON,派生自 KDE json.xml) highlight/resources/syntax/cpp.json C++ 语法定义(JSON,派生自 KDE isocpp.xml) highlight/resources/syntax/c.json C 语法定义(JSON,派生自 KDE c.xml) highlight/resources/syntax/lua.json Lua 语法定义(JSON,派生自 KDE lua.xml) highlight/resources/syntax/markdown.json Markdown 语法定义(JSON,派生自 KDE markdown.xml) highlight/resources/themes/breeze-dark.theme Breeze Dark 主题(KDE 原文件) highlight/liii/highlight/ 引擎实现(definition/rule/highlighter/theme/tui-render) highlight/tests/ 引擎单元测试(每函数一个测试文件) tools/cat/ gf cat 工具 gfproject.json 域依赖声明 gf_check.json 静态检查规则配置 ``` ## 使用 `gf cat` 已随工具链提供: ```bash gf cat foo.scm # 语法高亮输出 Scheme gf cat package.json # 语法高亮输出 JSON gf cat main.cpp # 语法高亮输出 C++ gf cat --plain foo.scm # 朴素输出 gf cat -h # 帮助 ``` 在 Scheme 代码中使用引擎: ```scheme (import (liii highlight definition) (liii highlight highlighter) (liii highlight theme) (liii highlight tui-render)) (let* ((def (load-scheme-definition)) (th (default-breeze-dark-theme)) (state (initial-highlight-state def))) (let-values (((spans next-state) (highlight-line "(define x 42)" state def))) (display (render-spans-to-ansi "(define x 42)" spans th def)) ;; next-state 可传给下一行,实现跨行高亮 )) ``` ## 开发 ```bash gf test --all # 运行全部单元测试 gf check # 静态检查(no-crlf、行数、树深等) gf fix # 格式化 ``` 测试采用"每函数一个测试文件"的组织方式,函数文档与用例见各 `tests/**/README.md`,或用 `gf doc liii/highlight <函数名>` 查看。 ## 许可 - 实现源码:[Apache-2.0](LICENSE),Copyright (C) The Goldfish Scheme Authors - `highlight/resources/themes/breeze-dark.theme` 与 `highlight/resources/syntax/`(派生自 [KDE syntax-highlighting](https://github.com/KDE/syntax-highlighting) 的 scheme.xml、json.xml 与 isocpp.xml):MIT,Copyright KDE 作者,见各文件内声明 引擎架构参考了 KDE syntax-highlighting 的设计(上下文栈状态机、规则类型、样式/主题分离),特此致谢。