# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式 > **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 回归? 原型代码已全部回退,工作区干净。等你定档我再动手。