Files
marqdo/doc/design/link-style-call-evaluation.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

8.3 KiB
Executable File
Raw Blame History

方案评估:Markdown 链接式调用 [函数名](参数…)

状态 Proposed · 已被 paren-call-and-readable-invocation.md 取代
日期 2026-10-22
提出 用户:「markdown 的链接语义似乎很适合做这种操作」
相邻 spaced-function-names-d8.md(方括号调用 + 空格)
影响面 核心解析:[key](coll) 链接索引与调用语法冲突

后续更正:本文的 L1–L4 方案列表把问题当成「表/语义」来讨论,偏离了用户原意。 用户问的是调用写法本身。最新评估(含原型实测 554/0 回归)见 paren-call-and-readable-invocation.md: 方括号确实不可行(2 个真实冲突文件),但去掉方括号的 f(args) 是空闲语法且可行。


0. 一句话结论

语法本身很优雅,但它与既有特性「链接索引 [key](map)」正面冲突。 冲突不是「难实现」,而是「同一个写法要表示两种语义」。 建议不要把它做成调用的主形式;若要引入,只能作为受限变体(见 §4)。


1. 现状事实(实测)

1.1 […](…) 目前是链接索引

**m = > json.parse text={"a":1}**
**v = [a](m)**          # 取 map 的 a 成员
> print text=`v`         # → 1

这是 v0.3 的正式特性,文档里写作「集合取元优先 [键](集合)」。 实现有专门入口 parse_link_index,并由 link_index_shape_ahead 判定:

[ … ] 后面紧跟 ( → 链接索引

1.2 提议的写法今天会怎样

## greet
    + `who`

*"hi " + `who`*

# main

**r = [greet](alice)**

实测:

error: l2.mq.md:12:1: undefined variable `alice`

因为它被当作链接索引 [greet](alice):拿 alice 当变量名去查, 查不到就报错。也就是说链接索引已经把这块语法占满了。

1.3 歧义判定只有一行

fn link_index_shape_ahead(s: &str) -> bool {
    // '[' … ']' 后紧跟 '('  → 链接索引
}

任何 [X](Y) 都会走链接索引,没有例外。


2. 为什么这个提议有吸引力

先说我认可的部分,避免低估它:

  1. 视觉语义准确。Markdown 里 [文本](目标) 的直觉是「链接一个东西到另一个」。 调用 [greet](alice) 读作「调用 greet,指向 alice」,对非程序员也直观。
  2. 参数在括号里,边界清晰。相比 > greet alice(空格切词), (alice bob) 的边界是显式的 —— 这恰好是 D8「带空格函数名」痛点的天然解药。
  3. 与 Markdown 完全兼容。[a](b) 是合法链接写法,编辑器不会标红。

但:这些优点必须在「不破坏链接索引」的前提下才能兑现。


3. 冲突分析

3.1 根本矛盾

写法 链接索引语义 调用语义 能否并存
[a](m) 取 m 的成员 a 用参数 m 调用 a 看内容才知道
[greet](alice) 取 alice 的成员 greet 用 alice 调用 greet 同上

两者形状完全一致,区别只在「greet 是函数还是键名」「alice 是集合还是实参」—— 这需要符号表信息,而语法判定发生在解析期(此时未必知道有哪些函数)。

3.2 用「函数表已知」来消歧能行吗

理论上:若 greet 是已定义函数 → 调用;否则 → 链接索引。

问题:

  1. 跨模块不可知:[lib.greet](x) 需要 import 结果,词法/语法期拿不到。
  2. 名字冲突:如果既有 greet 函数,又有 map 里叫 greet 的键,语义就靠猜。
  3. 错误信息会变差:本意是链接索引但键不存在时,会被误判成调用, 报 unknown function 而不是 missing map key —— 把清晰错误变成误导错误。
  4. 修改即破坏:今天所有 [键](集合) 写法都要进符号表做一次判定, 这是全量语义变更,不是增量特性。

3.3 冲突的严重度

链接索引是 v0.3 明确推广的写法(「集合取元优先 [键](集合)」), 仓库里大量使用。让调用去抢这块语法,等于用新特性侵蚀既有特性。


4. 可选的受限方案

方案 L1 — 参数列表必须「非单个标识符」(不可靠,不推荐)

仅在 (…) 内含分隔符时判为调用,如 [greet](alice, bob)。

  • 优点:[a](m) 单参数时保留链接索引语义
  • 致命缺陷:[greet](alice) 这种最常见的单参数调用无法表达; 而 [greet](a, b) 又和「链接索引 + 逗号」冲突。语义随参数个数漂移,最坏的一类设计。

方案 L2 — 独立标记前缀(可行,但失去「链接感」)

> [call]greet(alice)        # 或 @greet(alice)
  • 优点:零歧义
  • 缺点:前面多了标记,就不再是「Markdown 链接」了,失去了提议的全部吸引力

方案 L3 — 方括号调用 + 括号参数(推荐)

保留既有的方括号调用形式,但允许参数写在括号里:

> [加一 号](n=1)            # 具名参数
> [加一 号](1)              # 位置参数
> [greet](alice bob)        # 多参数

关键:] 后面跟 ( 时仍优先判为链接索引—— 除非方括号内是「已知的函数名形状」且调用上下文成立。

等等,这与 §3 的矛盾相同。所以 L3 的真正形态是:

> [加一 号] (n=1)           # 方括号与括号之间有空格 → 调用+参数组,不是链接

用「] 与 ( 之间是否有空格」消歧:

  • [key](coll)(紧贴)→ 链接索引(既有语义完全不变)

  • [callee] (args)(有空格)→ 调用,参数为一组

  • 优点:零歧义、零回归(紧贴形式完全不动)、保留了「括号包参数」的可读性、 顺带解决 D8 的空格函数名

  • 缺点:视觉上 ] ( 有个空格,略不自然;但 Markdown 渲染不受影响

方案 L4 — 不在语法层做,在文档层说明(保守)

明确「链接索引是取元,不是调用」,调用一律用 > callee args 或 > [callee] args。 [函数名](参数) 留作不做。


5. 方案对比

方案 歧义 回归风险 保留「链接感」 解决 D8 推荐
L1 参数需含分隔符 高(随参数个数漂移) 中 部分 否 ❌
L2 独立前缀 无 无 否 是 备选
L3 空格消歧 无 无 大部分 是 ✅
L4 不做 无 无 否 否 退路
直接抢 [x](y) 不可解 高 是 是 ❌

6. 我的建议

  1. 不要把 [函数名](参数) 直接定为调用——它和链接索引形状相同,无法可靠消歧。
  2. 采纳 L3:[callee] (args)(中间有空格)作为「带括号参数组的调用」, 紧贴的 [key](coll) 语义一字不动。
  3. 这样同时满足:
    • 「完全兼容 Markdown」([x](y) 仍是链接语义)
    • 参数边界显式(括号括起来)
    • D8 的空格函数名(方括号内允许空格)
  4. 若你觉得 ] ( 的空格不好看,退一步选 L2(> callee(args) 这种函数式写法), 牺牲链接感换取零歧义。

7. 若采纳 L3 的验证计划

编号 用例 期望
L3-1 [a](m) 紧贴 链接索引,取成员(不变)
L3-2 [greet] (alice) 有空格 调用,alice 作为位置参数
L3-3 [加一 号] (n=1) 调用带空格名函数,返回 2
L3-4 [greet] (a b) 两个位置参数
L3-5 [a](m) 中 a 恰好也是函数名 仍走链接索引(紧贴优先)
L3-6 > print text=(礼貌 [问候] x) 内嵌方括号不受影响
L3-7 全量 cargo test 554 全绿
L3-8 全仓库 .mq.md 回归 无变化(紧贴形式未动)

8. 待你决策

  1. 选 L3、L2、还是 L4?
  2. 若选 L3:] ( 的空格你能接受吗?(渲染上无差别,源码里能看见)
  3. 是否同时支持全角 【函数名】(参数)?与 D2 全角冒号问题一致考虑。