Files
marqdo/doc/design/call-arguments.md

66 lines
3.8 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 适用范围校正**:本文保留早期调用尾部规则和历史示例,不是 v2.1 全部调用语法。当前已有 `f(args)` 及具名实参;默认紧邻 `](` 是描述包裹 payload,不再是下文所述的 Classic 取元。语法审阅与开发取舍见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),当前行为须由默认模式测试复核。
| | |
|---|---|
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
| 日期 | 2026-08-07 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) |
---
## 1. 目标
`>` 调用同时支持:
| 形式 | 示例 | 说明 |
|------|------|------|
| **具名**(保留) | `> 问候 谁=Marqdo` | `名=值`;值可含空格(至下一 `名=`) |
| **位置**(新增) | `> 问候 Marqdo` | 按形参声明顺序绑定 |
| **方括号标记**(增补) | `礼貌 [问候] Marqdo` | `[函数名]` 消歧;`[` 前裸词 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md) |
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。前置修饰语与显式同名具名冲突则报错。
---
## 2. 文法(调用尾部)
```
call_tail ::= bracket_call | classic_call
bracket_call ::= modifier* '[' callee ']' arg*
classic_call ::= callee arg*
arg ::= named | positional
named ::= ident '=' value
positional ::= value_token | '(' call_tail ')'
modifier ::= ident # 展开为 ident=True;核心不剥语言词缀
```
- `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记(见 [collection-access-link.md](collection-access-link.md))。
- 嵌套调用:把内层整段放进 `()`,例如 `[问候] ([格式化] "x")`。
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
- 实参值中 `` `变量` `` 后**紧跟** `[^…]` 时按**脚注取元**解析(可链式),而非文本:`> print text=苹果单价:`水果价格`[^苹果]`、`> print text=`订单`[^2][^品名]`。
- **独立 `>` 调用**:裸词 = 文本字面量。
- **`*…*` / `**…**` 段内的调用**(如 `*x = > text.split value=src sep=","*`):裸词 = **变量**(Python 统一命名空间),文本字面量必须加引号(`value="a,b"`);`` `名` `` 变量形式仍合法。
- 内置 `print` / `打印` 形参:`text` ≡ `内容`。
- `input` / `输入`:`prompt` ≡ `提示`。
- `len` / `长度`、`str` / `文本`、`int` / `整数`:`value` ≡ `值`。
- 完整中英双名见 [keywords-i18n.md](keywords-i18n.md)。
---
## 3. 绑定算法
1. 将前置修饰语展开为 `名=True` 具名(与显式具名冲突则报错)。
2. 收集具名 → 映射;冲突则报错。
3. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
4. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
5. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
---
## 4. 金样例
见 `tests/structure/positional-call.mq.md`、`tests/structure/bracket-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。