Add Marqdo Chinese syntax tutorial under doc/tutorial/

13 chapters plus a README index covering syntax, variables, functions,
control flow, collections, objects/inheritance, modules and the CLI.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-08-24 14:45:26 +08:00
1 parent bd5555afaa
commit d7924ea8c7
14 files changed
+2009

No files matched your search

+88
View File
@@ -0,0 +1,88 @@
# 第 1 章:Marqdo 是什么
## 1.1 一句话介绍
**Marqdo = Markdown(Marq)+ 执行(do)**。它把 Markdown 的**标记当作编程语法**:同一个 `.mq.md` 文件,打开给人看是文档,运行给机器看是程序。
在大型项目里,说明、示例与实现往往分叉成三份「真相」,改一处忘另一处。Marqdo 让这三者**同源**——你写的文档本身就是可执行的代码。
## 1.2 与其他语言的区别
传统编程语言(如 Python)需要单独写文档和注释;Marqdo 反过来了——**文档本身就是程序**。
| 传统语言 | Marqdo |
|----------|--------|
| 代码在 `.py`,文档在 `.md` | 代码与文档同在 `.mq.md` |
| `def` / `if` / `for` / `return` 是关键字 | 用 Markdown 标记 `##` / `1.` / `-` / `**…**` 表达 |
| 注释用 `#` 或 `//` | **无标记的叙述就是注释** |
| 大括号 `{}` 或缩进界定代码块 | 标题层级 `#` / `##` 界定作用域 |
关键点:**不要**试图写 `if`、`else`、`while`、`for`、`def`、`return` 这些关键字——它们不是 Marqdo 的语法。控制流由 Markdown 承担。
## 1.3 安装
Marqdo 用 Rust 编写。从以下任一方式获取:
- **发布包**:从 GitHub Releases 下载预编译二进制(已内置标准库)。
- **源码构建**:
```bash
git clone https://github.com/cflmy/marqdo.git
cd marqdo
cargo build --release
# 二进制位于 target/release/marqdo
```
验证安装:
```bash
marqdo --version
```
## 1.4 第一个程序
创建一个文件 `hello.mq.md`:
```markdown
# Hello World
这是叙述文字,也就是注释。
> print text=Hello World!
```
- `# Hello World` —— 对象标题。`# main` 是入口;当文件只有唯一一个顶层 `#` 对象时,它也可作为入口。
- 空行后的普通文字是**注释**(叙述)。
- `> print text=Hello World!` —— 调用内置函数 `print` 输出一行文本。
运行:
```bash
marqdo run hello.mq.md
```
输出:
```text
Hello World!
```
## 1.5 中英双语内核
Marqdo 内核内置函数都有中英别名,**无需导入,可混用**:
```markdown
# main
> 打印 内容=你好,世界!
```
`打印` 与 `print` 是同一个内置函数,`内容` 与 `text` 是同一个参数名。
## 1.6 文件后缀:`.mq.md`
Marqdo 程序的**后缀必须是 `.mq.md`**(可执行源文件),不能用普通的 `.md`。一个 `.md` 文件默认只是文档;一个 `.mq.md` 文件既是文档又是程序。
## 1.7 下一步
你已经能写出并运行第一个程序了。接下来学习[第 2 章:基本语法](./02-基本语法.md)——理解 `.mq.md` 里哪些是代码、哪些是注释,以及标识符的写法。
+151
View File
@@ -0,0 +1,151 @@
# 第 2 章:基本语法
## 2.1 文件结构
一个 `.mq.md` 文件由以下几部分组成:
1. **Frontmatter**(可选):文件开头的成对 `---` 之间的元信息,如标题、导入。
2. **对象 / 函数定义**:以 `#` / `##` 开头的标题。
3. **叙述注释**:无标记的普通文字段落。
4. **可执行语句**:以标记开头的行。
```markdown
---
title: 我的程序
---
# main
这是叙述段落,整段都是注释。
> print text=Hello
```
## 2.2 代码 vs 注释:空行分段规则
Marqdo 的注释规则很特别:**无标记的叙述就是注释**,靠空行分段。
规则:
- 空行之后的第一行若**无标记**(普通文字)→ 这一段是**注释**。
- 注释段内的**每一行**(直到下一个空行)都是注释——即使它长得像代码。
```markdown
# main
这段注释里有一行看起来像代码,但它不会执行:
*not_executed = 1*
> print text=这也是注释
空行之后,代码开始运行:
> print text=这行会运行
```
> **注意**:叙述与可执行代码之间**必须空一行**。忘记空行会让本意是注释的文字被当作代码,或让代码被吞进注释段。
## 2.3 标记一览表
以下标记表示「这是代码」:
| 标记 | 含义 |
|------|------|
| `#` | 对象 / 类型(`# main` = 入口) |
| `##` … `######` | 函数 / 方法(嵌套按标题深度) |
| `` + `名` `` | 函数标题下的形参 |
| `1.` `2.` … | 条件分支 |
| `-` | 循环(遍历或 while) |
| `> 函数 参数` | 调用 |
| `*…*` | 程序语句(赋值 / 表达式) |
| `**…**` | 返回值 |
| `|` 开头的 GFM 表格 | 集合(列表 / 字典) |
| `---` / `***`(函数体内) | 结束函数体 |
## 2.4 标识符与反引号
Marqdo 中,**变量、参数名用反引号 `` ` `` 包裹**,这与 Markdown 的代码/链接语法脱钩,避免歧义。
```markdown
## 问候
+ `谁`
> print text=Hello, `谁`!
```
- `+ `谁`` —— 声明形参 `谁`
- `> print text=Hello, `谁`!` —— 在字符串中引用变量 `谁`
> **注意**:反引号规则有例外。在 `*…*`(斜体语句)和 `**…**`(粗体返回)内部,**裸标识符就是变量**,反引号可以省略(详见 [第 3 章](./03-变量与赋值.md))。
## 2.5 字面量
Marqdo 的字面量:
| 类型 | 示例 | 说明 |
|------|------|------|
| 数字 | `1` `3.14` `-5` | 整数 / 浮点 / 负数 |
| 布尔 | `True` `False`(`真` `假`) | 布尔值 |
| 空值 | `None`(`空`) | 空值 |
| 文本 | `hello`(裸 token) | 无转义,按字面量 |
| 字符串 | `"Hello\n"` | 双引号,支持转义与变量插值 |
| 列表 | `[1, 2, 3]` | 通过表格构造 |
| 字典 | `{"a": 1}` | 通过表格构造 |
文本 vs 字符串的区别:
- **裸 token**(如 `hello`、`路径`):按字面量,不转义,适合简短文本。
- **双引号字符串**:需要转义(`\n` 等)或嵌入变量时使用。
```markdown
> print text=Hello World! # 裸 token,按字面量
*msg = "Hello, `name`!\n"* # 字符串,可插值、可转义
```
## 2.6 关键字(不可作变量名)
以下单词是 Marqdo 的**保留关键字**,不能用作变量名:
| 英文 | 中文 | 含义 |
|------|------|------|
| `True` | `真` | 布尔真 |
| `False` | `假` | 布尔假 |
| `None` | `空` | 空值 |
| `and` | `且` | 逻辑与 |
| `or` | `或` | 逻辑或 |
| `not` | `非` | 逻辑非 |
**不要**尝试用 `if` / `else` / `while` / `for` / `def` / `return` ——它们不是关键字,也没有意义。
## 2.7 一个完整的例子
把学到的串起来:
```markdown
# main
这是一个完整示例:定义函数、调用、输出。
> 问候 谁=Marqdo
## 问候
+ `谁`
> print text=你好,`谁`!
---
## 加一
+ `n`
**n + 1**
```
运行输出:
```text
你好,Marqdo!
```
## 2.8 下一步
你已经理解 `.mq.md` 的基本结构了。接下来学习[第 3 章:变量与赋值](./03-变量与赋值.md),掌握 Marqdo 的值存储方式。
+116
View File
@@ -0,0 +1,116 @@
# 第 3 章:变量与赋值
## 3.1 什么是变量
变量是给数据起的一个名字。Marqdo 中,变量在**斜体语句 `*…*`** 中通过 `=` 绑定:
```markdown
*x = 1*
*name = "Marqdo"*
*ok = True*
```
> **重要**:在 `*…*` / `**…**` 内部,**裸标识符就是变量**——不需要反引号。这是 Marqdo 的关键约定。
## 3.2 绑定的三种写法
### 写法一:斜体语句 `*…*`(推荐)
```markdown
*x = 1*
*y = x + 2*
```
这是最常用的绑定方式。裸标识符就是变量。
### 写法二:行首反引号绑定(无 `*…*`)
```markdown
`x` = 1
```
不带 `*…*` 的绑定,变量名**需要反引号**。常用于绑定集合(表格)或公式:
```markdown
`篮子` =
| 果 |
|----|
| 苹果 |
```
### 写法三:绑定调用结果
```markdown
*len_s = > len value="hello"*
```
`*…*` 内用 `= >` 表示「把调用结果赋给变量」。
## 3.3 引用变量
在 `*…*` 内部,直接写变量名即可:
```markdown
*a = 5*
*b = a * 2*
> print text=`b` # 独立 > 调用中,变量要反引号
```
> **关键区别**:在**独立 `>` 调用**(如 `> print …`)里,裸词是**文本**,所以引用变量要加反引号:`> print text=`b``。而在 `*…*` / `**…**` 内,裸词是**变量**:`*b = a * 2*`。
## 3.4 字符串与插值
### 双引号字符串
```markdown
*msg = "Hello, World!"*
```
### 转义字符
| 转义 | 含义 |
|------|------|
| `\n` | 换行 |
| `\t` | 制表 |
| `\r` | 回车 |
| `\\` | 反斜杠 `\` |
| `\"` | 双引号 `"` |
### 变量插值
字符串内用 `` `变量` `` 插值:
```markdown
*name = "Marqdo"*
*msg = "Hello, `name`!"*
> print text=`msg` # 输出:Hello, Marqdo!
```
## 3.5 完整示例
```markdown
# main
*name = "Alice"*
*age = 30*
*next_age = age + 1*
> print text=名字:`name`
> print text=明年:`next_age` 岁
*msg = "你好,`name`!你明年 `next_age` 岁。"*
> print text=`msg`
```
输出:
```text
名字:Alice
明年:31 岁
你好,Alice!你明年 31 岁。
```
## 3.6 下一步
你已经会存取数据了。接下来学习[第 4 章:输出与输入](./04-输出与输入.md),与用户交互。
+93
View File
@@ -0,0 +1,93 @@
# 第 4 章:输出与输入
## 4.1 输出:`print` / `打印`
`print`(中文 `打印`)是内置函数,用于向标准输出写一行文本。**输出不是 `**粗体**`**——粗体是返回值,不是打印。
```markdown
# main
> print text=Hello World!
```
中英等价:
```markdown
> 打印 内容=你好,世界!
```
| 英文 | 中文 | 参数 |
|------|------|------|
| `> print text=…` | `> 打印 内容=…` | `text` ≡ `内容` |
### 输出变量
独立 `>` 调用中,变量用反引号:
```markdown
*x = 42*
> print text=`x` # 输出:42
```
### 输出拼接
```markdown
*name = "Marqdo"*
> print text=欢迎使用 `name`!
```
## 4.2 输入:`input` / `输入`
`input`(中文 `输入`)读取一行用户输入:
```markdown
# main
> input prompt=你叫什么名字?
```
| 英文 | 中文 | 参数 |
|------|------|------|
| `> input prompt=…` | `> 输入 提示=…` | `prompt` ≡ `提示` |
### 读取并保存输入
```markdown
# main
*name = > input prompt="请输入名字:"*
> print text=你好,`name`!
```
> `input` 的 `prompt` 参数可省略(缺省)。
## 4.3 完整示例:一个问答程序
```markdown
# main
这是一个人机问答程序。
*name = > input prompt="你叫什么名字?\n"*
> print text=你好,`name`!
*age = > int value=`age_input`*
```
> **注意**:上面的示例为了展示 `int` 用法,`age_input` 尚未定义。实际中你需要先从 `input` 得到字符串,再用 `int` 转换。完整可运行版本:
```markdown
# main
*name = > input prompt="你叫什么名字?\n"*
> print text=你好,`name`!
*age_str = > input prompt="你几岁?\n"*
*age = > int value=`age_str`*
*next_age = age + 1*
> print text=`name`,你明年 `next_age` 岁。
```
## 4.4 下一步
你已经能与用户交互了。接下来学习[第 5 章:运算符与比较](./05-运算符与比较.md)。
+122
View File
@@ -0,0 +1,122 @@
# 第 5 章:运算符与比较
## 5.1 算术运算符
在 `*…*` 表达式内部:
```markdown
*a = 10*
*b = 3*
*sum = a + b* # 13
*diff = a - b* # 7
*prod = a * b* # 30
*quo = a / b* # 3.33…(浮点除法)
```
| 运算符 | 含义 |
|--------|------|
| `+` | 加法 / 拼接 |
| `-` | 减法 |
| `*` | 乘法 |
| `/` | 除法 |
> **注意**:在裸表达式里 `/` 是除法;但在**调用实参 / 参数默认值**中,不空格相连的 `a/b` 会被当作路径文本(详见[第 11 章](./11-模块与导入.md))。
## 5.2 字符串拼接
`+` 也可以拼接字符串:
```markdown
*first = "Hello, "*
*second = "World!"*
*msg = first + second*
> print text=`msg` # Hello, World!
```
> 在 `*…*` 内变量是裸名;若拼接的是字符串字面量,要加引号。
## 5.3 比较运算符
| 运算符 | 含义 |
|--------|------|
| `==` | 相等 |
| `>` | 大于 |
| `<` | 小于 |
| `>=` | 大于等于 |
| `<=` | 小于等于 |
```markdown
*n = 5*
1. `n` > 3
> print text=大于 3
2. *
> print text=小于等于 3
```
## 5.4 逻辑运算符
| 英文 | 中文 | 含义 |
|------|------|------|
| `and` | `且` | 逻辑与 |
| `or` | `或` | 逻辑或 |
| `not` | `非` | 逻辑非 |
```markdown
*age = 20*
*has_id = True*
1. `age` >= 18 and `has_id`
> print text=可以进入
2. *
> print text=不能进入
```
## 5.5 布尔值
布尔值字面量:`True` / `False`(中文 `真` / `假`)。
```markdown
*is_admin = False*
1. `is_admin` == True
> print text=管理员
2. *
> print text=普通用户
```
也可以直接用布尔变量作条件:
```markdown
*flag = True*
1. `flag`
> print text=为真
2. *
> print text=为假
```
## 5.6 完整示例
```markdown
# main
*score = 85*
*passed = score >= 60*
*bonus = passed and score >= 80*
> print text=及格:`passed`
> print text=优秀:`bonus`
```
输出:
```text
及格:True
优秀:True
```
## 5.7 下一步
你已经能计算和判断了。接下来学习[第 6 章:函数](./06-函数.md),把逻辑封装起来复用。
+188
View File
@@ -0,0 +1,188 @@
# 第 6 章:函数
## 6.1 定义函数
在 Marqdo 中,函数用 `##`(及更深)标题定义:
```markdown
## 加一
+ `n`
**n + 1**
```
- `## 加一` —— 函数名
- `+ `n`` —— 参数
- `**n + 1**` —— 返回值(**粗体 = 返回**)
函数可以挂在 `# main` 之下作为嵌套函数,也可以作为顶层自由函数。
## 6.2 调用函数
使用 `>` 调用(具名参数或位置参数):
```markdown
# main
> greet who=World # 具名参数
> greet World # 位置参数
## greet
+ `who`
> print text=Hello, `who`!
---
```
### 具名 vs 位置
```markdown
> 问候 谁=Marqdo # 具名:名=值
> 问候 Marqdo # 位置:按形参顺序
```
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。
> 具名实参的值可以含空格,直到下一个 `名=` 边界;位置实参是单个词法单元(不含空格)。
## 6.3 参数与默认值
可选参数用 `=默认值`:
```markdown
## 问候
+ `谁`
+ `礼貌`=False
1. `礼貌`
> print text=您好,`谁`!
2. *
> print text=嗨,`谁`!
```
调用:
```markdown
> 问候 谁=小明
> 问候 谁=小明 礼貌=True
```
## 6.4 返回值:`**…**`
用 `**…**` 返回表达式结果:
```markdown
## 加一
+ `n`
**n + 1**
```
调用并绑定结果:
```markdown
# main
*b = > 加一 n=1*
> print text=`b` # 2
```
### 返回 None:`****`
`****`(或空粗体 `**` + 空白 + `**`)返回 `None` 并结束函数体:
```markdown
## 静默
+ `x`
****
```
### 字符串返回
```markdown
## 问候语
+ `谁`
**"你好," + 谁 + "!"**
```
## 6.5 结束函数体:`---` / `***`
对于**没有返回值、只有副作用**的函数,用单独一行 `---` 或 `***` 结束函数体,避免后续兄弟语句被吞掉:
```markdown
# main
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello, `谁`!
---
## 下一个函数
...
```
> `---` 仅在**函数体顶层单独一行**时表示「结束本函数」;文件开头的成对 `---` 是 frontmatter,不会混淆。
## 6.6 完整示例
```markdown
# main
> 问候 谁=Alice 礼貌=True
## 问候
+ `谁`
+ `礼貌`=False
1. `礼貌`
> print text=您好,`谁`!
2. *
> print text=嗨,`谁`!
---
## 加一
+ `n`
**n + 1**
```
输出:
```text
您好,Alice!
```
## 6.7 函数嵌套(标题深度)
嵌套辅助函数用更深的标题:
```markdown
# main
> 处理 名字=小明
## 处理
+ `名字`
*上 = > 大写 文本=`名字`*
> print text=`上`
### 大写
+ `文本`
**> str `文本`**
```
> 深度约定:`##` 是 `#` 的子级,`###` 是 `##` 的子级……按标题深度嵌套。
## 6.8 下一步
你已经会封装函数了。接下来学习[第 7 章:条件分支](./07-条件分支.md)。
+138
View File
@@ -0,0 +1,138 @@
# 第 7 章:条件分支
## 7.1 基本分支:`1.` `2.` …
Marqdo 用**有序列表** `1.` `2.` `3.` … 表达条件分支:
```markdown
# main
*n = 5*
1. `n` > 0
> print text=正数
2. `n` < 0
> print text=负数
3. *
> print text=零
```
- `1. 条件` —— 第一个分支(条件为真时执行其下的缩进行)
- `2. 条件` —— 第二个分支
- `3. *` —— else 臂(`N. *` = 否则)
输出:
```text
正数
```
## 7.2 else 臂:`N. *`
在 `1.` 之后的任意臂上,**整行恰为 `*`** 表示 else:
```markdown
*age = 15*
1. `age` >= 18
> print text=成年
2. *
> print text=未成年
```
## 7.3 布尔分支
```markdown
*is_admin = False*
1. `is_admin`
> print text=管理员
2. *
> print text=普通用户
```
## 7.4 多条件分支
```markdown
*score = 85*
1. `score` >= 90
> print text=优秀
2. `score` >= 80
> print text=良好
3. `score` >= 60
> print text=及格
4. *
> print text=不及格
```
## 7.5 逻辑组合条件
```markdown
*age = 25*
*has_id = True*
1. `age` >= 18 and `has_id`
> print text=可以进入
2. *
> print text=不能进入
```
## 7.6 多个独立分支语句
**一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`** 会开启**下一条**独立分支语句:
```markdown
# main
*a = True*
*b = False*
1. `a`
> print text=A 为真
2. *
> print text=A 为假
1. `b`
> print text=B 为真
2. *
> print text=B 为假
```
这是**两次独立判断**,不是「四个臂的一个分支」。输出:
```text
A 为真
B 为假
```
> 臂序号在同一分支内递增(`1.` → `2.` → `3.` …);不要在同一分支中途把序号重置为 `1.`。
## 7.7 完整示例:成绩评级
```markdown
# main
*score = 72*
1. `score` >= 90
> print text=评级:A
2. `score` >= 80
> print text=评级:B
3. `score` >= 70
> print text=评级:C
4. `score` >= 60
> print text=评级:D
5. *
> print text=评级:F
```
输出:
```text
评级:C
```
## 7.8 下一步
你已经能根据条件走不同路线了。接下来学习[第 8 章:循环](./08-循环.md)。
+179
View File
@@ -0,0 +1,179 @@
# 第 8 章:循环
## 8.1 遍历循环:`- [项](集合)`
Marqdo 用 `-`(无序列表)表达循环。遍历列表用 `- [项](集合)`:
```markdown
# main
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
- [果](篮子)
> print text=今天吃`果`
```
输出:
```text
今天吃苹果
今天吃梨
今天吃桃
```
- `[果](篮子)` —— 遍历 `篮子` 列表,每个元素绑定到 `果`
- 循环体内用 `` `果` `` 引用元素(独立 `>` 调用中变量要反引号)
反引号形式等价(可混用):
```markdown
- [`果`](`篮子`)
> print text=`果`
```
## 8.2 遍历字典:遍历键
`Map`(字典)用 `- [键](映射)` 遍历**键**:
```markdown
# main
`分类` =
| 苹果 | 黄瓜 |
|------|------|
| 水果 | 蔬菜 |
- [键](分类)
> print text=`键`
```
输出:
```text
苹果
黄瓜
```
> 遍历字典遍历的是键;要取值,用脚注取元(见[第 9 章](./09-集合.md))。
## 8.3 while 循环:`- 条件`
`-` 后直接写条件就是 while 循环:
```markdown
# main
*n = 3*
- `n` > 0
> print text=`n`
*n = n - 1*
```
输出:
```text
3
2
1
```
> 循环体内用 `*…*` 语句更新变量。
## 8.4 嵌套循环
循环可以嵌套:
```markdown
# main
`外层` =
| 项 |
|----|
| A |
| B |
`内层` =
| 项 |
|----|
| 1 |
| 2 |
- [o](外层)
- [i](内层)
> print text=`o``i`
```
输出:
```text
A1
A2
B1
B2
```
## 8.5 循环 + 分支组合
```markdown
# main
`数字` =
| 值 |
|----|
| 1 |
| 2 |
| 3 |
| 4 |
- [n](数字)
1. `n` >= 3
> print text=`n` 是大数
2. *
> print text=`n` 是小数
```
> 循环体里的 `1.` / `2.` 是分支语句(见[第 7 章](./07-条件分支.md)),与 `-` 循环嵌套使用。
## 8.6 完整示例:累计求和
```markdown
# main
`数字` =
| 值 |
|----|
| 1 |
| 2 |
| 3 |
| 4 |
| 5 |
*sum = 0*
- [n](数字)
*sum = sum + n*
> print text=总和:`sum`
```
输出:
```text
总和:15
```
## 8.7 下一步
你已经掌握循环了。接下来学习[第 9 章:集合(表格)](./09-集合.md),深入理解列表、字典与记录。
+203
View File
@@ -0,0 +1,203 @@
# 第 9 章:集合(表格)
Marqdo 用 **GFM 表格**直接构造数据集合。表格的**几何形状**决定值的类型——这是 Marqdo 最有特色的部分:你看到的 Markdown 表格就是数据结构。
## 9.1 绑定一个集合
集合绑定用「空右侧赋值 + 表格」:
```markdown
`名字` =
| 表头1 | 表头2 |
|-------|-------|
| 值 | 值 |
```
表格绑定变量名**需要反引号**(不在 `*…*` 内)。
## 9.2 单列竖表 → 列表(List)
**恰好 1 列** → 列表:
```markdown
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
```
等价于 `["苹果", "梨", "桃"]`。表头 `果` 是元素逻辑名(foreach 绑定名),**不进入列表元素**。
```markdown
- [果](篮子)
> print text=`果`
```
## 9.3 多列 + 一行 → 字典(Map)
**≥2 列 + 恰好 1 行数据** → 字典,键 = 表头:
```markdown
`分类` =
| 苹果 | 黄瓜 |
|------|------|
| 水果 | 蔬菜 |
```
等价于 `{"苹果": "水果", "黄瓜": "蔬菜"}`。
## 9.4 多列 + 多行 → 字典套列表
**≥2 列 + ≥2 行数据** → 字典,值为该列的列表(列向聚合):
```markdown
`货架` =
| 苹果 | 黄瓜 |
|------|------|
| 红富士 | 青瓜 |
| 嘎啦 | 黄瓜条 |
```
等价于:
```text
{"苹果": ["红富士", "嘎啦"], "黄瓜": ["青瓜", "黄瓜条"]}
```
## 9.5 行向记录表 → 记录列表
首列表头为 `@` / `行` / `row` 时,整表改为**行向**(SQL/CSV 风格):
```markdown
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |
```
等价于:
```text
[{"品名": "苹果", "数量": 2}, {"品名": "梨", "数量": 3}]
```
标记列(`行`)不进入记录字段。
## 9.6 表格形状速查
| 形状 | 值类型 |
|------|--------|
| 1 列 | `List` |
| ≥2 列 + 1 行 | `Map`(标量值) |
| ≥2 列 + ≥2 行 | `Map`(值均为 `List`) |
| ≥2 列 + 0 行 | `Map`(键存在,值空列表) |
| 首列 `@`/`行`/`row` | `List` of `Map`(行向记录) |
## 9.7 脚注取元:`[^…]`
用 Markdown 脚注外形从集合取元素(**表达式级**,可链式)。
### 从列表按下标取
**下标是 1-based**(与人类读表一致):
```markdown
*第一 = 篮子[^1]*
> print text=`第一` # 苹果
```
### 从字典按键取
```markdown
*种 = 分类[^苹果]*
> print text=`种` # 水果
```
### 嵌套取元
```markdown
*第一种苹果 = 货架[^苹果][^1]* # 先键,再下标 → 红富士
```
### 基名的反引号
`` 名[^键] `` 与 `` `名`[^键] `` 等价(紧跟 `[^` 时可省略反引号):
```markdown
*种 = `分类`[^苹果]*
```
### 插值中的取元
在**调用实参值 / 引号字符串**里,`` `变量` `` 后**紧跟**(无空白)`[^…]` 时也按取元解析,而不必先绑定再输出:
```markdown
> print text=苹果单价:`水果价格`[^苹果] # 输出:苹果单价:5
> print text=第一种:`货架`[^苹果][^1] # 链式取元 → 红富士
> print text="价 `水果价格`[^香蕉] 元" # 引号字符串内也可取元 → 价 3 元
```
> 规则:`` `变量` [^…] ``(**有空白**)时 `[^…]` 仍是普通文本;只有 `` `变量`[^…] ``(无空白)才算取元。
> 规则:
> - **List**:标签须为纯数字(1-based);`[^0]` 或越界 → 报错。
> - **Map**:标签为键文本(含纯数字键,如 `[^00]`);缺键 → 报错。
> - 文末的 `[^1]: …` 定义块仍是注释,与取元无关。
## 9.8 表格单元格是表达式
数据单元格支持表达式(与调用实参值语法相同):裸词、数字、`` `var` ``、算术、引号串。URL / `gpt-4o-mini` 等按路径/连字符折叠为文本。
```markdown
*k = "secret"*
`cfg` =
| api_key | model |
|---------|-------|
| `k` | gpt-4o-mini |
```
## 9.9 完整示例
```markdown
# main
`水果价格` =
| 苹果 | 香蕉 |
|------|------|
| 5 | 3 |
> print text=苹果单价:`水果价格`[^苹果]
`购物单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 香蕉 | 3 |
- [行](购物单)
> print text=`行`[^品名] × `行`[^数量]
```
输出:
```text
苹果单价:5
苹果 × 2
香蕉 × 3
```
## 9.10 下一步
你已经掌握 Marqdo 的数据组织了。接下来学习[第 10 章:对象与方法](./10-对象与方法.md)。
+195
View File
@@ -0,0 +1,195 @@
# 第 10 章:对象与方法
Marqdo 用 `#` 标题定义**对象 / 类型**,用 `##` 定义其下的**方法**。这是一种轻量、可读的面向对象写法。
## 10.1 定义对象(类型)
`#`(恰好一层)定义一个对象 / 类型,其正文是**构造体**:
```markdown
# 大模型
+ `模型名`
*配置 = > json.parse text={"model":"gpt-4o-mini"}*
**配置**
```
- `# 大模型` —— 类型名
- `+ `模型名`` —— 构造参数
- 构造体执行后 `**…**` 返回一个 map,运行时写入 `_type` 字段,形成实例句柄
## 10.2 构造实例
调用类型名即可构造实例:
```markdown
# main
*模型 = > 大模型 模型名="gpt-4o-mini"*
```
## 10.3 定义方法
对象下的 `##` 标题是方法:
```markdown
# 计数器
+ `初始值`
*状态 = > json.parse text={"n":0}*
*状态 = > json.set map=`状态` key="n" value=`初始值`*
**状态**
## 加一
*n = > json.get value=`self` key="n"*
*n2 = n + 1*
*t = > json.set map=`self` key="n" value=`n2`*
**t**
```
方法体内自动绑定:
- `self`(英文)
- `自`(中文)
二者是同一个接收者,指向当前实例。
## 10.4 调用方法
### 独立 `>` 调用(接收者加反引号)
```markdown
*计数器 = > 计数器 初始值=3*
*新值 = > `计数器`.加一*
```
### `*…*` 段内调用(接收者裸名)
```markdown
*计数器 = > 计数器 初始值=3*
*新值 = > 计数器.加一*
```
> **重要**:在 `*…*` / `**…**` 段内,裸词是变量,所以**方法接收者不加反引号**:`*新值 = > 计数器.加一*`。而在独立 `>` 调用中,裸词是文本,接收者需要反引号:`> `计数器`.加一`。
## 10.5 完整对象示例
对象(`#`)定义在**顶层**,与 `# main` 平级:
```markdown
---
import json:lib/json.mq.md
---
# main
*c = > 计数器 初始值=5*
*ty = > json.get value=`c` key="_type"*
> print text=类型:`ty`
*c2 = > c.加一*
*n = > json.get value=`c2` key="n"*
> print text=加一后:`n`
# 计数器
+ `初始值`
*状态 = > json.parse text={"n":0}*
*状态 = > json.set map=`状态` key="n" value=`初始值`*
**状态**
## 加一
*n = > json.get value=`self` key="n"*
*n2 = n + 1*
*t = > json.set map=`self` key="n" value=`n2`*
**t**
```
输出:
```text
类型:计数器
加一后:6
```
## 10.6 继承:`# Child = > Parent`
```markdown
# Greeter
## hello
+ `who`
*msg = "Hello, `who`!"*
**msg**
# Loud = > Greeter
## hello
+ `who`
*msg = "HELLO, `who`!"*
**msg**
```
规则:
| 规则 | 说明 |
|------|------|
| 语法 | `# Child = > Parent` |
| `_type` | 构造后仍为**最具体子类名** |
| 方法查找 | 先子类 `##`,未命中再沿基类链;同名则子类覆盖 |
| 构造 | **不**隐式调用父构造(无 auto-super) |
| 多继承 | 不支持 |
### 显式调用父构造
子类需要父字段时,在子类正文首行显式调用父构造:
```markdown
# Child = > Parent
+ `name`
*self = > Parent name=`name`*
*self = > json.set map=`self` key="role" value="child"*
**self**
```
## 10.7 完整继承示例
```markdown
# main
*c = > Child name="Ada"*
*ty = > json.get value=`c` key="_type"*
*role = > json.get value=`c` key="role"*
> print text=`ty`
> print text=`role`
# Parent
+ `name`
*out = > json.parse text={"role":"parent"}*
*out = > json.set map=`out` key="name" value=`name`*
**out**
# Child = > Parent
+ `name`
*self = > Parent name=`name`*
*self = > json.set map=`self` key="role" value="child"*
**self**
```
输出:
```text
Child
child
```
## 10.8 下一步
你已经会面向对象编程了。接下来学习[第 11 章:模块与导入](./11-模块与导入.md),组织大型项目。
+175
View File
@@ -0,0 +1,175 @@
# 第 11 章:模块与导入
大型项目需要把代码拆成多个文件。Marqdo 用 **frontmatter 导入**和**点号寻址**组织模块。
## 11.1 Frontmatter 元信息
文件开头的成对 `---` 之间是 frontmatter,存放元信息(标题、描述、导入):
```markdown
---
title: 我的程序
description: 描述文字
---
```
## 11.2 导入文件:`import 绑定:路径.mq.md`
```markdown
---
import text:lib/text.mq.md
import time:lib/time.mq.md
---
```
- `text` —— 绑定名(本地库名)
- `lib/text.mq.md` —— 目标文件路径
导入后得到一个**库(模块)绑定**,成员**不会**倒进全局。
中文等价:`导入 文本:lib/文本.mq.md`。
## 11.3 点号寻址调用:`库.成员`
导入后用裸点号路径调用库成员:
```markdown
---
import time:lib/time.mq.md
import json:lib/json.mq.md
---
# main
*t = > time.now_unix*
*s = > time.format unix=`t` pattern="%Y-%m-%d"*
> print text=`s`
```
- `time.now_unix` —— 调用 `time` 库的 `now_unix` 函数
- `time.format` —— 调用 `time` 库的 `format` 函数
**库名不是变量**:路径段是裸标识符,不加反引号。
## 11.4 三段路径:`库.类型.方法`
```markdown
---
import agent:ext/ai/agent.mq.md
---
# main
*助手 = > agent.agent model="gpt-4o-mini"* # 库 → 类型:构造
```
`agent.agent` —— `agent` 库中的 `agent` 类型(构造)。
## 11.5 短名:`import 绑定:库.成员`
把库路径成员绑为本地短名:
```markdown
---
import time:lib/time.mq.md
import fmt:time.format
---
# main
*t = > time.now_unix*
*s = > fmt unix=`t` pattern="%Y-%m-%d"*
```
`fmt` 现在是 `time.format` 的短名。
## 11.6 方法调用 vs 库路径(Python 统一命名空间)
对裸点号 `a.b`,规则是:
- 若 `a` 是当前作用域的**局部变量** → **方法调用**(`a` 为接收者)
- 否则 → **库路径**
| 写法 | 含义 |
|------|------|
| `time.parse` | 库路径(裸名,第一段非变量) |
| `` > `助手`.step `` | 独立 `>` 调用:实例方法(接收者反引号) |
| `*回复 = > 助手.step …*` | `*…*` 段内:`助手` 是变量 → 实例方法;否则 → 库路径 |
```markdown
---
import agent:ext/ai/agent.mq.md
---
# main
*助手 = > agent.agent model="gpt-4o-mini"*
*out = > 助手.step task="你好"* # 助手是变量 → 方法调用
```
## 11.7 完整示例:多模块程序
假设项目结构:
```text
project/
├── main.mq.md
├── lib/
│ ├── 数学.mq.md
│ └── 问候.mq.md
```
`lib/数学.mq.md`:
```markdown
## 加倍
+ `n`
**n * 2**
```
`lib/问候.mq.md`:
```markdown
## 你好
+ `谁`
> print text=你好,`谁`!
```
`main.mq.md`:
```markdown
---
import 数学:lib/数学.mq.md
import 问候:lib/问候.mq.md
---
# main
*结果 = > 数学.加倍 n=21*
> print text=`结果`
> 问候.你好 谁=世界
```
输出:
```text
42
你好,世界!
```
## 11.8 库路径解析
`lib/…` 按以下顺序解析:
1. 环境变量 `MARQDO_LIB`
2. 当前目录下的 `lib/`
3. `marqdo` 可执行文件旁边的 `lib/`(及几个父目录)
官方扩展(`ext/`)用 `marqdo ext add llm|agent|web|quantum` 安装,导入仍写 `import llm:ext/llm.mq.md` 等。
## 11.9 下一步
你已经能组织大型项目了。接下来学习[第 12 章:标准库](./12-标准库.md),使用官方能力。
+157
View File
@@ -0,0 +1,157 @@
# 第 12 章:标准库
Marqdo 内置函数无需导入即可使用;更丰富的能力通过导入 `lib/` 模块获得。
## 12.1 内置函数(无需导入)
| 英文 | 中文 | 作用 |
|------|------|------|
| `print` | `打印` | 写标准输出(参数 `text` ≡ `内容`) |
| `input` | `输入` | 读一行(参数 `prompt` ≡ `提示`) |
| `len` | `长度` | 文本 / 集合长度(参数 `value` ≡ `值`) |
| `str` | `文本` | 转为显示文本(参数 `value` ≡ `值`) |
| `int` | `整数` | 转为整数(参数 `value` ≡ `值`) |
```markdown
# main
> print text=Hello
*s = "Marqdo"*
*n = > len value=`s`*
> print text=长度:`n`
```
## 12.2 标准库模块
导入一个 `lib/` 文件,使用**该文件**的函数名:
| 英文导入 | 中文导入 | 典型功能 |
|----------|----------|----------|
| `lib/text.mq.md` | `lib/文本.mq.md` | 文本处理(去空白、拆分、拼接) |
| `lib/table.mq.md` | `lib/表.mq.md` | 列表 / 字典元素更新 |
| `lib/fs.mq.md` | `lib/文件.mq.md` | 文件系统 |
| `lib/sys.mq.md` | `lib/系统.mq.md` | 进程 / 当前目录 / 加载环境变量 |
| `lib/plugin.mq.md` | `lib/插件.mq.md` | 加载原生 ABI 插件 |
| `lib/time.mq.md` | `lib/时间.mq.md` | 时间 / 格式化 |
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) |
| `lib/json.mq.md` | — | JSON 解析 / 序列化 / 取元 |
| `lib/math.mq.md` | `lib/数学.mq.md` | 数值、三角函数、随机、公式、绘图 |
| `lib/foreign.mq.md` | `lib/外联.mq.md` | 运行异种语言代码块 |
> **语言一致性**:导入英文库文件,就用其英文 API;导入中文库文件,就用其中文 API。不要混用语言。
## 12.3 JSON 模块示例
```markdown
---
import json:lib/json.mq.md
---
# main
*obj = > json.parse text={"a":1}*
*a = > json.get value=`obj` key="a"*
> print text=`a` # 1
*out = > json.stringify value=`obj`*
> print text=`out` # {"a":1}
```
`json` 常用函数:
| 函数 | 作用 |
|------|------|
| `json.parse` | 解析 JSON 文本 |
| `json.stringify` | 序列化为 JSON 文本 |
| `json.get` | 取字段(键) |
| `json.keys` | 取所有键 |
| `json.set` | 设字段 |
| `json.append` | 向列表追加 |
## 12.4 文本模块示例
```markdown
---
import text:lib/text.mq.md
---
# main
*parts = > text.str_split s="a,b,c" sep=","*
> print text=`parts`
*joined = > text.str_join xs=`parts` sep="-"*
> print text=`joined` # a-b-c
```
## 12.5 数学模块:公式与绘图
```markdown
---
import math:lib/math.mq.md
---
# main
*值 = > math.num value=3.5*
> print text=`值`
```
公式绑定:
```markdown
---
import math:lib/math.mq.md
---
# main
`f` =
$$
x^2 - 2
$$
*_svg = > math.plot formula=`f` var=x min=-3 max=3*
```
空 RHS 赋值 + 后随 `$$…$$` 绑定一个公式值。
## 12.6 官方扩展库(`ext/`)
扩展库不是 stdlib,需安装:
```bash
marqdo ext list
marqdo ext add llm
marqdo ext add agent
marqdo ext add web
marqdo ext add quantum
```
导入仍写 `import …:ext/….mq.md`:
```markdown
---
import llm:ext/llm.mq.md
---
# main
*模型 = > llm.llm model="gpt-4o-mini"*
```
| 扩展 | 功能 |
|------|------|
| `llm` | 大模型对话 |
| `agent` | 文档驱动的智能体框架 |
| `web` | Web 应用 |
| `quantum` | 量子电路模拟 |
## 12.7 查看库的精确 API
打开 `lib/` 或 `ext/` 下对应的 `.mq.md` 文件,即可看到精确的 `##` / `#` 名称和参数。例如 `lib/json.mq.md` 顶层就是 `## parse`、`## stringify` 等。
## 12.8 下一步
你已经会使用标准库了。最后一章学习[第 13 章:命令行工具](./13-命令行工具.md)。
+111
View File
@@ -0,0 +1,111 @@
# 第 13 章:命令行工具
Marqdo 提供一组命令行工具,覆盖运行、浏览、调试、发布全流程。
## 13.1 命令总览
```text
marqdo --version # 查看版本
marqdo run 文件.mq.md # 运行程序
marqdo view 路径 # 文档浏览器(默认端口 7429)
marqdo debug 路径 # 调试界面(默认端口 7430)
marqdo catalog 路径 -o 目录 # 生成 OKF 风格清单
marqdo sync 路径 -o 目录 # catalog 的别名
marqdo ext list # 列出扩展
marqdo ext add llm|agent|web|quantum
marqdo ext remove llm|agent|web|quantum
```
## 13.2 运行程序:`run`
```bash
marqdo run hello.mq.md
```
指定后端(树遍历默认 / 字节码):
```bash
marqdo run hello.mq.md --backend bytecode
```
### 错误诊断
诊断信息格式:`path:line:col: message`(行 / 列从 1 开始)。
```text
error: hello.mq.md:5:1: undefined variable `x`
```
根据 `path:line:col` 定位并修复,再重新运行直到退出码为 0。
## 13.3 文档浏览器:`view`
`view` 启动一个本地文档浏览器,把 `.mq.md` 渲染成可浏览的文档站:
```bash
marqdo view public --no-open
```
浏览器打开后可看到:
- Structure(结构)
- 函数大纲 / 搜索
- Execution(执行)
- Variables(变量浮窗)
## 13.4 调试器:`debug`
```bash
marqdo debug public --no-open
```
提供独立调试页面,支持:
- 断点
- 单步执行
- 局部变量查看
## 13.5 生成清单:`catalog` / `sync`
从源码派生 OKF 风格的 YAML / Markdown 知识包:
```bash
marqdo catalog public -o .marqdo
# 或
marqdo sync public -o .marqdo
```
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
| `-o` / `--out` | `.marqdo` | 输出目录 |
产物:`catalog.yaml`、`index.md`、`modules/*.md` 等。
## 13.6 扩展管理:`ext`
```bash
marqdo ext list
marqdo ext add llm
marqdo ext add agent
marqdo ext remove llm
```
扩展默认安装到 `~/.marqdo/ext`(或 `MARQDO_EXT`)。
## 13.7 标准库与可执行文件解析
- **标准库**:内置于二进制;磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。
- **库路径解析**:`MARQDO_LIB` → 当前目录 `lib/` → 可执行文件旁 `lib/`。
## 13.8 下一步
恭喜!你已经完成了 Marqdo 语法教程。你现在可以:
- 写出带输入输出、函数、分支、循环的程序
- 用表格组织列表、字典、记录
- 用对象和方法做面向对象编程
- 拆分模块、使用标准库和扩展
- 用命令行工具运行、调试、发布
祝你在「代码即文档」的世界里愉快!
+93
View File
@@ -0,0 +1,93 @@
# Marqdo 语法教程
> **代码即文档,文档即代码。** Marqdo 把 Markdown 的标记当作编程语法:同一个 `.mq.md` 文件既是给人读的文稿,也是给机器跑的程序。
本教程面向所有读者——从没写过代码的文档作者,到熟悉 Python 的工程师。每章都配有可直接运行的完整示例。
## 目录
### 第一部分 · 入门
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 1 章:Marqdo 是什么](./01-入门.md) | 理念、安装、第一个程序、运行 | 写出并运行你的第一个 `.mq.md` 程序 |
| [第 2 章:基本语法](./02-基本语法.md) | 文件结构、注释、标识符、字面量 | 看懂 `.mq.md` 里哪些是代码、哪些是注释 |
### 第二部分 · 变量与数据
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 3 章:变量与赋值](./03-变量与赋值.md) | 绑定、变量引用、字符串 | 存取值,拼接文本 |
| [第 4 章:输出与输入](./04-输出与输入.md) | `print` / `打印`、`input` / `输入` | 与用户交互 |
| [第 5 章:运算符与比较](./05-运算符与比较.md) | 算术、比较、逻辑 | 计算与判断 |
### 第三部分 · 流程控制
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 6 章:函数](./06-函数.md) | 定义、参数、返回值、函数结束 | 封装可复用逻辑 |
| [第 7 章:条件分支](./07-条件分支.md) | `1.` `2.` 分支、else | 让程序根据条件走不同路线 |
| [第 8 章:循环](./08-循环.md) | `-` 遍历、`-` while | 重复执行 |
### 第四部分 · 数据集合
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 9 章:集合(表格)](./09-集合.md) | 列表、字典、记录、脚注取元 | 用 Markdown 表格组织数据 |
### 第五部分 · 面向对象与模块
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 10 章:对象与方法](./10-对象与方法.md) | `#` 类型、构造、方法、继承 | 面向对象编程 |
| [第 11 章:模块与导入](./11-模块与导入.md) | frontmatter、import、库路径、短名 | 组织大型项目 |
### 第六部分 · 进阶
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 12 章:标准库](./12-标准库.md) | 内置函数、`lib/` 模块 | 直接使用官方能力 |
| [第 13 章:命令行工具](./13-命令行工具.md) | `run` / `view` / `debug` / `catalog` | 运行、浏览、调试、发布 |
---
## 快速示例
一个完整的 Marqdo 程序长这样:
```markdown
# main
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello, `谁`!
---
## 加一
+ `n`
**n + 1**
```
- `# main` —— 入口
- `> 问候 谁=World` —— 调用函数(具名参数)
- `## 问候` + `+ `谁`` —— 定义函数及其参数
- `> print text=…` —— 输出(副作用,是普通函数)
- `**n + 1**` —— 返回值
- 单独一行 `---` —— 结束函数体
---
## 运行方式
```bash
marqdo run 文件.mq.md
```
更多运行、浏览、调试、发布方式见 [第 13 章](./13-命令行工具.md)。
> **提示**:语法宪法与精确定义见 [`doc/design/markdown-mapping.md`](../design/markdown-mapping.md);本教程是它的通俗讲解版。