Files
marqdo/doc/design/markdown-mapping.md
T
cflmyandCursor a23fdedfa2 Implement table semantic T0-T4: map/records/footnote get
- 1-col table stays a List; >=2-col becomes a column-oriented Map
  (1 data row -> scalar values, >=2 -> Map of Lists).
- First header @ / 行 / row opts into row-oriented List of Maps
  (marker column excluded); missing field cols is a diagnostic.
- Footnote index: `xs`[^1] (1-based list), `m`[^key] (map key), chained.
  Errors for [^0], out-of-range, missing key, duplicate headers.
- foreach walks list items or map keys; Map values now display as {k: v}.
- Sync both tree and bytecode backends; new gold + error fixtures, docs
  (markdown-mapping, roadmap, skill, public), and public 07/08 pages.
- Fix subtask-spawn fixture return value to child_ok (child-ok parses as
  subtraction).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-10 09:50:21 +08:00

9.8 KiB
Raw Blame History

Marqdo 语法映射 v0.2(Markup-as-Syntax)

状态 已定论(修订:形参 +、分支 1.、同级再 1. 为新分支、标识符反引号、- 专用于循环)
日期 2026-08-07
取代 v0.1 中「函数头 - 形参 / 裸名形参与遍历变量 / + 分支」
相关 objects.md · code-vs-comment.md · return-hr-and-code-surface.md · module-namespace.md

Markdown 标记即语法。输出不是语言架构原语,而是内置函数 print(英文;见 keywords.md)。


1. 哲学

  1. .mq.md:打开即文档,运行即程序。
  2. 叙述注释以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
  3. 可执行靠标记:结构标记(# > + - 1. 表…)与 斜体语句 / 粗体返回。
  4. # = 对象/类型,##+ = 函数/方法(嵌套按标题深度);入口优先 # main(见 objects.md)。函数体可用 --- / *** 或空返回收束(见 §11)。
  5. 标识符一律反引号:凡表示变量槽位(形参、绑定、引用、遍历项、集合名)均写作 `名`,与 Markdown 无序列表/链接脱钩。

2. 行首判别与成段注释

跳过前导空白后,对段首行(空行之后的第一行,或文件起始):

首字符 分类
普通文字 / 空 注释
标记字符 代码

标记含:# * > + - ` |、有序数字 1.、围栏 `、以及函数体内的结束分割线 --- / ***(见 §11)。

成段注释(空行分段):段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 ` / - / * 等开头也不升级为代码。叙述与可执行代码之间必须空一行。例外:单独一行的 --- / *** / ****(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。


3. 映射总表(v0.2)

标记 语义
# … ###### # = 对象/类型;##+ = 函数/方法(层差=嵌套)。见 objects.md
函数头下 + `` 名`` 形参 / 构造参数(可选 `名`=默认值)
体内 1. 2. … 分支(有序列表臂;条件行或 else)
体内 - 循环(while 条件,或 [`项`](`集合`) 遍历)
分支臂头整行恰为 *(在 N. 后) else,如 2. *
> 函数 形参=实参 或 > 函数 实参 调用(具名 / 位置,见 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);叙述面无名 $$ 仅展示
```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。


4. 语句、返回、调用

程序语句(斜体)

*`x` = 1*

*`y` = `x` + 2*

行首已是结构标记的构造(# > + - |、1.)不必再包一层斜体;斜体用于「一般语句」槽位。

返回值(粗体)

## 加一
    + `n`

**`n` + 1**

输出(内置函数 print)

# 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。

函数体内的 --- / *** 不解释为 frontmatter(见 §11)。


6. 对象、函数、形参

  • # Name:对象(构造体);# main 为入口对象。
  • ## / ### …:函数或方法;挂在对象下则为方法。
  • 标准库顶层 API 使用自由函数 ## name(见 objects.md)。
# main

> print text=Hello World!

## 加问候
    + `谁`

**你好,`谁`**

可选形参:

## 问候
    + `谁`
    + `礼貌`=False

方法体内自动绑定 `自` / `self`。


7. 绑定、比较与字符串

写法 含义
*x = 1* 或行首 `x` = 1 绑定
`x` == 1 相等比较
"text" 双引号字符串(复杂文本;见下)
hello / 路径 裸 token(无转义,按字面量)

双引号字符串(复杂文本)

需要转义或嵌入变量时用 "...";裸 token 不转义,保持文档简洁:

> input prompt="你叫什么名字\n"
*`msg` = "Hello, `name`!\n"*
转义 含义
\n 换行
\t 制表
\r 回车
\\ \
\" "

引号内仍可用 `变量` 插值。字面反斜杠+n 写 \\n(裸 token \\n 则就是两个字符)。


8. 分支与循环

分支(有序列表 1. 2. …),循环(-):

*`x` = 0*

1. `x` > 0
  > print text=正数
2. `x` < 0
  > print text=负数
3. *
  > print text=零
*`bool_value` = True*

1. `bool_value` == True
  > print text=True
2. *
  > print text=False

一条分支语句 = 从 1. 起、序号递增的一段有序列表。 同级缩进上再次出现 1.(无论中间有无空行)开启下一条独立分支语句,不得并入上一段的臂列表:

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.。

- [`果`](`篮子`)
  > print text=今天吃`果`

while:

- `n` > 0
  > print text=`n`
  *`n` = `n` - 1*

9. 集合(表格)

`名` = 后接 GFM 表;几何决定值类型(详见 tables-maps-footnotes.md):

形状 值
1 列(竖表) List(表头 = foreach 元素名,不进入元素)
≥2 列 + 1 行数据(横表) Map:键 = 表头,值 = 该列标量
≥2 列 + ≥2 行数据 Map:键 = 表头,值 = 该列 List(列向)
≥2 列 + 0 行数据 Map:键存在,值为空列表
首列表头 @ / 行 / row 行向 List of Map(标记列不进入字段;任意数据行数)
重复表头 诊断错误

行向示例:

`订单` =

| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |

*`名` = `订单`[^1][^品名] *

脚注取元(表达式级,1-based 列表下标 / 字典键;可链式):

*`第一` = `篮子`[^1] *
*`种` = `分类`[^苹果] *
*`第一种苹果` = `货架`[^苹果][^1] *
  • 文末 [^1]: … 定义块仍是注释,与取元无关。
  • [^0]、越界、缺键 → 报错。
  • foreach:List 遍历元素;Map 遍历键(值用脚注取)。

10. 求值入口

  1. 加载 index.mq.md + 导入。
  2. Pass1 收集定义。
  3. Pass2 执行 # main。
  4. * 语句、** 返回、> 调用、1. 分支、- 循环、表绑定按语义执行;> print 写 stdout。

11. 函数体结束(--- / *** / 空返回)

# main

> 问候 谁=World

## 问候
    + `谁`

> print text=Hello `谁`!

---
约定 说明
--- 或 *** 函数体顶层单独一行 → 结束本函数
**** / 空粗体 空返回(None),并结束本函数体
Frontmatter 仅文件开头成对 --- = 元信息

12. v0.2 非目标

  • break/continue、完整错误模型、静态类型、完整 FFI
  • + 作分支、+/- 作形参(不保留)

13. 示例索引

见 tests/。