Files
marqdo/doc/design/markdown-mapping.md
T
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

13 KiB
Executable File
Raw Blame History

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

状态 历史文档(v0.2 · 已废止为运行时) — 现行见 markdown-mapping-v0.3.md
日期 2026-08-07
取代 v0.1 中「函数头 - 形参 / 裸名形参与遍历变量 / + 分支」
被取代 markdown-mapping-v0.3.md(粗体即代码 · 斜体即返回 · 无双模式兼容)
相关 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 无序列表/链接脱钩。
    豁免:
    • foreach 头 - [项](集合) 允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用 `名`。
    • 脚注取元 名[^键]:基名在紧跟 [^…] 时可省略反引号(`名`[^键] 仍合法);链式同理。
    • 斜体语句 / 粗体返回内部:裸标识符默认是变量(含调用实参与方法接收者);文本字面量须 "…" 或 '…' 或引号实参(key="文本");`名` 仍合法。这是 Python 统一命名空间:裸点号 a.b 在 a 为局部变量时为方法调用,否则为库路径。

2. 行首判别与成段注释

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

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

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

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


3. 映射总表(v0.2)

标记 语义
# … ###### # = 对象/类型(可 # Child = > Parent);##+ = 函数/方法(层差=嵌套)。见 objects.md
函数头下 + `` 名`` 形参 / 构造参数(可选 `名`=默认值)
体内 1. 2. … 分支(有序列表臂;条件行或 else)
体内 - 循环(while 条件,或 [项](集合) / [`项`](`集合`) 遍历)
分支臂头整行恰为 *(在 N. 后) else,如 2. *
> 函数 形参=实参 或 > 函数 实参 调用(具名 / 位置,见 call-arguments.md)
> `对象`.方法 … 方法调用(独立 >;实例 map 须含 _type)。*…* 段内接收者裸名:*x = > 对象.方法 …*
frontmatter import bind:path.mq.md / 导入 导入文件并绑定库名
frontmatter import bind:lib.member / 导入 将库路径成员绑为本地短名(与文件导入同形)
> 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
- 谁 作形参 + `谁`
[果](篮子) 裸名遍历 仍合法(foreach 豁免);亦可用 [`果`](`篮子`)

print / input 为内置函数,完整表见 keywords.md。


4. 语句、返回、调用

程序语句(斜体)

*x = 1*
*y = x + 2*
*answer = ev[^message]*
*亦可用 = 1*

斜体内部:裸标识符 = 变量;字符串写 "…" / '…'。行首已是结构标记的构造(# > + - |、1.)不必再包一层斜体;斜体用于「一般语句」槽位。

返回值(粗体)

## 加一
    + `n`

**n + 1**
**"ok"**
**`n` + 1**

粗体内部与斜体相同的值语法(裸词 = 变量;文本须引号)。

输出(内置函数 print)

# main

> print text=Hello World!

else 与斜体消歧

  • 分支臂有序行 N. *(或 N. 后仅 *)→ else。
  • *中间有内容* → 程序语句。
  • **…** → 返回(与 else 无关)。

5. Frontmatter 与跨文件

文件头 --- 对为 Artifact Metadata。其中 import bind:path.mq.md / 导入 为文件导入;import bind:lib.member 为短名(废除独立 use 与 frontmatter > 导入)。其它 key: value 可为字面量或 Binding(${env.NAME} 等,加载期解析);见 binding.md。调用经裸点号路径(time.parse、agent.agent);实例方法在独立 > 调用须 > `var`.method(*…* 段内接收者裸名)。详见 module-namespace.md。

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


6. 对象、函数、形参

  • # Name:对象(构造体);# main 为入口对象。
  • # Child = > Parent:单继承(基类须为已定义对象名;方法沿链查找,子类可覆盖)。见 objects.md §5。
  • ## / ### …:函数或方法;挂在对象下则为方法。
  • 标准库顶层 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 回车
\\ \
\" "
\' '
\xHH 十六进制字符(如 \x22 → ")
\u{...} Unicode 码点(如 \u{4e2d} → 中)

引号内仍可用 `变量` 插值。字面反斜杠+n 写 \\n(裸 token \\n 则就是两个字符)。未知转义(如 \q)按字面保留,不报错。


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(标记列不进入字段;任意数据行数)
重复表头 诊断错误

数据单元格是表达式(与调用实参值语法相同:裸词、数字、`var`、算术、引号串;URL / gpt-4o-mini 等按路径·连字符折叠为文本;含 / 的 CSS 比率等请用引号 "1/5",裸 1/5 为除法)。表头仍是键名文本。细则:table-cell-expressions.md。

*`k` = secret *

`cfg` =

| api_key | model |
|---------|-------|
| `k` | gpt-4o-mini |

行向示例:

`订单` =

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

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

脚注取元(表达式级;可链式):

*`第一` = 篮子[^1] *              # 基名可省略反引号(`[^` 已标明取元)
*`种` = 分类[^苹果] *
*`第一种苹果` = 货架[^苹果][^1] *
*`亦可用` = `分类`[^苹果] *       # 反引号形式并存
  • List:标签须为纯数字(1-based);[^0] / 越界 → 报错。
  • Map:标签为键文本(含 "00" 这类数字串键);缺键 → 报错。同一外形按接收值类型分派,不把 map 上的 [^1] 当成「第 1 个条目」。
  • 基名:`名`[^键] 与 名[^键] 等价;无 [^ 时裸词仍是文本字面量(不是变量)。
  • 插值中的取元:在调用实参值 / 引号字符串里,`变量` 后紧跟(无空白)[^…] 时按取元解析,而不是字面文本:> print text=苹果单价:水果价格[^苹果];链式 `货架`[^苹果][^1] 同理。`变量` [^…](有空白)则 [^…] 仍是文本。
  • 文末 [^1]: … 定义块仍是注释,与取元无关。
  • 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/。