把 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 链、标准库前缀)。
102 lines
3.8 KiB
Markdown
102 lines
3.8 KiB
Markdown
# 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);本教程是它的通俗讲解版。
|