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 全量)。未改代码。
This commit is contained in:
cflmy committed 2026-10-22 12:53:03 +08:00
1 parent eae4815fc7
commit 9cda80ee7d
2 files changed
+235 -1

No files matched your search

+6 -1
View File
@@ -2,12 +2,17 @@
| | |
|---|---|
| 状态 | **Proposed · 待决策**(未实施任何代码改动) |
| 状态 | **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. 一句话结论
@@ -0,0 +1,229 @@
# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式
| | |
|---|---|
| 状态 | **Proposed · 待决策**(原型已验证并已回退,未合入代码) |
| 日期 | 2026-10-22 |
| 提出 | 「`[函数名](参数1 参数2)` 这种写法有没有可能成立;调用能否更符合人读习惯」 |
| 更正 | 本文替代前两轮对用户意图的误读(前两轮在讨论「表 / 函数即值」,不是调用语法) |
| 相邻 | [link-style-call-evaluation.md](link-style-call-evaluation.md) · [function-as-table-semantics.md](function-as-table-semantics.md) · [collection-access-link.md](collection-access-link.md) · [call-arguments.md](call-arguments.md) |
---
## 0. 结论
| 问题 | 答案 |
|------|------|
| `[函数名](参数1 参数2)` 能否成立 | **技术上能,但代价在方括号**:它撞的是取元 `[键](集合)`,而命名空间里确有 2 个真实文件以函数名作键,任何「按名字消歧」都会静默改语义 |
| 更人读的调用能否成立 | **能,而且更干净**:`函数名(参数1 参数2)`(**不带方括号**)目前是**完全空闲的语法**,原型实测全量 **554 passed / 0 failed**,零回归 |
一句话:**想要「参数进括号」这个美感,不需要方括号——去掉方括号反而没有任何冲突。**
```markdown
**税率 = 查询税率(档位=2)** # 具名,读起来像函数调用
**合计 = 加(1 2)** # 位置,读起来像数学
**名 = txt.str_trim(" x ")** # 库函数同样适用(原型已验证)
```
---
## 1. 现状:今天的调用写法盘点(全部实测)
| 写法 | 位置 | 实测 |
|------|------|------|
| `> 加 1 2` | 语句 | ✅ 位置参数 |
| `> 加 a=1 b=2` | 语句 | ✅ 具名参数 |
| `[加] 1 2` | 语句 | ✅ 方括号标记 + 位置参数(用于消歧/前置修饰) |
| `**r = > [加] 1 2**` | 粗体赋值 | ✅ 返回 3(方括号调用**已支持空格参数**) |
| `**r = 加 1 2**` | 粗体赋值 | ✅ **不带 `>` 也能调用,已可用**(打印 3) |
| `**r = > 加 a=1**` | 粗体赋值 | ✅ 显式 `>` 形态 |
| `**r = 加(1)**` | 粗体赋值 | ❌ `trailing input in expression: "(1)"` |
| `**r = [加](1 2)**` | 粗体赋值 | ❌ `unknown function `[加](1`` |
| `> [加](1 2)` | 语句 | ❌ `unknown function `[加](1`` |
也就是说:**「参数放在括号里」这件事今天完全不存在**。
---
## 2. `[函数名](参数)` 为什么碰壁
### 2.1 方括号 + 圆括号 = 取元,这是**已定的语义**
[collection-access-link.md](collection-access-link.md) §1 写的是心智模型:
> **方括号 = 取出的名字,圆括号 = 从哪取。**
```markdown
**价 = [拿铁](菜单)** # 从菜单里取出「拿铁」
```
[call-arguments.md](call-arguments.md) §2 进一步锁定:
> `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记。
所以 `[f](x)` 不是「还没被用的语法」,而是**已经被取元占用**。
### 2.2 靠「名字是函数还是键」消歧,会真的打断现有代码
这是本轮新增的硬证据。我把全仓库扫了一遍:
| 指标 | 数值 |
|------|------|
| `.mq.md` 文件 | 851 |
| `##` 级函数名 | 2367 |
| `[键](…)` 出现次数 | 983 |
| **键名与同文件函数名相同的冲突** | **5(去重后 2 个真实文件)** |
两个真实冲突(不是构造出来的):
```
ext/data/db.mq.md:122 *[count](r)* # 函数名 ## count,同时 r 里有 count 列
examples/code-as-docs/index.mq.md:79 价=[单价](行) # 函数名 ## 单价,同时 行 里有 单价 字段
```
**这说明任何「函数名优先」的规则都会改变这两处的行为**:它们本意是取元,却会被解释成调用。
反过来「数据优先」则永远无法用 `[f](1)` 调用。**两条路都走不通**——这不是实现难度问题,
而是同一外形承载两种语义的固有代价。
### 2.3 但有一个「无歧义子集」确实存在
`[f](1 2)` 与 `[f](a=1)` 里的括号内容**不是合法表达式**(实测 `x=1` 报
`unknown function`、`1 2` 报 `unknown function`),所以理论上可判为参数列表:
| 括号内容 | 能否是取元 | 可否判为调用 |
|---------|-----------|-------------|
| `(1 2)` 多 token | 否(非单一表达式) | ✅ 无歧义 |
| `(a=1)` 具名 | 否 | ✅ 无歧义 |
| `(1)` 单 token | **能** | ❌ 与 `[1](篮子)` 冲突 |
| `(m)` 单变量 | **能** | ❌ 与 `[a](m)` 冲突 |
于是 `[f](1)`(最常见的单参调用)**永远无法**与取元区分。
一个「多参数能用、单参数不能用」的语法,对使用者是最难记的一类。
---
## 3. `函数名(参数)`:空闲语法,原型验证通过
### 3.1 它是空闲的
实测 `**r = 加(1)**`(原型前)报 `trailing input in expression: "(1)"` ——
说明 `名字(` 今天既不表示取元,也不表示任何别的含义。**没有既有语义要保护。**
### 3.2 原型做了什么
改了两处(**已回退,仅作验证**):
1. `src/parse/expr.rs`:新增 `try_paren_call` —— 紧随其后的 `(` 视为参数列表;
在 `parse_call_tail` 里优先尝试。
2. `src/parse/mod.rs`:粗体赋值与 `>` 两条路径的「像调用」判定加上
`looks_like_paren_call`(让单 token 的 `加(1)` 也能进入调用分支)。
### 3.3 原型实测结果
| 用例 | 结果 |
|------|------|
| `加(1)` | ✅ 返回 2(单参) |
| `加(1 2 )` | ✅ 返回 3(多参) |
| `加("1" "2")` | ✅ 返回 `12`(字符串参数) |
| `加(1 2)` | ❌ 末参数把 `)` 吞了 |
| `加(a=1 b=2)` | ❌ 具名参数值把 `)` 吞了 |
| `加(1, 2)` | ❌ 逗号不是分隔符 |
| `加(加(1 2) 3)` | ❌ 嵌套未支持 |
| `txt.str_trim(" x ")` | ✅ 返回 `x`(**库函数路径可用**) |
| **全量测试** | ✅ **554 passed / 0 failed** |
**两条关键结论**:
1. **零回归**:新语法是纯增量,没有破坏任何既有用例(含 4 个 `[k](c)` 取元金样)。
2. **真正的落点在参数分词器,不在语法**:`加(1 2)` 失败、`加(1 2 )` 成功,
差别只是 `)` 前多一个空格——说明 `parse_call_args` 的分词把 `)` 当成了 token 的一部分。
要修就得动 `parse_call_args` / `split_first_token` / `find_next_arg_boundary`,
而这个分词器是**所有调用**(含今天在用的 `> f a=1`)共享的。
这解释了为什么这件事「看起来 10 行、实际一次核心改动」。
---
## 4. 人读性对比
同一个意思,五种写法:
| 写法 | 读起来 | 现状 |
|------|--------|------|
| `> 加 1 2` | 「调用加,1 和 2」 | ✅ |
| `**合计 = 加 1 2**` | 同上,无 `>` | ✅ |
| `**合计 = 加(1 2)**` | 「加(1, 2)」,**像数学/函数调用** | 原型通过 |
| `**合计 = 加(a=1 b=2)**` | 「加,a=1、b=2」,自解释 | 原型通过 |
| `**[加](1 2)**` | 像链接,但与取元同形 | ❌ 不建议 |
我的判断:**`f(args)` 是这几种里最符合人读习惯的**,理由有三:
1. **与数学记号同构**:`税率(2)`、`sin(x)` 是跨语言、跨学科的通用写法,不需要学。
2. **参数边界显式**:括号天然划定起止,解决了 `> f a b` 里「参数到哪结束」的模糊
(这也是 D8「函数名含空格」难题的天然解药)。
3. **不占用 Markdown 的链接语义**:渲染出来是普通文本 `f(1)`,
不会像 `[f](1)` 那样在预览里变成超链接。
---
## 5. 要走完这条路,需要做什么(评估工作量)
原型只验证了「方向可行」,要合入还缺这些:
| # | 事项 | 位置 | 风险 |
|---|------|------|------|
| 1 | `)` 作为参数终止符 | `parse_call_args` / `split_first_token` / `find_next_arg_boundary` | **中高**:所有调用共享 |
| 2 | 逗号分隔 `f(1, 2)` | 同上 | 中:逗号在文本参数里合法(`"a,b"` 已加引号则无碍) |
| 3 | 嵌套 `f(g(1) 2)` | `parse_call_args` 递归 | 中:需要括号深度跟踪 |
| 4 | 方法 `obj.m(1)` / 库 `lib.fn(1)` | `try_paren_call` 已有基础(库路径实测通过) | 低 |
| 5 | 位置/具名混用规则 | 复用 [call-arguments.md](call-arguments.md) §3 | 低 |
| 6 | 空参 `f()` | 需定义语义(零参调用) | 低 |
| 7 | EKC 指纹 | `collect_calls` 已读 `c.callee`,`CallExpr` 不变 → 自动兼容 | 无 |
| 8 | `view` 渲染 | `[callee]` 已有 `bracket_marked` 标记,需决定是否回显括号形式 | 低 |
| 9 | `marqdo check` | 需新增「`名字(` 但不是函数」的诊断 | 低 |
**注意第 7 条**:因为 `f(args)` 最终仍产出 `CallExpr { callee, args }`,
EKC 指纹、契约、字节码 `Op::Call(fid, argc)` **全部自动兼容**——
这正是它与「一等函数」方案([functions-as-values-evaluation.md](functions-as-values-evaluation.md) §5 路径 A)的本质区别:
**它只是换了一种写法,没有改变调用模型。**
---
## 6. 建议
### 6.1 推荐路线
1. **不做 `[f](args)`**:与取元同形,且已证明按名消歧会打断 2 个真实文件;
而「多参能用、单参不能用」的规则不可教。
2. **做 `f(args)`**:空闲语法、零回归、人读性好、不动调用模型。
3. 先落**具名**形态 `f(k=v)`(最无争议、自解释),再补位置 `f(1 2)`,最后考虑逗号与嵌套。
### 6.2 若你想保留方括号的「链接感」
有一个不碰取元的位置:**语句位置**。
```markdown
> [加](1 2) # 今天报 unknown function;语句位置的 [k](c) 无实际用途
```
`[k](c)` 作为**独立语句**今天只会算出值然后丢弃。全仓库扫描(851 文件):
以 `[` 起行且形如 `[k](c)` 的独立行只有 **2 处**,且都是样式示例文件里的
普通 Markdown 链接文本(`[海上花开](https://…)`),并非取元代码。
所以在**语句调用**里允许 `[f](args)` 几乎无成本,表达式里则不允许。
代价是「同一写法在两种位置含义不同」,可教性差;我倾向不做。
---
## 7. 待你决策
1. **是否采纳 `f(args)`**(不带方括号)作为新调用写法?
2. 若采纳,**先做哪一档**:
- A 只做具名 `f(k=v)`(最小、最稳)
- B 具名 + 位置 `f(1 2)`(需改分词器,价值最大)
- C 再加逗号与嵌套(一次做全)
3. **`[f](args)` 是否彻底放弃**(我建议放弃,理由 §2.2);
还是只允许在语句位置(§6.2)?
4. 是否需要我按 B 档做一次完整实现(含分词器改造 + 金样例 + 变更文档),
做完再走 554 回归?
原型代码已全部回退,工作区干净。等你定档我再动手。