Files
marqdo/doc/design/markdown-mapping.md
T
cflmyandCursor 5456d9ff83 Implement object inheritance: # Child = > Parent (I0-I2)
- Parse `# Child = > Parent` object decls (base must be a simple
  name after `>`; dotted bases and `# Foo = 1` are diagnostics).
- Validate in load: unknown base types and cyclic inheritance (A → B → A)
  fail with line/col.
- Method resolution walks the base chain (most specific first) on both
  tree and bytecode backends; `_type` stays the child name; same-name
  child ## overrides the parent.
- Add inherit.rs, wire Program.object_bases, gold fixtures
  (inherit-parent-method / inherit-override + cycle/unknown-base/bad-rhs)
  and public 09-inherit demo pages. Docs: objects.md, markdown-mapping,
  roadmap, skill.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-10 10:01:05 +08:00

326 lines
9.9 KiB
Markdown
Raw 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.
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
| | |
|---|---|
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、同级再 `1.` 为新分支、标识符反引号、`-` 专用于循环) |
| 日期 | 2026-08-07 |
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [module-namespace.md](module-namespace.md) |
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
---
## 1. 哲学
1. `.mq.md`:打开即文档,运行即程序。
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
5. **标识符一律反引号**:凡表示变量槽位(形参、绑定、引用、遍历项、集合名)均写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
---
## 2. 行首判别与成段注释
跳过前导空白后,对**段首行**(空行之后的第一行,或文件起始):
| 首字符 | 分类 |
|--------|------|
| 普通文字 / 空 | **注释** |
| 标记字符 | **代码** |
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
---
## 3. 映射总表(v0.2)
| 标记 | 语义 |
|------|------|
| `#` … `######` | **`#` = 对象/类型**(可 `# Child = > Parent`);**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
| 体内 `-` | **循环**(`while` 条件,或 `` [`项`](`集合`) `` 遍历) |
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
| `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) |
| frontmatter `> path.mq.md` [`as` / `作为` name] | 导入(绑定库名;默认 = 文件名茎) |
| frontmatter `> use lib.member` [`as` name] / `使用` | 将库路径成员绑为本地短名 |
| `> lib.member …` / `> lib.Type.member …` | 点号路径调用(路径段裸名、无反引号) |
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
| `**…**` | **返回值**(架构级;函数结果) |
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
| 无标记行 / 成段续行 | 注释(空行分段,见 §2) |
| GFM 表格 | 集合 |
| 空 RHS 赋值 + 后随 `$$…$$`(或同行 `$$…$$`) | **公式赋值** → 运行时 `formula`(见 [stdlib-math.md](stdlib-math.md));叙述面无名 `$$` 仅展示 |
| ` ```lang ` | 外联异种代码 |
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
### `+` / `-` / `1.` 消歧
| 位置 | `+` | `1.` … | `-` |
|------|-----|--------|-----|
| 函数标题后、**首条体语句前** | 形参:`` + `名` `` / `` + `名`=默认 `` | (非法) | (非法作形参) |
| 函数体内 | (非法作分支) | 分支臂:`1. `条件`` / `2. *` | 循环 |
**分支从未使用 `+`。** 自 v0 起即采用 GFM 有序列表;`+` 在 v0.2 专用于形参,与 `-` 循环彻底分离。
### 输出不是架构
| 错误(旧) | 正确(v0.2) |
|------------|--------------|
| `**Hello**` 表示打印 | `> print text=Hello` |
| `+ `x` > 0` 作分支 | `1. `x` > 0` |
| `- 谁` 作形参 | `` + `谁` `` |
| `[果](篮子)` 裸名遍历 | `` [`果`](`篮子`) `` |
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
---
## 4. 语句、返回、调用
### 程序语句(斜体)
```markdown
*`x` = 1*
*`y` = `x` + 2*
```
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
### 返回值(粗体)
```markdown
## 加一
+ `n`
**`n` + 1**
```
### 输出(内置函数 `print`)
```markdown
# main
> print text=Hello World!
```
### else 与斜体消歧
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
- `*中间有内容*` → 程序语句。
- `**…**` → 返回(与 else 无关)。
---
## 5. Frontmatter 与跨文件
文件头 `---` 对为元信息。其中 `> file.mq.md` 为**导入**(绑定库名,成员不倒进全局);`> use lib.member` / `> 使用 库.成员` 引入本地短名。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法须 `` > `var`.method ``。详见 [module-namespace.md](module-namespace.md)。
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
---
## 6. 对象、函数、形参
- `# Name`:对象(构造体);`# main` 为入口对象。
- `# Child = > Parent`:单继承(基类须为已定义对象名;方法沿链查找,子类可覆盖)。见 [objects.md](objects.md) §5。
- `##` / `###` …:函数或方法;挂在对象下则为方法。
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
```markdown
# main
> print text=Hello World!
## 加问候
+ `谁`
**你好,`谁`**
```
可选形参:
```markdown
## 问候
+ `谁`
+ `礼貌`=False
```
方法体内自动绑定 `` `自` `` / `` `self` ``。
---
## 7. 绑定、比较与字符串
| 写法 | 含义 |
|------|------|
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定 |
| `` `x` == 1 `` | 相等比较 |
| `"text"` | **双引号字符串**(复杂文本;见下) |
| `hello` / `路径` | **裸 token**(无转义,按字面量) |
### 双引号字符串(复杂文本)
需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁:
```markdown
> input prompt="你叫什么名字\n"
*`msg` = "Hello, `name`!\n"*
```
| 转义 | 含义 |
|------|------|
| `\n` | 换行 |
| `\t` | 制表 |
| `\r` | 回车 |
| `\\` | `\` |
| `\"` | `"` |
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。
---
## 8. 分支与循环
分支(**有序列表** `1.` `2.` …),循环(`-`):
```markdown
*`x` = 0*
1. `x` > 0
> print text=正数
2. `x` < 0
> print text=负数
3. *
> print text=零
```
```markdown
*`bool_value` = True*
1. `bool_value` == True
> print text=True
2. *
> print text=False
```
**一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`**(无论中间有无空行)开启**下一条**独立分支语句,不得并入上一段的臂列表:
```markdown
1. `a`
> print text=A
2. *
> print text=not-A
1. `b`
> print text=B
2. *
> print text=not-B
```
上例为两次独立判断(先 `a` 再 `b`),不是「四个臂的一个分支」。臂序号在同一分支内递增(`1.` → `2.` → `3.` …);**不要**在同一分支中途把序号重置为 `1.`。
```markdown
- [`果`](`篮子`)
> print text=今天吃`果`
```
`while`:
```markdown
- `n` > 0
> print text=`n`
*`n` = `n` - 1*
```
---
## 9. 集合(表格)
`` `名` = `` 后接 GFM 表;几何决定值类型(详见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md)):
| 形状 | 值 |
|------|-----|
| **1 列**(竖表) | `List`(表头 = foreach 元素名,不进入元素) |
| **≥2 列 + 1 行数据**(横表) | `Map`:键 = 表头,值 = 该列标量 |
| **≥2 列 + ≥2 行数据** | `Map`:键 = 表头,值 = 该列 `List`(列向) |
| **≥2 列 + 0 行数据** | `Map`:键存在,值为空列表 |
| **首列表头 `@` / `行` / `row`** | **行向** `List` of `Map`(标记列不进入字段;任意数据行数) |
| 重复表头 | 诊断错误 |
行向示例:
```markdown
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |
*`名` = `订单`[^1][^品名] *
```
**脚注取元**(表达式级,1-based 列表下标 / 字典键;可链式):
```markdown
*`第一` = `篮子`[^1] *
*`种` = `分类`[^苹果] *
*`第一种苹果` = `货架`[^苹果][^1] *
```
- 文末 `[^1]: …` 定义块仍是注释,与取元无关。
- `[^0]`、越界、缺键 → 报错。
- foreach:`List` 遍历元素;`Map` 遍历**键**(值用脚注取)。
---
## 10. 求值入口
1. 加载 `index.mq.md` + 导入。
2. Pass1 收集定义。
3. Pass2 执行 `# main`。
4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。
---
## 11. 函数体结束(`---` / `***` / 空返回)
```markdown
# main
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello `谁`!
---
```
| 约定 | 说明 |
|------|------|
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
---
## 12. v0.2 非目标
- break/continue、完整错误模型、静态类型、完整 FFI
- `+` 作分支、`+`/`-` 作形参(**不保留**)
---
## 13. 示例索引
见 [`tests/`](../../tests/)。