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

219 lines
8.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 方案评估:Markdown 链接式调用 `[函数名](参数…)`
| | |
|---|---|
| 状态 | **Proposed · 已被 [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) 取代** |
| 日期 | 2026-10-22 |
| 提出 | 用户:「markdown 的链接语义似乎很适合做这种操作」 |
| 相邻 | [spaced-function-names-d8.md](spaced-function-names-d8.md)(方括号调用 + 空格) |
| 影响面 | **核心解析**:`[key](coll)` 链接索引与调用语法冲突 |
> **后续更正**:本文的 L1–L4 方案列表把问题当成「表/语义」来讨论,偏离了用户原意。
> 用户问的是**调用写法**本身。最新评估(含原型实测 554/0 回归)见
> [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md):
> 方括号确实不可行(2 个真实冲突文件),但**去掉方括号的 `f(args)` 是空闲语法且可行**。
---
## 0. 一句话结论
**语法本身很优雅,但它与既有特性「链接索引 `[key](map)`」正面冲突。**
冲突不是「难实现」,而是「同一个写法要表示两种语义」。
建议**不要**把它做成调用的主形式;若要引入,只能作为**受限变体**(见 §4)。
---
## 1. 现状事实(实测)
### 1.1 `[…](…)` 目前是链接索引
```markdown
**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 提议的写法今天会怎样
```markdown
## greet
+ `who`
*"hi " + `who`*
# main
**r = [greet](alice)**
```
实测:
```
error: l2.mq.md:12:1: undefined variable `alice`
```
因为它被当作链接索引 `[greet](alice)`:拿 `alice` **当变量名**去查,
查不到就报错。也就是说**链接索引已经把这块语法占满了**。
### 1.3 歧义判定只有一行
```rust
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 — 独立标记前缀(可行,但失去「链接感」)
```markdown
> [call]greet(alice) # 或 @greet(alice)
```
- 优点:零歧义
- 缺点:前面多了标记,就不再是「Markdown 链接」了,失去了提议的全部吸引力
### 方案 L3 — 方括号调用 + 括号参数(**推荐**)
保留既有的方括号调用形式,但允许**参数写在括号里**:
```markdown
> [加一 号](n=1) # 具名参数
> [加一 号](1) # 位置参数
> [greet](alice bob) # 多参数
```
关键:**`]` 后面跟 `(` 时仍优先判为链接索引**——
除非方括号内是「已知的函数名形状」且**调用上下文**成立。
等等,这与 §3 的矛盾相同。**所以 L3 的真正形态是**:
```markdown
> [加一 号] (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 全角冒号问题一致考虑。