Widen admin main/table display, ensure marqdo ext add builds/copies the native plugin before mq install, and emit valid @keyframes from style tables. Prefer quoted cells like "16/9" for CSS values that contain /. Co-authored-by: Cursor <cursoragent@cursor.com>
356 lines
12 KiB
Markdown
356 lines
12 KiB
Markdown
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、同级再 `1.` 为新分支、标识符反引号、`-` 专用于循环) |
|
||
| 日期 | 2026-08-07 |
|
||
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
|
||
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [module-namespace.md](module-namespace.md) |
|
||
|
||
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
|
||
|
||
---
|
||
|
||
## 1. 哲学
|
||
|
||
1. `.mq.md`:打开即文档,运行即程序。
|
||
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
|
||
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||
5. **标识符默认反引号**:形参、绑定、引用写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
|
||
**豁免:**
|
||
- foreach 头 `` - [项](集合) `` 允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用 `` `名` ``。
|
||
- 脚注取元 `` 名[^键] ``:基名在紧跟 `` [^…] `` 时可省略反引号(`` `名`[^键] `` 仍合法);链式同理。
|
||
- **斜体语句 / 粗体返回内部**:裸标识符默认是**变量**(含调用实参与方法接收者);文本字面量须 `"…"` 或 `'…'` 或引号实参(`key="文本"`);`` `名` `` 仍合法。这是 **Python 统一命名空间**:裸点号 `a.b` 在 `a` 为局部变量时为方法调用,否则为库路径。
|
||
|
||
---
|
||
|
||
## 2. 行首判别与成段注释
|
||
|
||
跳过前导空白后,对**段首行**(空行之后的第一行,或文件起始):
|
||
|
||
| 首字符 | 分类 |
|
||
|--------|------|
|
||
| 普通文字 / 空 | **注释** |
|
||
| 标记字符 | **代码** |
|
||
|
||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
|
||
|
||
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
|
||
|
||
---
|
||
|
||
## 3. 映射总表(v0.2)
|
||
|
||
| 标记 | 语义 |
|
||
|------|------|
|
||
| `#` … `######` | **`#` = 对象/类型**(可 `# Child = > Parent`);**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
|
||
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
|
||
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
|
||
| 体内 `-` | **循环**(`while` 条件,或 `[项](集合)` / `` [`项`](`集合`) `` 遍历) |
|
||
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
|
||
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](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](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](keywords.md)。
|
||
|
||
---
|
||
|
||
## 4. 语句、返回、调用
|
||
|
||
### 程序语句(斜体)
|
||
|
||
```markdown
|
||
*x = 1*
|
||
*y = x + 2*
|
||
*answer = ev[^message]*
|
||
*亦可用 = 1*
|
||
```
|
||
|
||
斜体内部:裸标识符 = 变量;字符串写 `"…"` / `'…'`。行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||
|
||
### 返回值(粗体)
|
||
|
||
```markdown
|
||
## 加一
|
||
+ `n`
|
||
|
||
**n + 1**
|
||
**"ok"**
|
||
**`n` + 1**
|
||
```
|
||
|
||
粗体内部与斜体相同的值语法(裸词 = 变量;文本须引号)。
|
||
|
||
### 输出(内置函数 `print`)
|
||
|
||
```markdown
|
||
# main
|
||
|
||
> print text=Hello World!
|
||
```
|
||
|
||
### else 与斜体消歧
|
||
|
||
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
|
||
- `*中间有内容*` → 程序语句。
|
||
- `**…**` → 返回(与 else 无关)。
|
||
|
||
---
|
||
|
||
## 5. Frontmatter 与跨文件
|
||
|
||
文件头 `---` 对为元信息。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
|
||
|
||
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
|
||
|
||
---
|
||
|
||
## 6. 对象、函数、形参
|
||
|
||
- `# Name`:对象(构造体);`# main` 为入口对象。
|
||
- `# Child = > Parent`:单继承(基类须为已定义对象名;方法沿链查找,子类可覆盖)。见 [objects.md](objects.md) §5。
|
||
- `##` / `###` …:函数或方法;挂在对象下则为方法。
|
||
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
|
||
|
||
```markdown
|
||
# main
|
||
|
||
> print text=Hello World!
|
||
|
||
## 加问候
|
||
+ `谁`
|
||
|
||
**你好,`谁`**
|
||
```
|
||
|
||
可选形参:
|
||
|
||
```markdown
|
||
## 问候
|
||
+ `谁`
|
||
+ `礼貌`=False
|
||
```
|
||
|
||
方法体内自动绑定 `` `自` `` / `` `self` ``。
|
||
|
||
---
|
||
|
||
## 7. 绑定、比较与字符串
|
||
|
||
| 写法 | 含义 |
|
||
|------|------|
|
||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定 |
|
||
| `` `x` == 1 `` | 相等比较 |
|
||
| `"text"` | **双引号字符串**(复杂文本;见下) |
|
||
| `hello` / `路径` | **裸 token**(无转义,按字面量) |
|
||
|
||
### 双引号字符串(复杂文本)
|
||
|
||
需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁:
|
||
|
||
```markdown
|
||
> input prompt="你叫什么名字\n"
|
||
*`msg` = "Hello, `name`!\n"*
|
||
```
|
||
|
||
| 转义 | 含义 |
|
||
|------|------|
|
||
| `\n` | 换行 |
|
||
| `\t` | 制表 |
|
||
| `\r` | 回车 |
|
||
| `\\` | `\` |
|
||
| `\"` | `"` |
|
||
| `\'` | `'` |
|
||
| `\xHH` | 十六进制字符(如 `\x22` → `"`) |
|
||
| `\u{...}` | Unicode 码点(如 `\u{4e2d}` → `中`) |
|
||
|
||
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。未知转义(如 `\q`)按字面保留,不报错。
|
||
|
||
---
|
||
|
||
## 8. 分支与循环
|
||
|
||
分支(**有序列表** `1.` `2.` …),循环(`-`):
|
||
|
||
```markdown
|
||
*`x` = 0*
|
||
|
||
1. `x` > 0
|
||
> print text=正数
|
||
2. `x` < 0
|
||
> print text=负数
|
||
3. *
|
||
> print text=零
|
||
```
|
||
|
||
```markdown
|
||
*`bool_value` = True*
|
||
|
||
1. `bool_value` == True
|
||
> print text=True
|
||
2. *
|
||
> print text=False
|
||
```
|
||
|
||
**一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`**(无论中间有无空行)开启**下一条**独立分支语句,不得并入上一段的臂列表:
|
||
|
||
```markdown
|
||
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.`。
|
||
|
||
```markdown
|
||
- [果](篮子)
|
||
> print text=今天吃`果`
|
||
```
|
||
|
||
反引号形式等价:`` - [`果`](`篮子`) ``。两侧可混用。
|
||
|
||
`while`:
|
||
|
||
```markdown
|
||
- `n` > 0
|
||
> print text=`n`
|
||
*`n` = `n` - 1*
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 集合(表格)
|
||
|
||
`` `名` = `` 后接 GFM 表;几何决定值类型(详见 [tables-maps-footnotes.md](../roadmap/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](table-cell-expressions.md)。
|
||
|
||
```markdown
|
||
*`k` = secret *
|
||
|
||
`cfg` =
|
||
|
||
| api_key | model |
|
||
|---------|-------|
|
||
| `k` | gpt-4o-mini |
|
||
```
|
||
|
||
行向示例:
|
||
|
||
```markdown
|
||
`订单` =
|
||
|
||
| 行 | 品名 | 数量 |
|
||
|----|------|------|
|
||
| 1 | 苹果 | 2 |
|
||
| 2 | 梨 | 3 |
|
||
|
||
*`名` = `订单`[^1][^品名] *
|
||
```
|
||
|
||
**脚注取元**(表达式级;可链式):
|
||
|
||
```markdown
|
||
*`第一` = 篮子[^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. 函数体结束(`---` / `***` / 空返回)
|
||
|
||
```markdown
|
||
# main
|
||
|
||
> 问候 谁=World
|
||
|
||
## 问候
|
||
+ `谁`
|
||
|
||
> print text=Hello `谁`!
|
||
|
||
---
|
||
```
|
||
|
||
| 约定 | 说明 |
|
||
|------|------|
|
||
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
|
||
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
|
||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
|
||
|
||
---
|
||
|
||
## 12. v0.2 非目标
|
||
|
||
- break/continue、完整错误模型、静态类型、完整 FFI
|
||
- `+` 作分支、`+`/`-` 作形参(**不保留**)
|
||
|
||
---
|
||
|
||
## 13. 示例索引
|
||
|
||
见 [`tests/`](../../tests/)。
|