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 语句体也会保留原位。

  • 空行。
    完全保留原有空行,包括连续多个空行。

  • 注释。
    不移动到其他行,不重新折行,也不会迫使前面的代码换行。注释内容保持不变。

  • 字面量内容,逐字节保留。
    字符串、使用反引号 ` 的模板字面量、@TEXT heredoc 文本块和字符字面量,其内部都不会被拆分、重新缩进或调整空格。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 写入文件之前,必须通过以下检查。只要违反其中任意一项,工具就会报告问题、保留原文件,并以非零退出码结束运行。

  1. 词法分析必须完整有效。
    输入不能在字符串、字符字面量、模板字面量、块注释或文本块尚未结束时就到达文件末尾。驱动会将这些情况视为严重的词法错误,相关实现位于 src/compiler/internal/lexer.l,错误信息包括 "End of file in string" 等。

    这类文件没有明确有效的词法单元流。例如,一个意外出现且未配对的 ",就可能颠倒后续整段文件中字符串与代码的识别结果;如果继续对这些被错误识别的区域进行“格式化”,就会破坏真正的字符串内容。因此,formatLPC 会抛出异常,而不会生成输出。

    这项检查不可省略,因为下面的词法单元等价检查无法发现此类问题:输入和输出可能以相同方式被错误解析,导致比较仍然通过。

  2. 词法单元序列等价。
    对输出重新进行词法分析后,词法单元的类型和原始文本必须与输入完全一致。格式化工具不能改变编译器看到的内容。

  3. 字面量等内容的字节完全一致。
    每个字符串、模板、heredoc、字符、注释和预处理指令词法单元的内容,都必须逐字节保持一致。

  4. 幂等性。
    再次格式化输出,必须得到完全相同的结果。

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。