如何为 Weir 规则编写测试并用 harper-cli 运行？

如何为 Weir 规则编写测试并用 harper-cli 运行？

【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harper

Harper 的 Weir 语言允许你用自己的表达式定义语法检查规则，而规则文件内可以直接内嵌测试来声明"这段输入应被改成什么"。这篇文章的目标是：写一个带测试的.weir规则文件，然后用harper-cli test命令验证规则行为是否符合预期。前提是你能拿到harper-cli可执行文件；由于它未发布到包仓库（harper-cli/Cargo.toml中publish = false，但它属于根Cargo.toml声明的 workspace 成员），需要从 Harper 仓库源码构建。

规则文件的基本结构

一个 Weir 规则文件的核心是expr main声明的匹配表达式，加上若干let行描述规则行为。以 Weir 语言文档 中的示例为例，规则匹配文档中的拼写错误teh，并将其纠正为the：

expr main teh let message "Did you mean the definite article?" let description "Fixes especially common misspellings of the word `the`" let kind "Typo" let becomes "the"

四个let行分别声明：

• message：触发规则时展示给用户的提示；
• description：规则本身的说明；
• kind：规则类别，文档示例中出现的取值有Typo、Usage、Punctuation、Miscellaneous、Style、Redundancy等；
• becomes：建议的替换文本。

表达式支持多种写法，按需选用即可：

• 词与序列：gong to或(gong to)，顶层表达式默认就是序列；
• 多选一：[A, B]，如expr main [(G Suite), (G Suit), (Google Apps for Work)]；
• 过滤器<>：先选出较宽的片段再收窄，例如<([right, middle, left] $click), ( )>定位鼠标动词后的空格；
• UPOS 标签：在需要的位置直接写DET、NOUN等 Universal Part-Of-Speech 标签；
• 例外：在任意表达式前加!排除，如DET !NOUN；
• 通配符*：匹配任意完整 token；
• 注释：以#开头的行不生效。

如果需要跨逗号匹配，还要设置作用域：let scope "Sentence"（默认是Chunk，省略即等价于let scope "Chunk"）。替换大小写策略可用let strategy "Exact"或"MatchCase"指定。

在规则文件中内嵌测试

Weir 支持在规则文件里直接写测试，语法是两行字符串的断言（来自 Weir 语言文档 的 "Adding Tests" 一节）：

# 期望 A 被改成 B test "A" "B"

也可以断言规则不应修改某段文本：

# 期望规则不改动 A allows "A"

把测试加到前面的teh规则上，完整文件如下（此文件为文档示例）：

expr main teh let message "Did you mean the definite article?" let description "Fixes especially common misspellings of the word `the`" let kind "Typo" let becomes "the" test "I adore teh light of the moon." "I adore the light of the moon." test "I adore TEH LIGHT OF THE MOON." "I adore THE LIGHT OF THE MOON."

第二条测试覆盖了大写输入的场景——由于词的匹配不区分大小写，两条测试应同时通过。

仓库中已有数百个带测试的现成规则，可以作为写法参照，它们位于 weir_rules 目录。例如 ACoupleMore.weir：

expr main (a couple of more) let message "The correct wording is `a couple more`, without the `of`." let description "Corrects `a couple of more` to `a couple more`." let kind "Redundancy" let becomes "a couple more" test "There are a couple of more rules that could be added, how can I contribute?" "There are a couple more rules that could be added, how can I contribute?"

用 harper-cli 运行测试

拿到harper-cli后，运行指定 Weir 文件内的全部测试：

harper-cli test path/to/rule.weir

path/to/rule.weir是你要测试的 Weir 文件路径，需替换为你自己的文件位置。

如果你手边只有 Harper 仓库源码而没有已安装的二进制，可以直接从源码运行（harper-cli是根Cargo.tomlworkspace 的成员）：

cargo run -p harper-cli -- test path/to/rule.weir

判断测试结果

test子命令的输出与退出码由 harper-cli 源码 中的Args::Test分支定义：

• 全部测试通过：向标准错误输出All tests pass!，以状态码 0 结束；
• 存在失败测试：向标准错误打印失败测试的调试信息（{:?}格式），并以状态码 1 结束。

因此它可以直接放进脚本或 CI 中判断：退出码非 0 就说明规则行为与某条test期望不符，此时应检查是表达式匹配范围不对，还是let becomes给出的替换文本写错了。

可选：把规则用于实际检查

测试通过后，如果你想在一份文档上实际应用该规则，可以把规则打成一个.weirpack（内容为标准 ZIP，根目录包含.weir文件和必需字段author、version、description、license的manifest.json），然后在 lint 时加载：

harper-cli lint --weirpack path/to/rules.weirpack README.md

weirpack 的完整格式说明见 Weir 语言文档 的 "Weirpacks" 一节。此外，仓库文档还提到一个浏览器内的 Weir studio（站点路由/weir/studio）可用于在线实验规则与测试，但本地验证仍以上述harper-cli test为准。

【免费下载链接】harperOffline, privacy-first grammar checker. Fast, open-source, Rust-powered项目地址: https://gitcode.com/GitHub_Trending/har/harper