diff --git a/doc/design/link-style-call-evaluation.md b/doc/design/link-style-call-evaluation.md index 586725e..c244380 100644 --- a/doc/design/link-style-call-evaluation.md +++ b/doc/design/link-style-call-evaluation.md @@ -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. 一句话结论 diff --git a/doc/design/paren-call-and-readable-invocation.md b/doc/design/paren-call-and-readable-invocation.md new file mode 100644 index 0000000..15b1b87 --- /dev/null +++ b/doc/design/paren-call-and-readable-invocation.md @@ -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 回归? + +原型代码已全部回退,工作区干净。等你定档我再动手。