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>
222 lines
6.1 KiB
Markdown
222 lines
6.1 KiB
Markdown
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) |
|
||
| 日期 | 2026-08-04 |
|
||
| 取代 | v0 中「`**`=输出、`*`=返回」 |
|
||
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
|
||
|
||
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](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](call-arguments.md)) |
|
||
| frontmatter `> path.mq.md` | 跨文件导入 |
|
||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||
| `**…**` | **返回值**(架构级;函数结果) |
|
||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||
| 无标记行 / 成段续行 | 注释(空行分段,见 §2) |
|
||
| GFM 表格 | 集合 |
|
||
| 空 RHS 赋值 + 后随 `$$…$$`(或同行 `$$…$$`) | **公式赋值** → 运行时 `formula`(见 [stdlib-math.md](stdlib-math.md));叙述面无名 `$$` 仅展示 |
|
||
| ` ```lang ` | 外联异种代码 |
|
||
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
|
||
|
||
### 输出不是架构
|
||
|
||
| 错误(旧) | 正确(v0.1) |
|
||
|------------|--------------|
|
||
| `**Hello**` 表示打印 | `> print text=Hello` |
|
||
| 中文名 `输出`(已废弃) | 统一英文内置 `print` |
|
||
| 输出与返回抢粗体 | 粗体只表示 **返回** |
|
||
|
||
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
|
||
|
||
---
|
||
|
||
## 4. 语句、返回、调用
|
||
|
||
### 程序语句(斜体)
|
||
|
||
```markdown
|
||
*`x` = 1*
|
||
|
||
*`y` = `x` + 2*
|
||
```
|
||
|
||
行首已是结构标记的构造(`#` `>` `+` `-` `|`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||
|
||
### 返回值(粗体)
|
||
|
||
```markdown
|
||
# 加一
|
||
- n
|
||
|
||
**`n` + 1**
|
||
```
|
||
|
||
### 输出(内置函数 `print`)
|
||
|
||
```markdown
|
||
# main
|
||
|
||
> print text=Hello World!
|
||
```
|
||
|
||
### else 与斜体消歧
|
||
|
||
- 分支臂**第一行整行只有一个** `*` → else。
|
||
- `*中间有内容*` → 程序语句。
|
||
- `**…**` → 返回(与 else 无关)。
|
||
|
||
---
|
||
|
||
## 5. Frontmatter 与跨文件
|
||
|
||
同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。
|
||
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
|
||
|
||
---
|
||
|
||
## 6. 函数、作用域、提升
|
||
|
||
规则同 v0。推荐:
|
||
|
||
```markdown
|
||
# main
|
||
|
||
> print text=Hello World!
|
||
|
||
## 加问候
|
||
- 谁
|
||
|
||
**你好,`谁`**
|
||
```
|
||
|
||
(需要打印时对返回值再 `> print`,或直接 `> print`。)
|
||
|
||
形参 `- 名` → 体内 `` `名` ``。
|
||
|
||
---
|
||
|
||
## 7. 绑定与比较
|
||
|
||
| 写法 | 含义 |
|
||
|------|------|
|
||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定(两种均允许;实现应统一) |
|
||
| `` `x` == 1 `` | 相等比较 |
|
||
|
||
v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致;行首 `` ` `` 仍合法以便表格右值绑定。
|
||
|
||
---
|
||
|
||
## 8. 分支与循环
|
||
|
||
分支(`+` / 有序),循环(`-`),语义同 v0。臂体内打印改为调用 `print`:
|
||
|
||
```markdown
|
||
*`x` = 0*
|
||
|
||
+ `x` > 0
|
||
> print text=正数
|
||
+ `x` < 0
|
||
> print text=负数
|
||
+ *
|
||
> print text=零
|
||
```
|
||
|
||
```markdown
|
||
- [果](篮子)
|
||
> print text=今天吃`果`
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 集合(表格)
|
||
|
||
同 v0。`` `篮子` = `` 后接 GFM 表。
|
||
|
||
---
|
||
|
||
## 10. 求值入口
|
||
|
||
1. 加载 `index.mq.md` + 导入。
|
||
2. Pass1 收集定义。
|
||
3. Pass2 执行 `# main`。
|
||
4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。
|
||
|
||
---
|
||
|
||
## 11. 函数体结束(`---` / `***` / 空返回)
|
||
|
||
无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数:
|
||
|
||
```markdown
|
||
# main
|
||
|
||
> 问候 谁=World
|
||
|
||
## 问候
|
||
- 谁
|
||
|
||
> print text=Hello `谁`!
|
||
|
||
---
|
||
```
|
||
|
||
| 约定 | 说明 |
|
||
|------|------|
|
||
| `---` 或 `***` | 函数体**顶层**单独一行(长度 ≥ 3 且全为 `-` 或全为 `*`)→ **结束本函数**;后续语句属于外层 |
|
||
| `****` / 空粗体 | 空返回(值为 `None`),并同样结束本函数体 |
|
||
| 有值 `**expr**` | 普通返回;**不**自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) |
|
||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息;与函数体内结束符消歧 |
|
||
| 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 |
|
||
|
||
曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。
|
||
|
||
---
|
||
|
||
## 12. v0.1 非目标
|
||
|
||
- break/continue、完整错误模型、静态类型、完整 FFI
|
||
- 用 `*` 作无序列表符
|
||
|
||
---
|
||
|
||
## 13. 示例索引
|
||
|
||
见 [`tests/`](../../tests/)。
|