- 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。
13 KiB
Executable File
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. 哲学
.mq.md:打开即文档,运行即程序。- 叙述注释以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
- 可执行靠标记:结构标记(
#>+-1.表…)与 斜体语句 / 粗体返回。 #= 对象/类型,##+ = 函数/方法(嵌套按标题深度);入口优先# main(见 objects.md)。函数体可用---/***或空返回收束(见 §11)。- 标识符默认反引号:形参、绑定、引用写作
`名`,与 Markdown 无序列表/链接脱钩。
豁免:- foreach 头
- [项](集合)允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用`名`。 - 脚注取元
名[^键]:基名在紧跟[^…]时可省略反引号(`名`[^键]仍合法);链式同理。 - 斜体语句 / 粗体返回内部:裸标识符默认是变量(含调用实参与方法接收者);文本字面量须
"…"或'…'或引号实参(key="文本");`名`仍合法。这是 Python 统一命名空间:裸点号a.b在a为局部变量时为方法调用,否则为库路径。
- foreach 头
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. 求值入口
- 加载
index.mq.md+ 导入。 - Pass1 收集定义。
- Pass2 执行
# main。 *语句、**返回、>调用、1.分支、-循环、表绑定按语义执行;> print写 stdout。
11. 函数体结束(--- / *** / 空返回)
# main
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello `谁`!
---
| 约定 | 说明 |
|---|---|
--- 或 *** |
函数体顶层单独一行 → 结束本函数 |
**** / 空粗体 |
空返回(None),并结束本函数体 |
| Frontmatter | 仅文件开头成对 --- = 元信息 |
12. v0.2 非目标
- break/continue、完整错误模型、静态类型、完整 FFI
+作分支、+/-作形参(不保留)
13. 示例索引
见 tests/。