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>
6.1 KiB
6.1 KiB
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. 哲学
.mq.md:打开即文档,运行即程序。- 叙述注释以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
- 可执行靠标记:结构标记(
#>+-表…)与 斜体语句 / 粗体返回。 - 作用域 =
#层数;入口 =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. 求值入口
- 加载
index.mq.md+ 导入。 - Pass1 收集定义。
- Pass2 执行
# main。 *语句、**返回、>调用、+/-控制流、表绑定按语义执行;> print写 stdout。
11. 函数体结束(--- / *** / 空返回)
无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数:
# main
> 问候 谁=World
## 问候
- 谁
> print text=Hello `谁`!
---
| 约定 | 说明 |
|---|---|
--- 或 *** |
函数体顶层单独一行(长度 ≥ 3 且全为 - 或全为 *)→ 结束本函数;后续语句属于外层 |
**** / 空粗体 |
空返回(值为 None),并同样结束本函数体 |
有值 **expr** |
普通返回;不自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) |
| Frontmatter | 仅文件开头成对 --- = 元信息;与函数体内结束符消歧 |
| 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 |
曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。
12. v0.1 非目标
- break/continue、完整错误模型、静态类型、完整 FFI
- 用
*作无序列表符
13. 示例索引
见 tests/。