Files
marqdo/doc/design/paren-call-and-readable-invocation.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

11 KiB
Executable File
Raw Permalink Blame History

调用写法评估:[函数名](参数) 与更接近人读的调用形式

2026-10-23 审阅裁决:“原型回退”仅描述当时实验,当前 payload 已支持 f(args) 和具名实参。旧 Classic 索引冲突不再决定默认语法;保留熟悉的调用形态与文档原生描述并不矛盾。参见文档原生指导 §2,不要把本文备选形式当作已批准的新语法。

状态 Proposed · 待决策(原型已验证并已回退,未合入代码)
日期 2026-10-22
提出 「[函数名](参数1 参数2) 这种写法有没有可能成立;调用能否更符合人读习惯」
更正 本文替代前两轮对用户意图的误读(前两轮在讨论「表 / 函数即值」,不是调用语法)
相邻 link-style-call-evaluation.md · function-as-table-semantics.md · collection-access-link.md · call-arguments.md

0. 结论

问题 答案
[函数名](参数1 参数2) 能否成立 技术上能,但代价在方括号:它撞的是取元 [键](集合),而命名空间里确有 2 个真实文件以函数名作键,任何「按名字消歧」都会静默改语义
更人读的调用能否成立 能,而且更干净:函数名(参数1 参数2)(不带方括号)目前是完全空闲的语法,原型实测全量 554 passed / 0 failed,零回归

一句话:想要「参数进括号」这个美感,不需要方括号——去掉方括号反而没有任何冲突。

**税率 = 查询税率(档位=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 §1 写的是心智模型:

方括号 = 取出的名字,圆括号 = 从哪取。

**价 = [拿铁](菜单)**     # 从菜单里取出「拿铁」

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 §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 §5 路径 A)的本质区别: 它只是换了一种写法,没有改变调用模型。


6. 建议

6.1 推荐路线

  1. 不做 [f](args):与取元同形,且已证明按名消歧会打断 2 个真实文件; 而「多参能用、单参不能用」的规则不可教。
  2. 做 f(args):空闲语法、零回归、人读性好、不动调用模型。
  3. 先落具名形态 f(k=v)(最无争议、自解释),再补位置 f(1 2),最后考虑逗号与嵌套。

6.2 若你想保留方括号的「链接感」

有一个不碰取元的位置:语句位置。

> [加](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 回归?

原型代码已全部回退,工作区干净。等你定档我再动手。