Files
marqdo/doc/design/link-style-call-evaluation.md
cflmy 9cda80ee7d docs(design): [函数名](参数) 与 f(参数) 调用写法评估 — 原型实测 554/0(已回退)
更正前两轮对用户意图的误读:用户问的是**调用写法**,不是表/函数即值。

核心结论:
- [函数名](参数) 技术上能做,但撞的是已定的取元语义
  「方括号=取出的名字,圆括号=从哪取」(collection-access-link.md §1;
  call-arguments.md §2 锁定 `]` 紧邻 `(` = 取元)
- 按名字消歧不可行(**实测证据**):全仓库 851 文件 / 2367 个 ## 名 /
  983 次 [k](c),键名与同文件函数名冲突 5 处、去重后 2 个真实文件:
    ext/data/db.mq.md:122        *[count](r)*        (## count + r 里的 count 列)
    examples/code-as-docs/index.mq.md:79  价=[单价](行)  (## 单价 + 行里的单价字段)
  函数名优先 → 打断这两处取元;数据优先 → 永远无法 [f](1) 调用。两条都走不通。
- 且存在不可消除的歧义子集:[f](1) 与 [1](篮子) 同形,单参调用永远无法表达;
  「多参能用、单参不能用」的语法不可教。

但去掉方括号的 函数名(参数) 是**完全空闲的语法**(实测原型前 加(1) 报
trailing input in expression),且原型验证可行:

原型(已回退,仅验证):
1. src/parse/expr.rs 新增 try_paren_call,紧随其后的 ( 视为参数列表
2. src/parse/mod.rs 两处「像调用」判定加 looks_like_paren_call,让单 token 也能进调用分支

原型实测:
- 加(1) / 加(1 2 ) / 加("1" "2") / txt.str_trim("  x  ") 均通过
- 加(1 2)、加(a=1 b=2)、加(1, 2)、嵌套 加(加(1 2) 3) 失败
- **全量 cargo test --release: 554 passed / 0 failed(零回归)**

关键判断:失败点不在语法而在**参数分词器**——加(1 2) 失败、加(1 2 ) 成功,
差别只是 ) 前多一个空格,说明 parse_call_args/split_first_token 把 ) 当成了
token 的一部分;修它要动所有调用共享的分词器。这解释了「看着 10 行、实为一次核心改动」。

另一个重要性质:f(args) 最终仍产出 CallExpr{callee,args},
EKC 指纹 collect_calls、契约校验、字节码 Op::Call(fid,argc) **全部自动兼容**——
它只换写法,不改调用模型(与一等函数方案本质不同)。

人读性:f(1 2) / f(a=1 b=2) 与数学记号同构、参数边界显式、渲染不成超链接,
优于 [f](1 2)(预览里会变成链接)。

建议:不做 [f](args);做 f(args),先具名后位置。
附工作量清单 9 项与三档实施选择(A 仅具名 / B 具名+位置 / C 全量)。未改代码。
2026-10-22 12:53:03 +08:00

8.3 KiB
Raw Permalink 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 全角冒号问题一致考虑。