diff --git a/doc/tutorial/01-入门.md b/doc/tutorial/01-入门.md new file mode 100644 index 0000000..8f48681 --- /dev/null +++ b/doc/tutorial/01-入门.md @@ -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` 里哪些是代码、哪些是注释,以及标识符的写法。 diff --git a/doc/tutorial/02-基本语法.md b/doc/tutorial/02-基本语法.md new file mode 100644 index 0000000..734a408 --- /dev/null +++ b/doc/tutorial/02-基本语法.md @@ -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 的值存储方式。 diff --git a/doc/tutorial/03-变量与赋值.md b/doc/tutorial/03-变量与赋值.md new file mode 100644 index 0000000..62f8b94 --- /dev/null +++ b/doc/tutorial/03-变量与赋值.md @@ -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),与用户交互。 diff --git a/doc/tutorial/04-输出与输入.md b/doc/tutorial/04-输出与输入.md new file mode 100644 index 0000000..ae558c8 --- /dev/null +++ b/doc/tutorial/04-输出与输入.md @@ -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)。 diff --git a/doc/tutorial/05-运算符与比较.md b/doc/tutorial/05-运算符与比较.md new file mode 100644 index 0000000..9c40b3f --- /dev/null +++ b/doc/tutorial/05-运算符与比较.md @@ -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),把逻辑封装起来复用。 diff --git a/doc/tutorial/06-函数.md b/doc/tutorial/06-函数.md new file mode 100644 index 0000000..ca370e2 --- /dev/null +++ b/doc/tutorial/06-函数.md @@ -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)。 diff --git a/doc/tutorial/07-条件分支.md b/doc/tutorial/07-条件分支.md new file mode 100644 index 0000000..39be034 --- /dev/null +++ b/doc/tutorial/07-条件分支.md @@ -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)。 diff --git a/doc/tutorial/08-循环.md b/doc/tutorial/08-循环.md new file mode 100644 index 0000000..e02557d --- /dev/null +++ b/doc/tutorial/08-循环.md @@ -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),深入理解列表、字典与记录。 diff --git a/doc/tutorial/09-集合.md b/doc/tutorial/09-集合.md new file mode 100644 index 0000000..203cf34 --- /dev/null +++ b/doc/tutorial/09-集合.md @@ -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)。 diff --git a/doc/tutorial/10-对象与方法.md b/doc/tutorial/10-对象与方法.md new file mode 100644 index 0000000..e953848 --- /dev/null +++ b/doc/tutorial/10-对象与方法.md @@ -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),组织大型项目。 diff --git a/doc/tutorial/11-模块与导入.md b/doc/tutorial/11-模块与导入.md new file mode 100644 index 0000000..5dfb4ad --- /dev/null +++ b/doc/tutorial/11-模块与导入.md @@ -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),使用官方能力。 diff --git a/doc/tutorial/12-标准库.md b/doc/tutorial/12-标准库.md new file mode 100644 index 0000000..e69bba4 --- /dev/null +++ b/doc/tutorial/12-标准库.md @@ -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)。 diff --git a/doc/tutorial/13-命令行工具.md b/doc/tutorial/13-命令行工具.md new file mode 100644 index 0000000..5002750 --- /dev/null +++ b/doc/tutorial/13-命令行工具.md @@ -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 语法教程。你现在可以: + +- 写出带输入输出、函数、分支、循环的程序 +- 用表格组织列表、字典、记录 +- 用对象和方法做面向对象编程 +- 拆分模块、使用标准库和扩展 +- 用命令行工具运行、调试、发布 + +祝你在「代码即文档」的世界里愉快! diff --git a/doc/tutorial/README.md b/doc/tutorial/README.md new file mode 100644 index 0000000..6d9484e --- /dev/null +++ b/doc/tutorial/README.md @@ -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);本教程是它的通俗讲解版。