FluffOS 在 tools/lpc-syntax/ 中提供了一个无需额外依赖的 LPC 代码格式化工具。它采用语法驱动的格式化引擎,与 VS Code 扩展的“格式化文档”功能及测试库 CI 中的格式检查使用同一套实现。
运行时只需要 Node.js 18 或更高版本,无需执行 npm install。
该工具负责执行 LPC 代码风格指南 中的排版规则,包括空格、缩进、花括号位置和长行换行。同时,它将手动安排的换行、空行和注释视为有意义的布局,并保留这些安排。
使用方法
在仓库根目录中,对整个测试库进行格式化:
testsuite/format.sh # 直接格式化 testsuite/ 下的 .lpc 和 .c 文件
testsuite/format.sh --check # 仅检查;存在未格式化文件时退出码为 1,供 CI 使用
在自己的脚本中,对指定文件集合进行处理:
find lib -name '*.lpc' | node tools/lpc-syntax/bin/format-corpus.mjs # 直接修改文件
find lib -name '*.lpc' | node tools/lpc-syntax/bin/format-corpus.mjs --check # 仅检查
作为库调用:
import { formatLPC } from './tools/lpc-syntax/format.mjs';
const pretty = formatLPC(source); // 使用默认配置
const wide = formatLPC(source, { printWidth: 120 }); // 默认值为 100
const four = formatLPC(source, { indentSize: 4 }); // 默认值为 2
在 VS Code 或 Cursor 中,扩展提供基于同一引擎的“格式化文档”和“保存时格式化”功能。扩展在 fluffos/fluffos-vscode 仓库中开发,通过固定版本的 fluffos 子模块获取并构建该引擎。
可以使用以下设置调整格式:
lpc.format.printWidth:默认100。lpc.format.indentSize:默认2。
配置选项
| 选项 | 默认值 | 含义 |
|---|---|---|
printWidth |
100 |
建议的最大行长度。与 src/.clang-format 中的 ColumnLimit 一致,使 LPC 和驱动的 C++ 代码采用相同的换行列数。 |
indentSize |
2 |
每级缩进使用的空格数,与 C++ 的 IndentWidth 一致。 |
会规范化的内容
- 缩进,包括花括号嵌套、
case标签和换行后的续行缩进,以及行尾空白。 - 按照风格指南的空格规则表 调整词法单元之间的空格,包括控制流与函数调用的圆括号、运算符、类型转换、一元运算符的紧贴规则、字面量内侧空格、下标、映射与标签中的冒号等。例如:
({ 1, 2 })、([ "a": 1 ])、(: f :)。 - 将空代码块合并为
{}。 - 在行尾
//注释前保留至少两个空格;如果手动对齐时使用了更宽的间隔,则原样保留。 - 将预处理指令移到第 0 列。
#include和inherit保持原有顺序,包含指令可以位于继承语句之前或之后,不会被提前、排序或重新分组。 - 格式化后的行如果超过
printWidth,会在最外层括号组内拆分,例如函数实参、数组或映射元素,每个元素单独一行;必要时继续递归拆分。
会保留的内容
格式化工具遵循源码已有的布局,不会将不同写法全部重排为同一种形式。这与 clang-format 的完整重排方式不同。
-
语句顺序。
非空白词法单元的序列始终不变。#include、inherit、声明及其他内容都保持源码顺序。后面的包含指令不会被移动到继承语句前面,例如以下顺序会被保留:#include <ansi.h> inherit NPC; #include "fight.h"如果某次格式化处理会改变词法单元的顺序,
formatLPC会抛出异常。 -
手动安排的换行。
单行代码块只要没有超长,就保持单行;多行调用或声明保留原有布局,包括结束符)、");、});是紧贴最后一个元素,还是单独占一行。不带花括号且单独换行的if语句体也会保留原位。 -
空行。
完全保留原有空行,包括连续多个空行。 -
注释。
不移动到其他行,不重新折行,也不会迫使前面的代码换行。注释内容保持不变。 -
字面量内容,逐字节保留。
字符串、使用反引号`的模板字面量、@TEXTheredoc 文本块和字符字面量,其内部都不会被拆分、重新缩进或调整空格。heredoc 的正文和结束标记行原样保留;结束标记行中;的位置遵循原始源码布局。 -
被字符串化的宏实参。
#define STR(x) #x会在编译时将实参的源码写法转换为字符串。因此,格式化工具会识别执行字符串化的宏,并原样保留对应调用位置的实参。识别过程遵循驱动自身的预处理规则,包括连续#数量的奇偶规则和\续行规则。例如,
STR(1+2)仍然生成"1+2",不会变成"1 + 2"。 -
CRLF 换行符。
使用 CRLF 的源文件在格式化后仍使用 CRLF。
目前有一项已知限制:没有括号包裹、且不是字符串的表达式续行,会被合并为一行。例如:
return a +
b;
会合并为:
return a + b;
要跟踪任意表达式中的这类换行,需要完整的表达式解析器,而基于词法单元的设计刻意避免引入这种复杂度。如果该换行对表达布局很重要,请使用括号包裹续行表达式。
安全保证
通过 format.sh 或 format-corpus.mjs 写入文件之前,必须通过以下检查。只要违反其中任意一项,工具就会报告问题、保留原文件,并以非零退出码结束运行。
-
词法分析必须完整有效。
输入不能在字符串、字符字面量、模板字面量、块注释或文本块尚未结束时就到达文件末尾。驱动会将这些情况视为严重的词法错误,相关实现位于src/compiler/internal/lexer.l,错误信息包括"End of file in string"等。这类文件没有明确有效的词法单元流。例如,一个意外出现且未配对的
",就可能颠倒后续整段文件中字符串与代码的识别结果;如果继续对这些被错误识别的区域进行“格式化”,就会破坏真正的字符串内容。因此,formatLPC会抛出异常,而不会生成输出。这项检查不可省略,因为下面的词法单元等价检查无法发现此类问题:输入和输出可能以相同方式被错误解析,导致比较仍然通过。
-
词法单元序列等价。
对输出重新进行词法分析后,词法单元的类型和原始文本必须与输入完全一致。格式化工具不能改变编译器看到的内容。 -
字面量等内容的字节完全一致。
每个字符串、模板、heredoc、字符、注释和预处理指令词法单元的内容,都必须逐字节保持一致。 -
幂等性。
再次格式化输出,必须得到完全相同的结果。
testsuite/format.sh 会排除 testsuite/single/tests/compiler/fail/ 中特意构造的部分错误测试文件:
- 两个包含无效 UTF-8 原始字节的测试文件,它们本身不是有效文本。
- 三个用于触发文件末尾词法错误、故意不写结束标记的测试文件:
eof_in_string.lpc、eof_in_comment.lpc和bad_at_block.lpc。按照设计,它们会被第一项安全检查拒绝。
对于词法分析器无法完整理解的内容,工具会拒绝处理,而不会猜测其含义。
除了这些内置检查,对格式化工具本身的修改还必须通过真实驱动验证:整个测试库经过重新格式化后,仍须通过以下测试:
driver etc/config.test -ftest
这项端到端检查用于发现词法单元自检无法覆盖的问题,因为错误也可能存在于词法分析器本身。完整验证方法见 tools/lpc-syntax/README.md。
与 C++ 风格的关系
驱动的 C++ 代码由 clang-format 格式化,其 src/.clang-format 配置以 Google 风格为基础,采用 2 个空格缩进,单行上限为 100 列。
对于两种语言共有的规则,LPC 格式化工具与其保持一致,包括:
- 缩进和行长度上限。
- 花括号与声明、关键字位于同一行。
- 关键字和函数调用前的圆括号空格规则。
- 运算符两侧的空格。
- 类型转换紧贴操作数。
case标签缩进。- 行尾注释前至少保留两个空格。
只有 LPC 特有语法,或手工布局本身承载意图时,才采用不同规则:
- 数组标记紧贴名称,例如
string *arr。 - 数组和映射字面量的分隔符内侧留空格,例如
({ ... })、([ ... ])。 catch(和new(按函数调用方式紧贴圆括号。- 函数字面量
(: ... :)的分隔符内侧留空格。 - 保留手工安排的换行布局,不进行完整重排。
完整对照说明见 tools/lpc-syntax/README.md。