Files
marqdo/doc/tutorial/README.md
cflmy aeb5a2a43d docs(tutorial): 新增《常见陷阱手册》,并补 D8–D10、按实测收敛 D3
把 qdagent 重构期间踩到的坑整理成**使用向**手册 doc/tutorial/15-常见陷阱.md
(417 行,全部条目在 1.5.2 逐条实测,含现象/原因/改法三段式与提交前自查清单)。

手册要点:
- §1 写文档:行首数字必报错(2026 年 / 42 条 / 3 个要点 都中招);
  行首 + 报错;未闭合引号静默吞行(最危险)
- §2 变量作用域:模块级变量在 # main 与各 ## 之间不可见;
  顶层不许裸语句;table.put 不原地修改
- §3 函数:函数名含空格时定义成功但调用必崩
- §4 字符串:引号内 ** / | / # 实为安全,只有引号不配对才出事
- §5 导入:相对路径以当前文件为基准;标准库必须带库名前缀
- §6 易记错的函数签名(txt.contains 的 sub、table.put 的 in/at/value …)
- §7 结构:# main 体不被 ## 截断;1./2./3. 是 if/elif/else 链
- §8 自查清单(marqdo check + run 双跑)

同步修正缺陷实录 research/qdagent-refactor-defects-2026-10.md:
- D3 收敛:实测证明 - / > / | / [ 在叙述区**安全**,只有行首数字与 +
  会被当语句;判据是「该行能否被解析成完整语句」
- 新增 D8 函数名含空格:定义成功、调用必崩,check 却通过(不对称)
- 新增 D9 未闭合引号静默吞行,退出码 0(静默类最危险)
- 新增 D10 table.put 非原地,累积计数静默失效
- 同步复现清单与变更记录

索引:tutorial/README 增第 15 章;doc/README 增手册与缺陷实录两行。
手册内所有代码示例均实测跑通(含参数传递修法、if 链、标准库前缀)。
2026-10-22 09:46:17 +08:00

102 lines
3.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Marqdo 语法教程
> **代码即文档,文档即代码。** Marqdo 把 Markdown 的标记当作编程语法:同一个 `.mq.md` 文件既是给人读的文稿,也是给机器跑的程序。
本教程面向所有读者——从没写过代码的文档作者,到熟悉 Python 的工程师。每章都配有可直接运行的完整示例。
**现行映射是 markup v0.3**:`**…**` = 代码(赋值 / 调用),`*…*` = 返回;集合取元优先 `[键](集合)`。
## 目录
### 第一部分 · 入门
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 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` | 运行、浏览、调试、发布 |
| [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) | `lib/net`、`ext/web`、鉴权、WebSocket | 构建 HTTP 客户端与网页应用 |
| [第 15 章:常见陷阱](./15-常见陷阱.md) | 行首数字、作用域、空格函数名、导入路径等实测坑 | 避开高频错误,提交前自查 |
---
## 快速示例
一个完整的 Marqdo 程序长这样:
```markdown
# main
礼貌 [问候] World
## 问候
+ `谁`
+ `礼貌`=False
1. `礼貌`
> print text=您好,`谁`!
2. *
> print text=Hello, `谁`!
*None*
## 加一
+ `n`
*n + 1*
```
- `# main` —— 入口
- `礼貌 [问候] World` —— 方括号标记调用(前导词 → `礼貌=True`)
- `## 问候` + `+ `谁`` —— 定义函数及其参数
- `> print text=…` —— 输出(副作用,是普通函数)
- `*n + 1*` —— 返回值(斜体)
- `*None*` —— 无值收束并结束函数体
---
## 运行方式
```bash
marqdo run 文件.mq.md
```
更多运行、浏览、调试、发布方式见 [第 13 章](./13-命令行工具.md)。
> **提示**:语法宪法见 [`doc/design/markdown-mapping-v0.3.md`](../design/markdown-mapping-v0.3.md);本教程是它的通俗讲解版。