Files
marqdo/doc/design/spaced-function-names-d8.md
T
cflmy b6629e5450 fix(parse): D9 未闭合引号不再静默吞行(分类层 + 解析层双层修复)
缺陷:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0,
没有输出也没有报错,该行凭空消失。对「文档即程序」来说这是最危险的一类
错误——文档看起来完整、能跑、check 通过,实际少了一节。

根因在**分类层**而不是解析层:
parse_quoted_string 里 `unterminated " string` 的报错一直都在,
但 matching_bold_close 扫描时遇到未闭合的 '"' 后一直处于 in_str 状态,
再也找不到收尾 '**',于是 is_marqdo_star_line 返回 false,
该行被判为 LineKind::Comment 成为叙述,解析器根本看不到它。
解析层精心准备的报错不可达。

修复(两层,缺一不可):
1. src/lex/mod.rs
   - 新增 pub fn has_unterminated_string:统计未被 \ 转义的 '"',奇数即「开了没收」
   - is_marqdo_star_line:粗体起始且找不到收尾时,若引号未闭合则仍判 Code
     (判 Comment 会静默丢行;判 Code 才能让解析器说话)
2. src/parse/mod.rs
   - parse_simple_stmt 紧跟既有粗体分支之后,对「粗体起始 + 引号未闭合」
     给出精确报错,而不是笼统的 unrecognized statement

影响面(改前量化,避免凭直觉改核心解析):
- 全仓库 845 个 .mq.md、620 个含代码行文件
- 引号计数为奇数的代码行:**0**
- 结论:不改变任何现有文件的解析结果,只作用于畸形输入

测试(TDD,先写测试确认失败再修):
- 新增 4 个单测:未闭合→Code、闭合→Code、叙述含引号→Comment、
  叙述含孤立引号→Comment
- 修复前 unterminated_quote_inside_bold_is_code_not_comment 如期失败
- 修复后 lex 14/14;cargo test --lib 237 passed 0 failed(基线 233 + 新增 4)
- cargo test --test gold 276 passed 8 failed;git stash 验证基线同样 8 failed,
  失败全部是 ext_web_*(依赖 Go 插件 libweb,本机环境不具备),与本次无关

文档:
- doc/design/parser-diagnostics-d8-d9.md  设计依据、根因链路、候选方案评判、影响面
- doc/design/change-d9-unterminated-string.md  变更记录(现象/根因/改法/测试/边界)
- doc/design/spaced-function-names-d8.md  D8 方案评估(待审阅,未改代码)

已知边界:单引号 '...' 未闭合仍是旧行为,留作后续评估
(单引号兼作英文撇号,误判风险高于双引号)。
2026-10-22 11:52:27 +08:00

9.0 KiB
Raw Blame History

方案评估:函数名含空格的调用(D8)

状态 Proposed · 待审阅(未实施任何代码改动)
日期 2026-10-22
来源 qdagent-refactor-defects-2026-10.md D8
前置 parser-diagnostics-d8-d9.md(该文方案 A「禁止空格」已被否决,见 §0)
影响面 核心解析:src/parse/expr.rs 调用切词 / src/lex 行分类 / 名称解析

0. 为什么原方案被否决

原方案 A 主张「定义期拒绝含空格的函数名」。这是错的,理由是我此前忽略的一句话:

Marqdo 的立身之本就是完全兼容 Markdown。

## 用户 登录 是一个完全合法的 Markdown 二级标题。真实文档里这类标题极多:

## 用户 登录流程
## 第三阶段 数据校验
## Appendix A Results

如果禁止这些标题当函数名,等于强迫作者为了「能调用」而改写标题措辞—— 这恰恰把「代码即文档」降级成「代码迁就文档」。作者写的标题首先应当是他自己想写的标题。

结论:空格必须被支持,问题只在于「怎么把带空格的名字准确传给调用」。


1. 事实基础(全部实测,1.5.2)

先固定真实行为,避免方案讨论建立在猜测上。

1.1 定义侧

输入 结果
## 加一 号 ✅ 定义成功,函数名原样为 加一 号(parse_object_decl 走 Ok((raw.to_string(), None)))
## 用户 登录流程 ✅ 同上

定义侧完全支持空格,不需要任何改动。

1.2 调用侧

输入 结果 原因
> 加一 号 n=1 ❌ undefined variable 号 parse_call_tail 用 split_whitespace().next() 只取首词
> [加一_号] n=1 ✅ 正常(返回 2) 方括号标记调用已存在且工作
> [加一 号] n=1 ❌ unknown function [加一 is_bracket_callee_inner 第 1248 行显式拒绝含空白
`加一 号` 作为表达式 ❌ undefined variable 加一 号 反引号名走变量解析,找不到函数

1.3 关键发现

方括号标记调用([callee])已经存在且实现完整, 挡住带空格名字的是 is_bracket_callee_inner 里的两处校验, 而不是一处(首轮评估低估了)。

这是本次评估最重要的发现:不需要发明新语法,只需要让既有机制接受空格。

1.4 可行性实测(已做,未保留改动)

为回答「放开后运行时到底能不能查到含空格的函数名」,做了受控实验: 临时放开两处校验 → 编译 → 跑用例 → 立即回退(src/parse/expr.rs 已恢复原样)。

关卡 位置 原逻辑 放开后
1 is_bracket_callee_inner t.chars().any(is_whitespace) → 拒绝 删除该检查
2 同函数末尾 bare-name 白名单 is_alphanumeric() | '_' | '.' | !is_ascii() 追加 | c == ' '

实验结果

用例 结果
## 加一 号 + > [加一 号] n=1 ✅ 返回 2(运行时函数表正确命中含空格名)
## 加一_号 + > [加一_号] n=1(对照) ✅ 仍返回 2,既有行为不变
全量 cargo test --lib ✅ 237 passed, 0 failed

结论:方案 1 技术上完全成立,且不破坏既有测试。 (237 = 基线 233 + 本轮 D9 新增的 4 个分类测试。)

注意:实验只证明「可行」,未固化。正式实施需要补 §4 的全部 V1–V9 用例, 特别是 V3–V7 的歧义排除,再决定是否合入。


2. 候选方案

方案 1 — 放开方括号内的空格(推荐)

做法:把 is_bracket_callee_inner 的「含空白即拒绝」改为「允许空白, 但需与既有歧义守卫共存」;并确认调用链后续不再按空格切词。

用法:

## 用户 登录流程
    + `账号`

*"已登录 " + `账号`*

# main

> [用户 登录流程] 账号=alice
*""

优点

  • 不新增语法:[…] 标记调用是既有的正式特性,只是被一行校验挡住
  • 向后兼容:所有现有调用(含 [加一_号])行为不变
  • 与 Markdown 完全兼容:标题怎么写都行,调用时用方括号「引用这个名字」
  • 语义清晰:方括号本身就是「这里是一个整体名字」的视觉标记
  • 可推广:方法调用 [obj.方法 名]、库函数 [lib.函数 名] 一并受益

风险与缓解

风险 缓解
[…] 也被用于链接索引 [key](map) 已有守卫:] 后紧跟 ( 则不是 callee(第 981 行),保持
JSON 数组 [1, 2] 被误认为 callee 既有守卫:含 , : { } [ ] 一律拒绝,保持
print text=(礼貌 [问候] x) 类内嵌方括号 既有守卫:前缀含 = ( " ' : 则不当 callee,保持
运行时按下标查函数表,加一 号 能否命中 需实测验证(见 §4 验证计划 V1)

工作量:改 2 处校验 + 补 6–9 个测试 + 更新教程与陷阱手册。最小可验证改动。


方案 2 — 调用侧最长前缀匹配(否决)

做法:拿到 加一 号 n=1 后,尝试用「已知函数名」做最长前缀匹配。

否决理由

  1. 上下文不可达:调用发生在表达式解析阶段,此时只有本模块符号表; 跨模块 lib.函数 名 需要 import 解析结果,不可在词法期判定。
  2. 歧义爆炸:> print text=hello world 中,若存在名为 print text 的函数, 本来正确的调用会突然变成别的函数。所有多词行语义都可能改变。
  3. 属于核心语义变更,收益(省掉方括号)远小于风险。

方案 3 — 主张「标题即函数名,调用用完整标题」(不改代码,只改文档)

做法:明确官方立场——带空格的名字不自称可调用,需要调用就请写 一个无空格的 ## 别名 转发,或直接把标题写成无空格形式。

## 用户 登录流程          ← 给人读的标题,不被调用

## 用户登录流程           ← 真正被调用的函数
    + `账号`
...

优点:零代码改动;鼓励「标题给人、标识符给机器」的清晰分层。

缺点:与「完全兼容 Markdown」仍有张力——作者得写两遍。

适用:如果审计认为方括号放开会牵连过多,可作为保守退路。


方案 4 — 反引号名解析到函数(否决)

允许 `加一 号` 在调用位解析成函数引用(> 加一 号 n=1)。

否决理由:反引号在 Marqdo 中统一表示变量引用。让它有时指变量、有时指函数, 会让「反引号=变量」这条最基础的约定失效,错误更难排查。


3. 方案对比

维度 方案 1 放开方括号 方案 2 前缀匹配 方案 3 文档立场 方案 4 反引号
兼容 Markdown ✅ 完全 ✅ ⚠️ 需写两遍 ✅
新增语法 无(复用既有) 无 无 有歧义
改动范围 1 处校验 + 测试 核心语义 0 代码 核心语义
回归风险 低 高 无 高
可验证性 高(可枚举用例) 低 — 低
推荐 首选 否决 备选 否决

4. 若采纳方案 1:验证计划

必须全部通过才可合入。

编号 用例 期望
V1 ✅ ## 加一 号 + > [加一 号] n=1 返回 2(已实测通过,见 §1.4)
V2 ## 加一_号 + > [加一_号] n=1 返回 2(既有行为不变)
V3 链接索引 [k](m) 仍解析为索引,不被当 callee
V4 > print text=(礼貌 [问候] x) 内嵌方括号不被当 callee
V5 方括号内 JSON [1, 2] / ["a"] 仍被拒绝为 callee
V6 跨模块 [lib.函数 名] 正确解析到库函数
V7 方法 [obj.方法 名] 正确解析 receiver
V8 全量 cargo test 233 全绿(+ 新增用例)
V9 全仓库 .mq.md 回归 无新增解析错误

V1 是决定性的:如果运行时函数表以 加一 号 为键能正常查到, 方案 1 就成立;如果查不到(比如符号表内部也做了归一化),需要再评估。


5. 待你决策的问题

  1. 选哪个方案? 我倾向 方案 1(放开方括号空格):不新增语法、 完全兼容 Markdown、改动可控、可验证性强。
  2. 若选方案 1,调用书写是否需要中文别名? 例如同时接受 【加一 号】(全角方括号), 与全角冒号问题(D2)一致。
  3. 是否要保留方案 3 的文档立场作为补充说明? 即「标题可自由书写; 需要调用时用 [完整名] 引用」——这句话本身就很适合写进教程。

在你确认前,我不会改动 D8 相关代码。