- 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。
622 lines
26 KiB
Markdown
Executable File
622 lines
26 KiB
Markdown
Executable File
# Marqdo 语法映射 v0.3(叙述统一 · 粗体即代码)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **Accepted · 现行运行时目标(实现中)** |
|
||
| 日期 | 2026-09-13 |
|
||
| 取代 | [markdown-mapping.md](markdown-mapping.md) **v0.2(已废止为运行时宪法)** |
|
||
| ADR | [0005-prose-unified-markup.md](../adr/0005-prose-unified-markup.md) |
|
||
| 路线 | [markup-v0.3.md](../roadmap/markup-v0.3.md) |
|
||
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [call-arguments.md](call-arguments.md) · [objects.md](objects.md) · [keywords.md](keywords.md) |
|
||
|
||
> **名词:** 本文「Markup」指 Marqdo **如何把 Markdown 标记映射成语法**(`**` 代码、`*` 返回、`` `名` `` 声明),不是另一个语言。产品仍是 Marqdo。
|
||
> **v0.3 为唯一映射。** 不做 v0.2 双模式 / `--markup` 版本身份。摸索阶段允许破坏性变更;旧 `.mq.md`(`*语句*` / `**返回**`)须改写。金样例见 `tests/markup-v03/`。
|
||
|
||
---
|
||
|
||
## 0. 一句话
|
||
|
||
让 **Markdown 叙述本身成为程序的一部分**:普通文字里用 `` `名` `` 出现变量(首次未赋值 = 声明);用 **`**…**` 粗体** 包裹可执行代码(含调用,不必再写 `>`);用 **`*…*` 斜体** 表示返回值。函数形参**不再手写 `+` 列表**,由函数体内的声明/赋值自行推断。
|
||
|
||
---
|
||
|
||
## 1. 动机(为何推翻 v0.2 的部分定论)
|
||
|
||
v0.2 为了「标记即语法」的清晰边界,做了这些硬隔离:
|
||
|
||
| v0.2 | 代价 |
|
||
|------|------|
|
||
| 无标记行 = 纯注释;变量只能写在 `*…*` / 结构行里 | 叙述与代码割裂,「文档即代码」读起来像两套语言叠在一起 |
|
||
| `*…*` = 语句,`**…**` = 返回 | 与常见 Markdown/AI 习惯相反:模型更爱用 `**` 强调「要执行的东西」,读者也更易看见粗体 |
|
||
| 调用必须 `>` | 行间调用要另起结构行,叙述中夹调用不自然 |
|
||
| 形参必须 `` + `名` `` | 仪式感强;函数头像「另一套签名语言」,与正文脱节 |
|
||
|
||
古早示例(当时不能跑,正是本文要合法化的目标面):
|
||
|
||
```markdown
|
||
## 加一函数
|
||
|
||
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
|
||
|
||
# main
|
||
|
||
我要调用加一函数可以采用这样的办法:
|
||
|
||
> 加一函数 37
|
||
|
||
或者可以直接这么调用**加一函数 37**
|
||
```
|
||
|
||
目标:上述文件在 v0.3 下应能解析、求值,且**读起来仍是一篇正常中文说明**。
|
||
|
||
---
|
||
|
||
## 2. 哲学(设计原则)
|
||
|
||
### P1 — 叙述统一(Prose-unified)
|
||
|
||
- Marqdo 注释采用 **Markdown 叙述**(段落、列表中的说明文字),不是第二种注释语法。
|
||
- **变量可以出现在正常文字之间**:用 Markdown 行内代码 `` `n` `` 标识标识符。
|
||
- **第一次出现且未赋值 = 声明变量**;之后的出现 = 引用。赋值发生在粗体代码段内(或兼容的结构赋值形)。
|
||
- **未使用的变量无害**(不报错、不升参);真正的输入由「可执行面读取」升为形参(§8)。
|
||
- 这样「说明文字」与「程序名字」共用同一套 Markdown 视觉习惯,整体更和谐。
|
||
|
||
### P2 — 粗体即代码(Bold-as-code)
|
||
|
||
- **`**…**` = 代码段**(可执行):赋值、表达式、函数/方法调用、可内联的短语句。
|
||
- 选择粗体的原因:
|
||
1. **AI 输出偏好**:模型天然爱用 `**` 强调「重要操作」;把粗体定为可执行,降低「模型写了强调却被当成返回」的错配。
|
||
2. **行间显眼**:在长段落里,粗体比斜体更容易被扫到。
|
||
- 粗体代码段内的调用 **允许不写 `>`**:`**加一函数 37**` 与 `> 加一函数 37` 语义等价(见 §6)。
|
||
- **`>` 保留为可选调用面**(blockquote 风格、独立行、兼容 v0.2 迁移与 AI 已学会的形态)。
|
||
|
||
### P3 — 斜体即返回(Italic-as-return)
|
||
|
||
- **`*…*` = 返回值**(架构级),与粗体代码形成对立、易读的一对:
|
||
- 做了什么 → 粗体
|
||
- 结果是什么 → 斜体
|
||
- **空返回 / 无值收束**(已决议,见 §7.2):推荐 `*None*` / `*无*`;整行 `**`;兼容 `****`。`---` / `***` 仅为叙述分隔(跳过),**不再**结束函数体。
|
||
- **输出仍不是返回**:打印继续用内置 `print` / `打印`(副作用函数),不把粗体或斜体当成「打印到终端」的语法。
|
||
|
||
### P4 — 形参由体推断(Body-inferred params)
|
||
|
||
- **不再要求**作者手写 `` + `名` `` 形参表(v0.3 默认关闭;过渡期可兼容,见 §8)。
|
||
- 函数体内:
|
||
- **只声明、未赋默认** → **必选形参**(调用时必须提供)。
|
||
- **声明同时赋值**(含默认值字面量)→ **可选形参**(带默认值)。
|
||
- 推断顺序与绑定规则见 §8;与位置/具名实参规则对齐 [call-arguments.md](call-arguments.md) 的精神(可修订附录)。
|
||
|
||
### P5 — 标记仍承载控制流(不变)
|
||
|
||
- **不引入** `if` / `else` / `while` / `for` / `def` / `return` 关键字。
|
||
- `#` = 对象/类型,`##`+ = 函数/方法([objects.md](objects.md) 不变)。
|
||
- 分支仍用 `1.` `2.` …;循环仍用 `-`;结构行不必再包粗体(见 §5)。
|
||
|
||
### P6 — 其它「代码即文档」补强(本版一并采纳)
|
||
|
||
| 思路 | 说明 |
|
||
|------|------|
|
||
| **渐进披露** | 读者可只读叙述;运行时只执行标记与推断出的声明。同一文件服务人与机器。 |
|
||
| **最小仪式** | 能从正文看出的签名,就不在函数头重复写一遍。 |
|
||
| **双调用面** | 独立行 `>` 适合「步骤清单」;行间 `**f …**` 适合「嵌在句子里的动作」。 |
|
||
| **标识符视觉统一** | 叙述、代码、形参一律优先 `` `名` ``;粗体/斜体内部允许裸名(与 v0.2 斜体/粗体内规则同类)。 |
|
||
| **段落仍可整段注释** | 不含任何可执行标记、且无「声明性 `` `名` ``」义务的纯说明段,行为与注释相同(见 §4 消歧)。 |
|
||
| **迁移可观测** | `--dump-lines` / `--dump-ast` 必须能区分「叙述中的声明」与「粗体代码」与「斜体返回」。 |
|
||
|
||
---
|
||
|
||
## 3. 与 v0.2 对照(角色对调摘要)
|
||
|
||
| 概念 | v0.2 | v0.3 |
|
||
|------|------|------|
|
||
| 程序语句 / 代码段 | `*…*` | `**…**` |
|
||
| 返回值 | `**…**` | `*…*` |
|
||
| 独立调用 | 必须 `>` | `>` **或** `**callee …**` |
|
||
| 形参 | 标题下 `` + `名` `` | **体推断**(`+` 过渡兼容) |
|
||
| 叙述中的变量 | 一般为注释,不可声明 | `` `名` `` 可声明/引用 |
|
||
| 无标记纯文字 | 成段注释 | 仍为叙述;**若含声明性反引号则参与绑定图**(见 §4) |
|
||
|
||
这是一次 **架构级标记对调**,不是局部糖。金样例、教程、Skill、扩展库需按路线图分波迁移。
|
||
|
||
---
|
||
|
||
## 4. 叙述、声明与注释
|
||
|
||
### 4.1 三层模型(修订)
|
||
|
||
| 层 | 形态 | 角色 |
|
||
|----|------|------|
|
||
| **叙述面** | 普通 Markdown 段落、列表说明 | 给人读;其中的 `` `名` `` 可进入**绑定图** |
|
||
| **可执行面** | 结构标记(`#` `>` `+` `-` `1.` 表…)+ **`**代码**`** + **`*返回*`** | 求值 |
|
||
| **外联面** | ` ```lang ` | FFI(不变) |
|
||
|
||
### 4.2 变量在叙述中的出现
|
||
|
||
语法:Markdown **行内代码** `` `标识符` ``。
|
||
|
||
| 出现形态 | 语义 |
|
||
|----------|------|
|
||
| 全文(当前函数/对象作用域)**首次**出现 `` `n` ``,且此前/同句无对 `n` 的赋值 | **声明变量**(进入绑定图;是否升为形参见 §8) |
|
||
| 已声明之后再次 `` `n` `` | **引用**(不生成新绑定) |
|
||
| 粗体内 `**n = …**` / `**n=n+1**` | **赋值**(若首次赋值且未见声明,则声明+赋值一并发生) |
|
||
| 叙述中 `` `n`=1 ``(反引号名紧贴 `=`,无粗体) | **带初值的声明**(形参默认或局部初值;见 §8) |
|
||
|
||
推荐作者写法(与动机示例一致):
|
||
|
||
```markdown
|
||
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
|
||
```
|
||
|
||
- `` `n` `` → 声明变量;因随后在代码中**读取**未先由局部独力定义 → 升为必选形参(§8)
|
||
- `**n=n+1**` → 代码段(赋值)
|
||
- `*n*` → 返回
|
||
|
||
### 4.3 何为「纯注释」
|
||
|
||
满足下列**全部**条件的段落,不产生绑定、不求值:
|
||
|
||
1. 不含结构标记行;
|
||
2. 不含 `**…**` / 作为返回的 `*…*`(见 §7);
|
||
3. 不含任何 `` `标识符` ``。
|
||
|
||
仍建议:**叙述段与独立结构代码行之间空一行**,降低人读与差分时的视觉粘连(解析器在 v0.3 下不再依赖「空行分段注释升级」作为唯一边界,但空行仍是作者卫生习惯)。
|
||
|
||
### 4.4 提及性反引号:一律视作变量(已决议)
|
||
|
||
**不另设「仅提及、不声明」语法。** 叙述里凡出现合法标识符 code span `` `名` ``,一律按 **变量** 处理(首次 = 声明,其后 = 引用)。
|
||
|
||
| 情况 | 处理 |
|
||
|------|------|
|
||
| 谈到某名但可执行代码**从未读写**它 | 仍是绑定图中的变量;**对求值无影响**(死绑定) |
|
||
| 与其它语言对照 | 类似 Python 写了未用局部、JS 未用 `let`——默认可忽略;实现可对「从未读写」发**可选 lint**,**不得**因此报错或拒绝运行 |
|
||
| 是否变成函数形参 | **否**(仅声明、从未在可执行面被读取)——见 §8.2「升参条件」 |
|
||
| 是否需要 `` 提及`n` `` 等前缀 | **不需要**;避免第二套反引号方言 |
|
||
|
||
例(合法、无副作用):
|
||
|
||
```markdown
|
||
## 说明性函数
|
||
|
||
本文顺便提到`Markdown`与`GFM`,但真正的输入只有`题干`。
|
||
**print text=题干**
|
||
---
|
||
```
|
||
|
||
- `` `Markdown` `` / `` `GFM` `` → 变量声明,未使用 → 不进形参表、不改行为
|
||
- `` `题干` `` → 声明且在粗体中读取 → 必选形参
|
||
|
||
**否决**:为「提及」单独做转义/前缀(曾列于开放点);若将来作者强烈需要「叙述中的等宽字但不进绑定图」,另开增强案,不阻塞 v0.3 核心。
|
||
|
||
### 4.5 成段规则相对 v0.2 的变化
|
||
|
||
v0.2:「段首无标记 → 整段注释,续行永不升级」。
|
||
v0.3:
|
||
|
||
- 叙述段落**可以**内含可执行粗体/斜体返回;解析器做**段内扫描**,抽出 `` `名` ``、`**…**`、`*…*`。
|
||
- 独立结构行(行首 `#` `>` `-` `1.` `|` 等)仍整行分类为代码。
|
||
- **否决维持**:「整行无标记 = 默认可执行代码」。无标记且无反引号声明的文字永不单独变成语句。
|
||
|
||
---
|
||
|
||
## 5. 映射总表(v0.3)
|
||
|
||
| 标记 | 语义 |
|
||
|------|------|
|
||
| `#` … `######` | `#` = 对象/类型;`##`+ = 函数/方法(同 [objects.md](objects.md)) |
|
||
| 叙述中 `` `名` `` | 声明或引用(§4) |
|
||
| `**…**` | **代码段**(赋值、表达式、调用) |
|
||
| `*…*` | **返回值**(含显式空值,见 §7.2) |
|
||
| `>` 行 | **调用**(可选面,与粗体内调用等价) |
|
||
| `` + `名` `` | **过渡兼容**:显式形参;新代码不推荐 |
|
||
| 体内 `1.` `2.` … | 分支 |
|
||
| 体内 `-` | 循环 |
|
||
| `N. *` | else 臂(此处 `*` 仍是「空条件」标记,**不是**返回值;见 §7.3) |
|
||
| GFM 表格 | 集合;`` `名` = `` 后绑定,或**未绑定**时求值后丢弃(文档中可写表) |
|
||
| 表达式 `[键](集合)` | **取元**(与 foreach 同形;见 [collection-access-link.md](collection-access-link.md)) |
|
||
| `修饰… [函数名] 实参…` | **方括号标记调用**(前置修饰 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md)) |
|
||
| `` 集合[^键] `` | **过渡**:旧脚注取元(仍可用) |
|
||
| ` ```lang ` | 外联(不变;绑定仍用 `` `名` = `` + 围栏) |
|
||
| `$$` 内 `% marqdo: var=名` | 块公式绑定([fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)) |
|
||
| `- 对`集`的每一项`项`` / `for each` | foreach 叙述糖;推荐 `- [项](集)` |
|
||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;模块顶与函数体内相同) |
|
||
| 整行恰 `**` 或 `****` / `*None*` / `*无*` | **空返回**并结束本函数体(见 §7.2) |
|
||
|
||
### 结构行与粗体
|
||
|
||
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包 `**…**`。
|
||
粗体用于:**嵌在叙述中的代码**,以及「我想把这一小段标成可执行」的行间片段。
|
||
|
||
---
|
||
|
||
## 6. 调用
|
||
|
||
### 6.1 调用表面
|
||
|
||
```markdown
|
||
> 加一函数 37
|
||
|
||
**加一函数 37**
|
||
|
||
礼貌 [问候] marqdo
|
||
```
|
||
|
||
前两种解析为对 `加一函数` 的调用;第三种为**方括号标记调用**(`[` `]` 标出函数名,前置裸词展开为 `名=True`)。实参位置或具名绑定;详见 [call-arguments.md](call-arguments.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md)。
|
||
|
||
| 形式 | 典型用途 |
|
||
|------|----------|
|
||
| `> …` | 步骤列表、独立可执行行、与 v0.2/AI 习惯兼容 |
|
||
| `**…**` | 嵌在句子中:「或者可以直接这么调用**加一函数 37**」 |
|
||
| `**x = 加一 37**` | 粗体赋值右侧为调用时**可省略 `>`**(代码即文档首选;`> 加一 37` 仍合法) |
|
||
| `修饰… [函数] 实参…` | 叙述里需要「形容词 + 动词」时消歧;与 `[键](集合)` 取元靠 `]` 后是否紧邻 `(` 区分 |
|
||
|
||
### 6.2 粗体内调用的判别
|
||
|
||
粗体内容在去掉外层 `**` 后,按下列优先级分类:
|
||
|
||
1. 含 `=` 且左侧为可赋值目标(标识符 / 脚注左值等)→ **赋值语句**(可含右侧调用)。
|
||
2. 否则,若首词为已知函数/方法/内置/导入成员(Pass 名表可见)→ **调用**。
|
||
3. 否则 → **表达式语句**(求值后丢弃,或在语句位置非法则诊断)。
|
||
|
||
示例:
|
||
|
||
| 粗体内容 | 分类 |
|
||
|----------|------|
|
||
| `n=n+1` | 赋值 |
|
||
| `加一函数 37` | 调用 |
|
||
| `加一函数 n=37` | 调用(具名) |
|
||
| `n + 1` | 表达式(单独出现时;作返回应写 `*n + 1*`) |
|
||
| `print text=hi` / `打印 内容=你好` | 调用(内置) |
|
||
|
||
### 6.3 方法调用
|
||
|
||
- 独立行:`` > `对象`.方法 … ``(兼容)或 `> 对象.方法 …`(若接收者规则允许)。
|
||
- 粗体内:`**对象.方法 …**` / `**p = page.主体装配 组件=home**`。
|
||
- 粗体/斜体内裸名 = 变量(延续 v0.2「段内统一命名空间」精神)。
|
||
|
||
### 6.4 实参
|
||
|
||
具名 + 位置混用规则继承 [call-arguments.md](call-arguments.md);v0.3 仅把「形参列表来源」从 `+` 行改为**推断签名**(§8)。独立 `>` 行上裸词仍为文本字面量;粗体内调用的裸词为变量(与 v0.2「段内调用」一致)。
|
||
|
||
---
|
||
|
||
## 7. 返回
|
||
|
||
### 7.1 斜体返回
|
||
|
||
```markdown
|
||
*n*
|
||
*n + 1*
|
||
*"ok"*
|
||
```
|
||
|
||
斜体内部值语法与 v0.2 粗体返回内部相同(裸词 = 变量;文本须引号)。
|
||
|
||
### 7.2 空返回与收束(已决议)
|
||
|
||
Marqdo **不引入** `return` 关键字;「无值结束」用标记表达。对照常见语言:
|
||
|
||
| 语言 | 无值 / 空返回 | Marqdo v0.3 对应 |
|
||
|------|----------------|------------------|
|
||
| Python | `return` / `return None` | 显式 `*None*`·`*无*` |
|
||
| Go | 无结果函数里的 `return` | `*None*` / 整行 `**` / `****` |
|
||
| Rust | `()` 或函数末尾隐式 unit | 同上;或下一标题 / EOF 自然结束 |
|
||
| JavaScript | `return;` → `undefined` | 同上 → 运行时 `None` |
|
||
| Marqdo 历史 | `---` 收束;`****` | `---` 已改为叙述跳过;`****` 仍兼容 |
|
||
|
||
#### 形式层级(推荐自上而下)
|
||
|
||
| 优先级 | 形式 | 语义 | 说明 |
|
||
|--------|------|------|------|
|
||
| **1. 显式空值** | `*None*` 或 `*无*`(整段或行内返回位) | 返回 `None` **并结束本函数体解析** | 对齐 Python `return None`;副作用函数首选;外层续写依赖此收束 |
|
||
| **2. 空斜体标记** | **整行** trim 后恰为两个星号:`**` | 同上 | 词法钉死:`^\s*\*\*\s*$` → **空斜体返回**,**不得**当成粗体开闭 |
|
||
| **3. 兼容** | 整行 `****`(四个星号) | 同空返回 | 迁移期识别 |
|
||
| **(非收束)** | 整行 `---` / `***` | **仅叙述分隔**,跳过 | 不再结束函数;见 [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||
|
||
```markdown
|
||
## 只打印
|
||
**print text=hi**
|
||
*None*
|
||
|
||
## 空斜体行
|
||
**print text=hi**
|
||
**
|
||
|
||
## 分割线不收束(下一标题才结束)
|
||
**print text=hi**
|
||
---
|
||
```
|
||
|
||
#### 词法消歧(空斜体 vs 粗体)
|
||
|
||
1. **整行恰好 `**`(两个 `*`)** → 空返回(规则 2),不是未闭合粗体。
|
||
2. **粗体代码**至少包住一个非空内容:`**x**`、`**n=1**`;不允许「空粗体代码段」作为语句。
|
||
3. **四个星号整行 `****`** → 兼容空返回(规则 3),不解释为「空粗体代码」。
|
||
4. 行内出现的 `**…**`(两侧还有叙述文字)按正常粗体代码扫描,不走「整行空返回」。
|
||
|
||
#### 与「有返回值」的关系
|
||
|
||
- 需要把值交回调用方 → 用非空斜体:`*n*`、`*n + 1*`(返回即结束本函数体解析)。
|
||
- 只做副作用、不要值 → 优先 `*None*` / `*无*` / 整行 `**`。
|
||
- 下一标题或 EOF 也可结束体;**不要**再靠 `---` 收束。
|
||
|
||
### 7.3 与 else 臂 `N. *` 的消歧
|
||
|
||
有序列表臂头 `2. *` 中的 `*` 表示 **else**,不是返回。判别:行匹配 `^\s*\d+\.\s+\*\s*$`(可带尾注)→ 分支 else;不进入返回扫描。
|
||
|
||
### 7.4 输出
|
||
|
||
```markdown
|
||
**print text=Hello**
|
||
> print text=Hello
|
||
```
|
||
|
||
打印是调用,不是返回。禁止把 `*Hello*` / `**Hello**` 解释为「打印 Hello」(延续 v0.2 决议精神,仅对调标记)。
|
||
|
||
---
|
||
|
||
## 8. 形参推断
|
||
|
||
### 8.1 目标签名
|
||
|
||
对每个 `## 函数`(及方法),在 Pass1 收集体之后得到:
|
||
|
||
```text
|
||
params: Vec<{ name, default: Option<Expr>, span }>
|
||
```
|
||
|
||
### 8.2 收集规则(函数作用域)
|
||
|
||
扫描该函数标题之下、下一同级/更高级标题之前的所有节点,维护**绑定图**与**形参表**(二者分离):
|
||
|
||
#### A. 绑定图(所有变量)
|
||
|
||
1. **声明事件**:叙述或代码中的首次 `` `名` ``,或粗体内首次对 `名` 的赋值左值。
|
||
2. **默认/初值事件**:叙述 `` `名`=默认表达式 ``;或符合 §8.3 的「形参默认」赋值。
|
||
3. **排除出绑定图**(不建变量):
|
||
- 循环变量 `` - [项](集合) `` 中的 `项`(循环自有绑定);
|
||
- `self` / `自`(方法自动注入)。
|
||
|
||
凡进入绑定图的名字都是**变量**——包括「只在叙述里出现、可执行代码从未读写」的名字(§4.4)。未使用 → **不报错**。
|
||
|
||
#### B. 升为形参的条件(升参)
|
||
|
||
名字已在绑定图中,且满足下列之一,才进入 `params`:
|
||
|
||
| 升参种类 | 条件 |
|
||
|----------|------|
|
||
| **必选形参** | 在可执行面(`**…**` / `*…*` / `>` / 结构语句)中存在对 `名` 的**读取**,且该读取无法单靠「不依赖外部输入的局部赋值」满足——典型:先声明、后 `n=n+1` / `*n*` / `**print text=n**` 等读到未先行赋成纯局部常量 |
|
||
| **可选形参** | 有默认/初值事件(`` `名`=… `` 或 §8.3 默认赋值),供调用方覆盖 |
|
||
|
||
**不升参**:仅叙述声明、可执行面零读取(死绑定)→ 留在绑定图,**不进** `params`,调用签名不变。
|
||
|
||
**顺序**:按升参名字的**首次声明事件**在源码中的出现序。
|
||
|
||
**仍排除**:分支/块内纯局部(金样例钉启发式);显式 `+` 合并见 §8.4。
|
||
|
||
### 8.3 「形参默认」与「函数体赋值」的区分
|
||
|
||
```markdown
|
||
## 问候
|
||
对`谁`打招呼,默认`礼貌`=False。
|
||
|
||
**print text=谁**
|
||
```
|
||
|
||
- `` `谁` `` → 必选
|
||
- `` `礼貌`=False `` → 可选,默认 `False`
|
||
- 体里的 `**print …**` 不是给 `谁` 赋默认值
|
||
|
||
```markdown
|
||
## 加一函数
|
||
输入`n`。**n=n+1**返回*n*。
|
||
```
|
||
|
||
- `` `n` `` 先声明 → 必选
|
||
- `**n=n+1**` 是**体语句**(对已声明形参赋值),**不是**默认值
|
||
|
||
判别启发式(实现契约):
|
||
|
||
- 若赋值右值**依赖同名左值**(如 `n=n+1`)→ 体语句。
|
||
- 若赋值出现在「该名被当作输入读取」之前,且右值不依赖未绑定的同名 → 可作为默认值候选。
|
||
- 叙述形 `` `名`=字面量 `` 优先视为默认值声明。
|
||
|
||
### 8.4 显式 `+` 形参(过渡)
|
||
|
||
- 若函数标题下仍有 `` + `名` `` 行:与推断结果**合并**;冲突时 **显式 `+` 胜出**并诊断警告。
|
||
- 迁移完成后(路线图 M4)可改为:存在 `+` 则关闭推断,或直接废弃 `+`。
|
||
|
||
### 8.5 调用绑定
|
||
|
||
与现有一致:具名优先,位置按「尚未绑定的形参」从左到右填充。缺必选形参 → 语义错误。
|
||
|
||
---
|
||
|
||
## 9. 完整示例(规范金样意向)
|
||
|
||
### 9.1 加一(动机例)
|
||
|
||
```markdown
|
||
## 加一函数
|
||
|
||
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
|
||
|
||
# main
|
||
|
||
我要调用加一函数可以采用这样的办法:
|
||
|
||
> 加一函数 37
|
||
|
||
或者可以直接这么调用**加一函数 37**
|
||
```
|
||
|
||
期望:
|
||
|
||
- 签名:`加一函数(n)`
|
||
- `# main` 两次调用均返回 `38`(第二次若未绑定到打印,至少 AST/求值结果为 38;可用 `**print text=…**` 观测)。
|
||
|
||
### 9.2 带默认值
|
||
|
||
```markdown
|
||
## 问候
|
||
|
||
向`谁`问好;`礼貌`=False 时用短句。
|
||
|
||
1. 礼貌
|
||
**print text=您好,**
|
||
**print text=谁**
|
||
2. *
|
||
**print text=嗨,**
|
||
**print text=谁**
|
||
|
||
---
|
||
|
||
# main
|
||
|
||
**问候 谁=Marqdo 礼貌=True**
|
||
> 问候 Marqdo
|
||
```
|
||
|
||
### 9.3 对象方法(不变骨架)
|
||
|
||
```markdown
|
||
# 计数器
|
||
## 加
|
||
将`self`的`值`增加`delta`(`delta`=1)。
|
||
**值 = 值 + delta**
|
||
*self*
|
||
|
||
# main
|
||
*c = > 计数器*
|
||
**c.加 3**
|
||
```
|
||
|
||
(方法形参推断含 `delta`;`self` 自动。)
|
||
|
||
---
|
||
|
||
## 10. AST / 管线变更要点(设计约束)
|
||
|
||
详细里程碑见 [markup-v0.3.md](../roadmap/markup-v0.3.md)。此处只钉**语义 → 树**的约束,供实现对照:
|
||
|
||
### 10.1 行分类(lex / line-class)
|
||
|
||
新增或调整类别:
|
||
|
||
| 类别 | 说明 |
|
||
|------|------|
|
||
| `Prose` | 叙述行;需**内联扫描** |
|
||
| `BoldCode` | 整行或片段 `**…**` |
|
||
| `ItalicReturn` | 整行或片段 `*…*`(非 else 臂) |
|
||
| `CallLine` | `>` 调用(保留) |
|
||
| … | 原有 Heading / List / Table / Fence / Hr |
|
||
|
||
**内联扫描**产出 `InlineBit`:`Text` | `IdentDecl/Ref` | `BoldCode` | `ItalicReturn`。
|
||
|
||
### 10.2 AST 节点调整(建议)
|
||
|
||
```text
|
||
Param { name, default?, inferred: bool, span } // inferred=true 表示来自体推断
|
||
|
||
Stmt::
|
||
Assign { … } // 多由 BoldCode 解析
|
||
Call { … } // CallLine 或 BoldCode 判别为调用
|
||
Return { value } // 由 ItalicReturn 解析(原由 Bold)
|
||
ExprStmt { … } // 可选:纯表达式粗体
|
||
Prose { bits } // 可选:保留叙述结构供 view/catalog;求值阶段只消费 Decl
|
||
|
||
FnDef.params:
|
||
由 InferParams(body + prose bits) 填充,再合并显式 +
|
||
```
|
||
|
||
`Stmt::Return` 的**语法来源**从粗体改为斜体;dump 文本应写 `return←italic`。
|
||
|
||
### 10.3 Pass1 / Pass2
|
||
|
||
- Pass1:收集 `#`/`##` 结构;建绑定图;跑 **ParamInfer(升参)**;登记名表。
|
||
- Pass2:粗体内调用名解析;叙述 Decl 不重复建参。
|
||
- 诊断:**必选缺失**、`+` 与推断冲突、空返回词法歧义(非整行 `**` 的残缺粗体)。
|
||
- Lint(可选、默认关或降级为 hint):绑定图中「从未读写」的死变量——**不得**当错误。
|
||
|
||
### 10.4 双后端
|
||
|
||
树遍历与字节码均消费同一 AST;字节码发射仅跟随 `Stmt`/`Expr` 变化,不感知 Markdown 标记。
|
||
|
||
---
|
||
|
||
## 11. 破坏性切换(无双模式)
|
||
|
||
**产品决定(2026-09-13):** 直接以 v0.3 为唯一运行时映射;**不**保留 `--markup v0.2` / 双 edition。旧语法金样例与库文件在迁移完成前可能失败——可接受。
|
||
|
||
| 阶段 | 行为 |
|
||
|------|------|
|
||
| 现在 | 解析器切到 v0.3;`tests/markup-v03/` 为门禁 |
|
||
| 随后 | 批量改写 `tests/structure|keywords`、`lib/`、`ext/`、Skill、`public/` |
|
||
| 文档 | `markdown-mapping.md` 改为指向本文;ADR 0005 → Accepted |
|
||
|
||
**机械改写:**
|
||
|
||
- 语句 `*a = 1*` → `**a = 1**`
|
||
- 返回 `**x**` → `*x*`
|
||
- 粗体内文本字面量须引号:`**print text="hi"**`(裸词 = 变量)
|
||
- 调用可保留 `>` 或改为粗体
|
||
- `` + `n` `` 可删,改为叙述 `` `n` `` + 升参
|
||
|
||
---
|
||
|
||
## 12. 开放问题 / 已决议
|
||
|
||
| # | 议题 | 状态 | 决议摘要 |
|
||
|---|------|------|----------|
|
||
| 1 | 空返回词法 | **已决议** | §7.2:推荐 `*None*`/`*无*`;整行 `**`;兼容 `****`;`---` 仅叙述跳过 |
|
||
| 2 | 提及性反引号 | **已决议** | §4.4:一律视作变量;未使用不报错、不升参;不设提及前缀 |
|
||
| 3 | 粗体内调用 vs 赋值 | **已落地** | §6.2:可赋值左值 → 赋值;否则表达式优先、再裸调用;`**n + 1**` = ExprStmt |
|
||
| 4 | `` `n`+1 `` 误声明 | **已落地** | Decl 名须为标识符;`` `n+1` `` 不升 Decl |
|
||
| 5 | 叙述强调斜体 vs 返回 | **已落地** | 整行 / `返回*…*` / 表达式形才当返回;`*only*` `*very important*` `*foo.bar*` 为叙述 |
|
||
| 6 | 一行多 `**…**` | **已落地** | 允许,按出现序执行(`tests/markup-v03/multi-bold.mq.md`) |
|
||
| 7 | view 展示 prose Decl | **已落地** | Structure / Functions 大纲:`inferred` 形参标注(`chip inferred`) |
|
||
|
||
---
|
||
|
||
## 13. 非目标
|
||
|
||
- 不把整篇无标记 Markdown 变成可执行程序。
|
||
- 不引入 `def` / `return` 关键字(空返回用标记,见 §7.2)。
|
||
- 不改变 `#` / `##` 对象体系与 ext 插件 ABI。
|
||
- 不在本文阶段修改解释器代码(见路线图)。
|
||
- 不为「提及」另发明一套反引号方言(§4.4)。
|
||
|
||
---
|
||
|
||
## 14. 验收标准(设计完成 ≠ 实现完成)
|
||
|
||
设计稿验收:
|
||
|
||
- [x] 哲学 P1–P6 成文
|
||
- [x] 与 v0.2 对照表
|
||
- [x] 形参推断规则可实现(含升参 vs 死绑定)
|
||
- [x] 动机示例在语义上闭合
|
||
- [x] AST/管线约束与路线图挂接
|
||
- [x] ADR 记录决策意向
|
||
- [x] **空返回**对照其它语言并钉死词法
|
||
- [x] **提及/未使用变量**政策钉死
|
||
|
||
实现验收:
|
||
|
||
- [x] 金样例夹具 `tests/markup-v03/`(`gold.rs` `markup_v03_*`)
|
||
- [x] 动机示例金样例通过(`inc-prose.mq.md`)
|
||
- [x] `--dump-ast` 可见 inferred params 与死绑定;`--dump-lines` 标注 `[decl]` / `[bold]` / `[italic]`
|
||
- [x] 空返回四种形式金样例通过
|
||
- [x] 无 v0.2 双模式(默认即 v0.3)
|
||
|
||
---
|
||
|
||
## 15. 修订历史
|
||
|
||
| 日期 | 说明 |
|
||
|------|------|
|
||
| 2026-09-13 | 初稿:叙述统一、粗体代码、斜体返回、形参体推断;Proposed |
|
||
| 2026-09-13 | 决议空返回(§7.2)与提及性反引号(§4.4);形参改为「升参」与绑定图分离(§8.2) |
|
||
| 2026-09-14 | §7.2:`---` 不再收束;返回语句结束函数体解析;空返回首选 `*None*` |
|
||
| 2026-09-14 | 取元主语法改为 `[键](集合)`;脚注取元过渡保留 |
|
||
| 2026-09-24 | Artifact Metadata Binding(`${…}` Phase 1,仅 frontmatter):见 [binding.md](binding.md) · ADR 0006 |
|