Files
marqdo/doc/design/paren-call-and-readable-invocation.md

232 lines
11 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.
# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式
> **2026-10-23 审阅裁决**:“原型回退”仅描述当时实验,当前 payload 已支持 `f(args)` 和具名实参。旧 Classic 索引冲突不再决定默认语法;保留熟悉的调用形态与文档原生描述并不矛盾。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),不要把本文备选形式当作已批准的新语法。
| | |
|---|---|
| 状态 | **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 回归?
原型代码已全部回退,工作区干净。等你定档我再动手。