Files
marqdo/doc/design/markdown-mapping.md
cflmyandCursor dcd0cdb8f7 Add math stdlib with formulas/plots and polish the docs view.
Ship Num/Formula runtime, bilingual math libs, SVG plots with axes/grid, and view UX for collapsible folders plus centered plots.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 11:30:47 +08:00

6.1 KiB
Raw Permalink Blame History

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

状态 已定论(修订:语句 / 返回 / 输出职责分离)
日期 2026-08-04
取代 v0 中「**=输出、*=返回」
相关 code-vs-comment.md · return-hr-and-code-surface.md

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


1. 哲学

  1. .mq.md:打开即文档,运行即程序。
  2. 叙述注释以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
  3. 可执行靠标记:结构标记(# > + - 表…)与 斜体语句 / 粗体返回。
  4. 作用域 = # 层数;入口 = index.mq.md。函数体可用 --- / *** 或空返回收束(见 §11)。

2. 行首判别与成段注释

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

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

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

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


3. 映射总表(v0.1)

标记 语义
# … ###### 函数;层数 = 作用域
函数头下 - 纯名 形参
体内 - 循环
体内 + 或 1. 分支
分支臂头整行恰为 * else
> 函数 形参=实参 或 > 函数 实参 调用(具名 / 位置,见 call-arguments.md)
frontmatter > path.mq.md 跨文件导入
*…* 程序语句(绑定、表达式句、可写的调用句等)
**…** 返回值(架构级;函数结果)
**** / ** + 空白 + ** 空返回(None),并结束本函数体
无标记行 / 成段续行 注释(空行分段,见 §2)
GFM 表格 集合
空 RHS 赋值 + 后随 $$…$$(或同行 $$…$$) 公式赋值 → 运行时 formula(见 stdlib-math.md);叙述面无名 $$ 仅展示
```lang 外联异种代码
函数体内 --- / *** 结束本函数体(无返回值函数的收束;见 §11)

输出不是架构

错误(旧) 正确(v0.1)
**Hello** 表示打印 > print text=Hello
中文名 输出(已废弃) 统一英文内置 print
输出与返回抢粗体 粗体只表示 返回

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


4. 语句、返回、调用

程序语句(斜体)

*`x` = 1*

*`y` = `x` + 2*

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

返回值(粗体)

# 加一
    - n

**`n` + 1**

输出(内置函数 print)

# main

> print text=Hello World!

else 与斜体消歧

  • 分支臂第一行整行只有一个 * → else。
  • *中间有内容* → 程序语句。
  • **…** → 返回(与 else 无关)。

5. Frontmatter 与跨文件

同 v0:文件头 --- 对为元信息;其中 > file.mq.md 为导入。
函数体内的 --- / *** 不解释为 frontmatter(见 §11)。


6. 函数、作用域、提升

规则同 v0。推荐:

# main

> print text=Hello World!

## 加问候
    - 谁

**你好,`谁`**

(需要打印时对返回值再 > print,或直接 > print。)

形参 - 名 → 体内 `名`。


7. 绑定与比较

写法 含义
*x = 1* 或行首 `x` = 1 绑定(两种均允许;实现应统一)
`x` == 1 相等比较

v0.1 推荐绑定写在斜体语句内,以保持「语句=斜体」一致;行首 ` 仍合法以便表格右值绑定。


8. 分支与循环

分支(+ / 有序),循环(-),语义同 v0。臂体内打印改为调用 print:

*`x` = 0*

+ `x` > 0
  > print text=正数
+ `x` < 0
  > print text=负数
+ *
  > print text=零
- [果](篮子)
  > print text=今天吃`果`

9. 集合(表格)

同 v0。`篮子` = 后接 GFM 表。


10. 求值入口

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

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

无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数:

# main

> 问候 谁=World

## 问候
    - 谁

> print text=Hello `谁`!

---
约定 说明
--- 或 *** 函数体顶层单独一行(长度 ≥ 3 且全为 - 或全为 *)→ 结束本函数;后续语句属于外层
**** / 空粗体 空返回(值为 None),并同样结束本函数体
有值 **expr** 普通返回;不自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束)
Frontmatter 仅文件开头成对 --- = 元信息;与函数体内结束符消歧
分支/循环臂内 分割线仍可忽略(噪声),不截断外层函数

曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。


12. v0.1 非目标

  • break/continue、完整错误模型、静态类型、完整 FFI
  • 用 * 作无序列表符

13. 示例索引

见 tests/。